fix(163): reads load the frozen build — contract, red tests, and the canonical-read fix

[paddymul]

What

The full #163 arc: state how the system is supposed to work (docs/system-contract.md), pin it with tests that fail on main, then land the fix that makes the contract true. Design decisions are recorded in plans/adr-read-path-loads-builds.md (D1–D12); the bug-class survey beyond #163's alias axis is plans/cache-soundness-audit.md.

The contract (Part 1: the five xorq ideas tallyman is built on; Part 2: the tallyman primitives; Part 3: the lifecycle; Part 4: invariants I1–I5). The core rule: after a build, the frozen xorq_build/ is the entry's semantics and expr.py is documentation. A content hash names a fixed result; names resolve exactly once, at build.

The red suite — eight tests over the #163 shape (two revisions of one recipe, distinct entries only because their recorded parent moved), each seen failing on CI with its designed assertion across two red waves:

test	invariant / decision	failure on main
cheap historical read uses recorded parent	I1/I4	assert 37 == 200 — serves boots-only rows from the live head
worthy revisions resolve distinct snapshots	I1	both hashes resolve to one snapshot file
untouched entry verifies faithful	I4	verify_result_faithful returns False
diff of two revisions is not a self-join	I5	every n_abs_delta exactly 0.0
cold-cache read reproduces build bytes	I2	heal manufactures head bytes under the historical hash
missing build is a hard error	D6	read silently succeeds off expr.py
chained child's build heals parent, no pre-heal	D4	ValueError: At least one path is required
unfaithful heal wipes the entry's stat cache	D10	stale stats survive beside fresh rows

The fix (ae58484):

• Canonical read (D2/D6): cached_result_expr / baked_snapshot_path internals load the frozen build — ensure_expanded_build → load_expr(cache_dir=compute cache) → portable.rewrite_cache_dirs, a deep cache-dir rewrite that reaches cache nodes nested inside CachedNode.parent (xorq's own rewrite is shallow). A missing or unloadable build raises, naming the entry; there is no recipe fallback.
• Self-contained chaining (D3/D4): tracked_expr_from_alias returns the parent's loaded build with its cache node intact, rebound onto the process default backend under a one-content-profile guard. The ensure_session pre-heal and the build: #73's expression-level from_catalog breaks any entry combining ≥2 catalog parents — 'Multiple backends found' #75 stripping are deleted. Child manifests still record ancestors' source digests so gc_cas keeps a child's CAS leaves alive.
• Canonical-order bake (D5, amended): the result_digest is order-sensitive for parquet-sourced worthy entries — canonical ordering exists only for CSV ingest #171 probe showed the drift fires on every heal at scale (3 heals → 3 distinct digests, 250k rows), so the ADR's escape clause was exercised: worthy expressions are sorted by all sortable columns before the bake (author sort keys stay primary, then original_row_order, then schema order). The probe is now a regression test pinning byte-equality across heals.
• Verification in production (D7/D8/D10/D12): every self-heal verifies against result_digest before serving; a mismatch records a durable unfaithful_heal error (the pin marking and UI badge source), wipes the entry's stat cache, evicts its Buckaroo session, and pushes an SSE event. Builds record snapshot_key; reads assert their derivation matches. catalog_scan_staleness(verify_results=True) sweeps the corpus.

Local: fast suite 690 passed / 0 failed, integration 7 passed, ruff clean.

Rebuild required at landing

Chaining and the canonical sort both change content hashes; per the project's no-migration policy the corpus is rebuilt (and Buckaroo bounced, diff_stat_cache/ wiped) instead of migrated.

Closes #163. Closes #171. Refs #166, #168–#172, buckaroo#955–957.

🤖 Generated with Claude Code