The map

This book is an atlas for someone who wants to rebuild Clay by hand. Every snippet is real output from the repository, not an idealised sketch. Where something is not built, it says so.

Clay source
   │  tree-sitter (strict: any ERROR/MISSING node is a hard error)
   ▼
AST                 mirrors the syntax, still has sugar
   │  lowering (desugar)
   ▼
Core IR             small, sugar-free; the thing that gets hashed
   ├──► kernel term (JSON) ──► Rust kernel (wasm): typecheck + hash     runs in the browser
   └──► Unison text ─────────► UCM: typecheck + hash + run              the oracle, Node only
                                 │
              hashes must agree, or the write is refused
                                 ▼
Store: immutable objects keyed by hash · names per branch · journal · original text

Three ideas carry the whole design:

1. Identity is a hash of the tree. Names are labels stored beside the code, never inside it.
2. The tiny core is the contract. All surface sugar is gone before hashing, so the hash only depends on a few node kinds.
3. Never trust yourself, trust the oracle. Unison’s UCM independently hashes and typechecks every write. A disagreement writes nothing.

We follow one program through every stage:

let add = (a: int, b: int): int => a + b
let twice = (n: int): int => add(n, n)

Read the chapters in order: parsing, Core IR, hashing, typechecking, the oracle and store, the data-type features, then interpreting.