Implement cached (§15)

[janstrakowski]

cached <expr> evaluates an expression once and reads the answer back on every
later run. §15 had pinned the cache key — the expression treated as a
function, hashed as one — but left > TODO: Where does the cache actually live
open. This closes it.

Rebased onto #17. This branch originally carried its own directory and
closure hashing, built as scaffolding. #17 landed the same ground while it
was in flight, and better — decisively, it handles cyclic values, which #16
made constructible and which the version here would have recursed on forever.
All of that is dropped in favour of #17's; what remains is cached and the
pieces #17 does not have.

The key

main hashes a closure as its body's shape plus its captures, which is exactly
right for a Function value — but #arg/#self are dynamic lookups into the
interpreter's stacks, captured by no closure and invisible to free_names.
Left there, let f func (cached (#arg + 1)) gives f 10 the answer 2 — a
wrong value, not a stale cache. cached mixes in the stack entries the
expression can reach, bounded statically by the largest N written in it
(hash_implicit.odin). There is a regression test.

The layout

In ctx.cache's directory (--cache-dir, else the XDG/per-user default), one
entry per key:

<cache>/sha256-<key>                  a File value, stored as itself
<cache>/sha256-<key>.hb/value.hb      anything else, as HashedBuild text
<cache>/sha256-<key>.hb/sha256-<h>    each File inside it, by content hash

A file stays a file and a directory stays a directory, so what a build produced
is still something you can open, diff or copy out. Anything else is written
as HashedBuild's own value syntax, read back by a literals-only parser rather
than import — a hand-edited entry is a parse failure, not code that runs.
Entries commit by rename, which is also how two runs racing on one key settle
it without locking.

Cyclic values are cacheable. A Table reached more than once is written
node "N" { … } at its first occurrence and ref "N" after that:

node "1" { .name = "alice", .friend = node "2" { .name = "bob", .friend = ref "1" } }

The reader creates each Table before reading its entries — exactly as §10's
evaluation order does — so a definition always precedes its references and
nothing needs patching up afterwards. A restored cycle is bisimulation-equal to
the stored one, which is what §6 requires of it. Labels go on merely shared
Tables too: not needed for correctness, since §6 compares structurally, but it
stops a shared value expanding exponentially on the way out.

Also here

• Four fs write operations — mkdir/rename/unlink/rmdir, on all three
  backends. Finish hashing: directories, closures, cycles, and ctx.cache #17 added reading; the store needs writing.
• The executable bit is dropped from §3's directory hash, reversing the
  resolution Finish hashing: directories, closures, cycles, and ctx.cache #17 recorded. Finish hashing: directories, closures, cycles, and ctx.cache #17 cited core.filemode as agreeing; git actually
  does the opposite — it never re-derives the bit on a target that cannot report
  one, because core.fileMode=false carries the mode from the index, so a
  committed 100755 round-trips without ever existing in a Windows working
  tree. Hashing it made one tree two values depending on where it was checked
  out: this repo has four such files, so sha256 loadfile "scripts" answered
  two ways. Remembering the bit instead isn't available to a File — a live
  handle with no index beside it. The cache still restores the bit when copying
  a tree: fidelity in the store, not identity in the language.

Testing

230 tests pass, repeatedly, on Windows; all three targets typecheck.
examples/cached.hb is asserted by the suite like every other example.

Two things I could not run locally, both covered by CI:

• the WASI artifacts — no wasm-ld on this machine, so the backends are
  typechecked for wasi_wasm32 but not linked;
• hash_linux_test.odin, whose assertion inverts with the exec-bit change:
  it now sets the bit, confirms it landed, and asserts the digest is unchanged.

🤖 Generated with Claude Code