test: doc-driven edge-case tests for the reactive system and caching

[paddymul]

What

23 new tests exercising doc-promised edges of the reactive system (staleness axes, recalc cone, auto-recalc) and the caching stack. They were written from docs/reactive-recalc.md, docs/caching.md, docs/architecture.md, docs/expression-lifecycle.md, and docs/mcp-server.md first, then reconciled against the API only — the point is to pin what the docs promise, not what the code happens to do.

20 pass. 3 fail, each documenting a real doc-vs-code hole (failing tests pushed first per the TDD workflow; whether each fix is code-side or doc-side is a design call):

Failing tests (the findings)

1. test_recalc.py::test_explicit_husk_root_is_dropped_from_the_cone — recalc: superseded historical entries treated as live — cascade replays them (manufactured junk entries) and orphan-classifier flags them "UNEXPLAINED / file a bug" #154 head-gated the scan-driven root set and cone membership, but an explicitly-passed husk root bypasses the gate: recalc(project, [husk], dry_run=False) replays the superseded version. Under source drift the replay mints a junk sibling entry of the live head — the same junk-replay shape recalc: superseded historical entries treated as live — cascade replays them (manufactured junk entries) and orphan-classifier flags them "UNEXPLAINED / file a bug" #154 fixed on the scan-driven path. mcp-server.md says "Roots naming no live entry are silently dropped"; the scan's own live=False verdict for the husk says it should be.

2. test_recalc.py::test_scratch_follower_rebuilds_with_remap_but_no_alias_revision — reactive-recalc.md: a rebuilt entry with no alias ("an unnamed scratch entry") "produces a new hash and a remap entry but zero alias revisions". In practice the head-gate marks a never-aliased catalog_run follower live=False, so it is never actionably stale (stale=False even with the alias reason recorded) and never recalcs. Either the gate should treat never-aliased scratch entries as live, or the doc's scratch-rebuild semantics are dead and should say so.

3. test_recalc.py::test_alias_pin_is_not_silently_advanced_by_a_replay — the docs promise a pin (by alias or hash) means the child "stays on that exact revision" and is "never disturbed by recalc". True when the pin is the child's only edge; but a child with one tracked parent and one alias-pinned parent gets replayed when the tracked parent advances, and the replay re-runs pinned_expr_from_alias("p"), which re-resolves the name to p's new head — the pin silently advances. Hash pins are immune. Fix is either replay-time pin freezing or a doc caveat ("pin by hash if you need replay durability").

Passing tests worth a note

• test_revise_carry_over.py::test_cascade_carries_chart_to_rebuilt_follower — cascade carry-forward of chart/display config works but is undocumented (caching.md only names catalog_revise/put_code as carry-forward callers).
• test_staleness.py::test_inplace_edit_preserving_mtime_and_size_is_detected — the "forces a faithful re-read" claim holds even when the edit preserves mtime and byte length (the stat-keyed memo's blind spot).
• test_staleness.py::test_cheap_parent_sources_inline_into_child_and_both_go_directly_stale / test_expensive_parent_shields_child_from_source_axis — the cheap-inline vs expensive-shield source-axis behavior, including the doc's checkable invariant (child sources ⊇ cheap parent sources).
• test_recalc.py::test_diamond_join_child_rebuilds_once_against_both_new_parents / test_diamond_failure_skips_the_join_child — diamond replay: join child rebuilds once against both advanced heads; stop-and-report skips it when an arm fails.
• test_recalc.py::test_empty_roots_list_recomputes_nothing — roots=[] is an explicit empty selection, not a falsy fallback to the stale set.
• test_source_identity.py::test_salt_mode_bakes_no_snapshot_and_reads_still_work / test_salt_rebuild_over_edited_source_forks_hash — first coverage of salt mode's documented behavior.
• test_auto_recalc.py::test_revise_identical_code_keeps_version_and_cascades_nothing — byte-identical revise dedupes: same hash, still version 1, empty cascade.

Doc inconsistencies found during the review (no test possible / already covered)

• reactive-recalc.md "Current limits" says the SPA does not consume the recalc SSE event; architecture.md says it does (and auto-recalc-on-revise.md's currency note confirms the listener shipped). reactive-recalc.md is stale.
• expression-lifecycle.md step 5 says a cheap entry records a result_digest via count_and_result_digest; architecture.md (and test_cheap_entry_records_no_digest) say worthy-only. expression-lifecycle.md predates ADR: result digest as row-multiset + canonical snapshot ordering #137.
• caching.md's closing section still describes the source-identity: digest-pinned reconstruction — cas flip (#86) does not make cold reads content-faithful; #74 hazard survives #115 cold-reconstruction hole as open; architecture.md and the test_cas_* reconstruction-pinning tests show digest-pinned reconstruction shipped. Same staleness in test_source_identity.py's module docstring.
• reactive-recalc.md's scan schema: reasons[].now is "null if the input is gone" contradicts the same section's "an axis that can't be evaluated … lands in unknown_axes" — in practice a gone input produces no reason at all, and unknown_axes holds axis-qualified refs ("alias:base", "source:orders.parquet"), with the bare axis name reserved for a wholly-unevaluable axis (off mode). The doc implies bare names.
• reactive-recalc.md omits orphan_stale from the scan return shape (mcp-server.md has it) and doesn't document recalc: superseded historical entries treated as live — cascade replays them (manufactured junk entries) and orphan-classifier flags them "UNEXPLAINED / file a bug" #154 head-gating/husk semantics at all ("the scan classifies every live entry" predates the live flag).

🤖 Generated with Claude Code