Make let rec build cyclic data, and compare it by bisimulation

[janstrakowski]

SPEC.md §6 has always said cycles are possible; nothing could construct one. A let rec over a Table literal now can, so a social graph whose friendships are mutual is expressible — without a placeholder type, a lazy keyword, or a second binding form.

let rec people {
  .alice = { .name = "Alice", .friends = { people.bob, people.carol } },
  .bob   = { .name = "Bob",   .friends = { people.alice } },
  .carol = { .name = "Carol", .friends = { people.alice, people.bob } },
};
people.alice.friends[1].friends[1].name        // => "Alice", back where we started

How

The mechanism is evaluation order, not deferral.

• The Table is created and bound to the name before any entry runs, so an entry can mention the Table it belongs to.
• Entries are evaluated on demand rather than in source order. Reaching people.bob while .alice is mid-flight evaluates .bob there and then. That dissolves every dependency between entries that has a topological order — which is why mutual references need nothing further, and why a form binding several names at once is still not needed.
• What survives is the residual true cycle: .bob reaching back into .alice, already in progress and so with no value to give. Only that yields a forward reference (src/rec_build.odin), filled the moment .alice completes. Storing one makes the back-edge; inspecting one before it is filled is a circular definition and fails, naming the entry. Every entry completes before the let rec returns, so no finished value can hold an unfilled one — which is why this is not one of §3's types.

Scope is deliberately narrow, and the docs say so. This builds cyclic structures — finite graphs with back-edges — not unbounded ones: a stream constructing a fresh node per step still recurses to the nesting budget. Only a Table literal written directly as the bound value has entries to reorder; let rec x x + 1 still reports undefined name.

What then has to cope with a graph rather than a tree

• Equality is bisimulation. Two rings of the same shape built by separate bindings are the same value — §6 makes equality a question about content, and a pointer comparison would answer it wrongly. Assumptions live in a union-find with path compression (Downey–Sethi–Tarjan congruence closure), keeping it near-linear rather than the quadratic a visited-pair set would cost. The map is created only when two distinct Tables are first assumed equal, so scalar key lookup on the hot path of field access still allocates nothing.
• Printing labels the node a back-edge returns to — #1{n: 1, self: #1} — so output stays finite and the shape is legible. Acyclic values, including a sub-Table merely shared between two branches, print byte-identically to before.

Reviewer notes

Two decisions worth a second opinion:

1. Hashing a cyclic value is refused, not implemented — sha256 of one fails cleanly rather than hanging, alongside the existing directory-File and Function gaps. §3 pins what a digest encodes, so choosing a cyclic encoding is a spec decision. SPEC.md §6 records what the answer looks like (SCC decomposition, Merkle-fold the acyclic part, canonicalise each component under bisimulation) and LANGUAGE.md lists it as unbuilt. This is the one part of the feature I'd call unfinished.
2. Evaluation order inside a rec Table literal is now dependency order, not source order. It falls out of the design, but it is a "what fails and how" change: where entries have effects — a createfile, a fired async, a failing check — that is the order they happen in, and which failure surfaces first can differ from the source reading. Documented in §10.

The second commit is an audit, not just this feature's loose ends. Three of its six fixes were wrong before this change: §5 claimed a Table's hash sorts entries by §6's generic total order (it sorts by key digest, deliberately, since that ordering isn't built); §5 filed hashing and equality under one heading, reading as though equality were hash-derived when it is structural; and §8 named the nesting constant MAX_EVAL_DEPTH when it has been MAX_NEST_DEPTH throughout.

Testing

• 180 tests pass, 20 new in src/rec_build_test.odin covering the cycle, demand reordering, source-order preservation, both circular-definition failures, bisimulation (equal, unequal, and differing-period cases), labelled printing, and the hash refusal.
• New example examples/cyclic-data.hb, asserted by the suite like every other.
• Every snippet added to LANGUAGE.md and every behavioural claim added to SPEC.md was run against hb before being written down.
• The portable WASI target builds clean, so the new code compiles for wasm32. The threaded WASI build needs clang and the smoke test needs wasmtime, neither installed on the machine this was written on — CI covers both.

🤖 Generated with Claude Code