Merge pull request #155 from buckaroo-data/fix/154-head-reachable-staleness

fix(#154): gate staleness on head-reachability — no husk replay, no false orphans

Author: paddymul

src/tallyman_companion/app.py

@@ -1671,7 +1671,9 @@ def api_staleness(project: str):
         Read-only (no checkpoint). Drives the per-entry staleness badge: ``stale``
         lists directly-stale hashes (their own input moved), ``transitively_stale``
         the clean descendants a recalc would carry, ``entries`` the full verdict
-        map. The SPA fires this on project load / switch and after a recalc.
+        map. Only current alias heads are ``stale`` (#154): a superseded historical
+        version reports ``live=False`` and is never listed — recomputing it re-points
+        no alias. The SPA fires this on project load / switch and after a recalc.
         """
         project = _validate_project(project)
         from tallyman_core.config import auto_recalc_enabled  # noqa: PLC0415

src/tallyman_mcp/server.py

@@ -1029,13 +1029,16 @@ def catalog_scan_staleness() -> dict:
     a followed alias (built with ``tracked_expr_from_alias("name")``) advanced past the
     recorded head, or a recorded source file's content drifted on disk. A
     *directly* stale entry has its own input moved; a *transitively* stale entry
-    is a clean descendant of a stale ancestor. Use ``catalog_recalc`` to act.
+    is a clean descendant of a stale ancestor. Only current alias heads are
+    directly stale (#154): a superseded historical version reports ``live=False``
+    and is never listed, since recomputing it re-points no alias. Use
+    ``catalog_recalc`` to act.
 
     Returns:
         stale: hashes that are directly stale (the natural recalc roots).
         transitively_stale: clean descendants carried by a stale ancestor.
         entries: ``{hash: verdict}`` for every live entry, where a verdict is
-            ``{stale, reasons:[{axis, ref, was, now}], unknown_axes,
+            ``{stale, live, reasons:[{axis, ref, was, now}], unknown_axes,
             transitively_stale}``.
     """
     project = _resolve_active_project()

src/tallyman_xorq/recalc.py

@@ -118,6 +118,25 @@ def _preview_action(content_hash: str, verdict, cone: set[str], dag: dict) -> st
     return "unchanged"  # pinned to an out-of-cone parent, or a non-stale root
 
 
+def _live_cone(cone: list[str], roots: list[str], verdicts: dict[str, StaleVerdict]) -> list[str]:
+    """The cone with dragged-in husks removed (#154). ``descendant_cone`` re-expands
+    from a stale head through *every* recorded parent edge, so a superseded husk that
+    follows that head (via a since-advanced alias) is pulled back in even though the
+    head-gate dropped it from the root set. Replaying such a husk re-resolves its
+    followed alias to the advanced head and manufactures a junk entry that heads no
+    alias and re-points nothing — the f2dd/cb24 regression. Drop every non-head cone
+    member; an explicitly-named root is exempt (a user-supplied root is a deliberate
+    request, not scan-driven drag-in — the revise/recalc defaults never pass one).
+
+    Safe because a *live* entry can depend on a husk only through a ``follow=False``
+    hash pin (nothing can follow a headless husk by name), and a hash pin replays to
+    the same parent whether or not the husk itself was rebuilt — so nothing downstream
+    is stranded by skipping it. Order is preserved, so the topological walk stays valid.
+    """
+    roots_set = set(roots)
+    return [h for h in cone if h in roots_set or verdicts[h].live]
+
+
 def recalc(project: str, roots: list[str], *, dry_run: bool = False) -> RecalcReport:
     """Recompute *roots* and their dependents, in dependency order.
 
@@ -146,6 +165,7 @@ def recalc(project: str, roots: list[str], *, dry_run: bool = False) -> RecalcRe
         # the project), then index into it for the cone. Keeps the staleness
         # semantics in one tested place rather than re-deriving them here.
         verdicts = scan(project)
+        cone = _live_cone(cone, roots, verdicts)  # drop dragged-in husks so preview matches the real walk (#154)
         cone_set = set(cone)
         dag = build_dag(project)
         entries = [
@@ -202,6 +222,7 @@ def _replay_cone(
 
     if verdicts is None:
         verdicts = scan(project)
+    cone = _live_cone(cone, roots, verdicts)  # a husk dragged into a stale head's cone must not replay into junk (#154)
     remap: dict[str, str] = {}
     entries: list[RecalcEntry] = []
     status = "ok"

src/tallyman_xorq/staleness.py

@@ -52,10 +52,11 @@ class StaleReason:
 @dataclass
 class StaleVerdict:
     content_hash: str
-    stale: bool  # directly stale: this entry's own recorded inputs moved
+    stale: bool  # actionably stale: a CURRENT alias head whose own recorded inputs moved
     reasons: list[StaleReason] = field(default_factory=list)
     unknown_axes: list[str] = field(default_factory=list)  # axes that can't be evaluated
     transitively_stale: bool = False  # set by scan(): a directly-stale ancestor exists
+    live: bool = True  # #154: content_hash is a current alias head (set by scan)
 
 
 @contextmanager
@@ -115,20 +116,35 @@ def entry_staleness(project: str, content_hash: str) -> StaleVerdict:
 
 
 def scan(project: str) -> dict[str, StaleVerdict]:
-    """Staleness for every live entry, tagging direct vs transitive staleness.
-
-    A **directly** stale entry has its own recorded input moved. A
-    **transitively** stale entry is a (not directly stale) descendant of one in
-    the dependency cone. The recalc surfaces use this to flag both while
-    distinguishing the entry the user must act on from the ones a cascade carries.
+    """Actionable staleness for every live entry, tagging direct vs transitive.
+
+    An entry is **directly** stale only when it is a *current alias head* whose own
+    recorded input moved (#154). A superseded historical version pins alias heads
+    that have since advanced, so its inputs read as moved forever — but it heads no
+    alias, so recomputing it re-points nothing (and, for a recipe shape no current
+    head uses, manufactures a junk entry), and it is not an invariant break to flag.
+    Such a non-head is marked ``live=False`` and forced ``stale=False`` here (its
+    ``reasons`` are kept for forensics). A **transitively** stale entry is a (not
+    directly stale) descendant of a directly-stale head in the dependency cone.
+
+    ``entry_staleness`` stays the raw per-entry primitive — did *this* entry's inputs
+    move, regardless of headship; this function layers the head-reachability gate
+    that makes ``stale`` mean *actionable*. The verdict dict still keys **every**
+    entry (heads and husks alike), because the recalc replay indexes cone members
+    that are not themselves heads (a hash-pinned child).
     """
+    heads = set(aliases.load_aliases(project).values())  # current alias heads, read once
     verdicts = {
         entry["content_hash"]: entry_staleness(project, entry["content_hash"]) for entry in list_entries(project)
     }
+    for content_hash, verdict in verdicts.items():
+        verdict.live = content_hash in heads
+        if not verdict.live:
+            verdict.stale = False  # a non-head is never actionably stale (#154)
     directly_stale = [h for h, v in verdicts.items() if v.stale]
     if directly_stale:
         for content_hash in descendant_cone(project, directly_stale):
             verdict = verdicts.get(content_hash)
-            if verdict is not None and not verdict.stale:
+            if verdict is not None and verdict.live and not verdict.stale:  # a husk is dead history, not carried (#154)
                 verdict.transitively_stale = True
     return verdicts

tests/test_auto_recalc.py

@@ -21,8 +21,10 @@
 from tallyman_core.config import auto_recalc_enabled, set_auto_recalc
 from tallyman_core.errors import error_for_hash
 from tallyman_core.paths import entry_dir
-from tallyman_mcp.server import catalog_create, catalog_revise
+from tallyman_mcp.server import catalog_create, catalog_recalc, catalog_revise
 from tallyman_xorq.build import list_entries
+from tallyman_xorq.dependents import descendant_cone
+from tallyman_xorq.recalc import followers_of
 from tallyman_xorq.staleness import scan
 
 # ---------------------------------------------------------------------------
@@ -473,3 +475,133 @@ def counting_scan(p):
     monkeypatch.setattr(recalc_mod, "scan", counting_scan)
     catalog_revise("a", _src_code_v2(project))
     assert calls["n"] == 1
+
+
+# ---------------------------------------------------------------------------
+# 10. head-reachability (#154): a SUPERSEDED historical version — a husk that no
+#     alias still heads — is dead history. Its immutable pin to a since-advanced
+#     alias makes it look stale forever, but recomputing it re-points nothing and,
+#     for a recipe shape no current head uses, manufactures a junk entry (the
+#     f2dd/cb24 regression). Staleness is gated on being a current alias head, so
+#     a husk is never a recompute root (followers_of / scan-driven catalog_recalc)
+#     and never a false UNEXPLAINED orphan.
+# ---------------------------------------------------------------------------
+
+
+def _tracked_mutate(parent: str, col: str, mult: int) -> str:  # tracked follower, distinguishing column+graph
+    return (
+        "from tallyman_xorq.io import tracked_expr_from_alias\n"
+        f"t = tracked_expr_from_alias({parent!r})\n"
+        f"expr = t.mutate({col}=t.price * {mult})\n"
+    )
+
+
+def _make_divergent_husk(project) -> tuple[str, str, str]:
+    """leaf@v1; alias ``u`` built on one recipe shape (husk_tag) then REBASED onto a
+    different shape (live_tag). The original ``u`` version is now a superseded husk
+    whose recipe shape no current head uses — replaying it against an advanced leaf
+    yields a novel hash (the divergent-recipe junk). Returns (leaf_v1, husk, live_head)."""
+    leaf1 = _hash(catalog_create("leaf", _src_code(project)))
+    husk = _hash(catalog_create("u", _tracked_mutate("leaf", "husk_tag", 3)))
+    live = catalog_revise("u", _tracked_mutate("leaf", "live_tag", 5))["hash"]
+    assert live != husk and get_alias(project, "u") == live  # u rebased; husk orphaned
+    return leaf1, husk, live
+
+
+def test_revising_leaf_does_not_replay_a_superseded_husk(project, orders_parquet, monkeypatch):
+    # THE f2dd/cb24 REGRESSION. Revising a leaf the husk pins must recompute only
+    # u's live head, not replay the divergent husk into a brand-new junk entry.
+    _clean_env(monkeypatch)
+    _leaf1, husk, live = _make_divergent_husk(project)
+
+    before = {e["content_hash"] for e in list_entries(project)}
+    out = catalog_revise("leaf", _src_code_v2(project))  # auto-recalc cascades from the head advance
+    leaf2 = out["hash"]
+    new_head = get_alias(project, "u")
+
+    assert new_head != live  # u's live head recomputed against the advanced leaf
+    # exactly two new entries — the leaf edit and u's live-head recompute — no junk husk replay
+    new = {e["content_hash"] for e in list_entries(project)} - before
+    assert new == {leaf2, new_head}
+    assert out["recalc"]["remap"] == {live: new_head}  # the husk is not a remap root
+    assert husk not in out["recalc"]["remap"]
+
+
+def test_followers_of_excludes_superseded_husk(project, orders_parquet, monkeypatch):
+    _clean_env(monkeypatch)
+    set_auto_recalc(project, False)  # advance leaf WITHOUT the cascade, to inspect the raw roots
+    _leaf1, husk, live = _make_divergent_husk(project)
+    catalog_revise("leaf", _src_code_v2(project))  # leaf head advances; nothing recomputed
+
+    follows = set(followers_of(project, "leaf"))
+    assert live in follows  # the live head is a genuine recompute root
+    assert husk not in follows  # the dead husk is not
+
+
+def test_scan_excludes_husk_from_stale_but_keeps_it_in_the_dict(project, orders_parquet, monkeypatch):
+    _clean_env(monkeypatch)
+    set_auto_recalc(project, False)
+    _leaf1, husk, live = _make_divergent_husk(project)
+    catalog_revise("leaf", _src_code_v2(project))  # leaf advances; no cascade
+
+    v = scan(project)
+    assert v[live].stale is True  # a current head whose input moved IS actionably stale
+    assert v[husk].stale is False  # the superseded husk is not
+    assert husk in v  # ...but still present in the dict (the replay loop indexes every cone member)
+
+
+def test_superseded_husk_is_not_an_unexplained_orphan(project, orders_parquet, monkeypatch):
+    # The perpetual-false-alarm half: a husk must not fill orphan_stale with
+    # "file a bug", while a genuinely-stale live head with no error still does.
+    _clean_env(monkeypatch)
+    set_auto_recalc(project, False)
+    _second_source(project, "widgets.parquet", seed=1)
+    _leaf1, husk, live = _make_divergent_husk(project)
+    catalog_revise("leaf", _src_code_v2(project))  # leaf advances → husk + live both stale, none recomputed
+    _hash(catalog_create("z", _src_code(project, "widgets.parquet")))  # unrelated alias
+    set_auto_recalc(project, True)
+
+    out = catalog_revise("z", _src_code_v2(project, "widgets.parquet"))
+    orphans = {o["hash"]: o for o in out["recalc"]["orphan_stale"]}
+    assert live in orphans and "UNEXPLAINED" in orphans[live]["explanation"]  # real stale head still flagged
+    assert husk not in orphans  # the husk is no longer a false UNEXPLAINED
+
+
+def test_scan_driven_recalc_does_not_replay_husk(project, orders_parquet, monkeypatch):
+    # The SECOND junk-site: a no-arg catalog_recalc defaults its roots to every
+    # directly-stale entry (server.py), bypassing followers_of. The head-gate must
+    # cover it too, or the husk churns junk here instead of on the revise path.
+    _clean_env(monkeypatch)
+    set_auto_recalc(project, False)
+    _leaf1, husk, live = _make_divergent_husk(project)
+    catalog_revise("leaf", _src_code_v2(project))  # leaf advances; no cascade
+
+    before = {e["content_hash"] for e in list_entries(project)}
+    catalog_recalc(dry_run=False)  # roots default to the scan-driven directly-stale set
+    new = {e["content_hash"] for e in list_entries(project)} - before
+    assert new == {get_alias(project, "u")}  # only u's live-head recompute; no husk junk
+
+
+def test_scan_driven_recalc_does_not_replay_husk_under_source_drift(project, orders_parquet, monkeypatch):
+    # The SOURCE-DRIFT sibling of the test above. Instead of REVISING the leaf
+    # (which advances its head, so the leaf drops out of the root set), drift the
+    # leaf's SOURCE FILE on disk. The leaf HEAD stays a directly-stale root, so
+    # descendant_cone([leaf]) re-expands through the husk's follow=True parent edge
+    # and drags the husk back into the cone. The head-gate lives on the ROOT SET,
+    # not on cone membership, so _replay_cone rebuilds the husk anyway — the
+    # f2dd/cb24 junk-replay regression, on the source-drift path.
+    _clean_env(monkeypatch)
+    set_auto_recalc(project, False)
+    leaf1, husk, _live = _make_divergent_husk(project)
+    write_shoe_orders(data_dir(project) / "orders.parquet", n_rows=200, seed=1)  # drift leaf's source in place
+
+    v = scan(project)
+    assert v[leaf1].stale is True  # leaf head directly stale on the source axis → a recalc root
+    assert v[husk].stale is False and v[husk].live is False  # husk gated out of the root set...
+    assert husk in descendant_cone(project, [leaf1])  # ...but still dragged into the leaf's cone
+
+    before = {e["content_hash"] for e in list_entries(project)}
+    catalog_recalc(dry_run=False)  # roots default to the scan-driven directly-stale set = [leaf]
+    new = {e["content_hash"] for e in list_entries(project)} - before
+    # exactly two new entries — the leaf source-recompute and u's live-head recompute — no junk husk replay
+    assert new == {get_alias(project, "leaf"), get_alias(project, "u")}

tests/test_recalc.py

@@ -134,6 +134,11 @@ def test_alias_advance_cascades_to_the_follower(project, orders_parquet, monkeyp
     # follower b *directly* stale on the alias axis; recalc re-resolves b to the
     # advanced head. b's source is unchanged, so this isolates the alias cascade.
     monkeypatch.setenv("TALLYMAN_SOURCE_IDENTITY", "cas")
+    # Opt out of auto-recalc-on-revise so the revise advances a WITHOUT recomputing
+    # b: otherwise the cascade re-points "b" to a fresh head and b1 becomes a
+    # superseded husk (never actionably stale under #154), not the *live* directly-
+    # stale follower this test means to observe and then recalc explicitly.
+    monkeypatch.setenv("TALLYMAN_AUTO_RECALC", "0")
     a1 = _hash(catalog_create("a", _base_code(project)))
     b1 = _hash(catalog_create("b", _child_code("a")))