feat(#135): reject revisions that reference their own alias; steer toward inline / pin-by-hash

references_own_alias (dependents) detects a parent edge whose ref is the alias being revised. catalog_revise (MCP) and put_code (UI edit) reject such a revise before advancing the alias — recording it so it shows in the activity log — and the catalog_revise docstring now steers toward a self-contained recipe: extend the entry's current code; inline the source for a source-shaped entry, or pin the previous version by hash for an expensive one (lever b + guard).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: paddymul

src/tallyman_companion/app.py

@@ -1542,6 +1542,21 @@ async def put_code(project: str, alias: str, payload: dict):
             rec = _record_error(project, code=code, message=str(exc), tool="api_code")
             await publish({"kind": "build_failed", "error_id": rec["id"], "tool": "api_code"})
             raise HTTPException(400, str(exc))
+        from tallyman_xorq.dependents import references_own_alias  # noqa: PLC0415
+
+        if references_own_alias(project, res.content_hash, alias):
+            from tallyman_core import record_error as _record_error  # noqa: PLC0415
+
+            msg = (
+                f"this revision references its own alias {alias!r}, which makes an opaque, "
+                f"permanently-stale (follows-its-own-head) entry. Write a self-contained recipe: "
+                f"inline the source (read_project_file / read_csv …) for a source-shaped entry, or "
+                f"reference the previous version by hash with pinned_expr_from_alias({prev_hash!r}) "
+                f"for an expensive one."
+            )
+            rec = _record_error(project, code=code, message=msg, tool="api_code")
+            await publish({"kind": "build_failed", "error_id": rec["id"], "tool": "api_code"})
+            raise HTTPException(400, msg)
         info = _set_alias(project, alias, res.content_hash, expect_exists=True)
         # Chart + display config are keyed by content hash; seed the new version
         # from the previous one so they follow the alias across revisions.

src/tallyman_mcp/server.py

@@ -50,6 +50,7 @@
 )
 from tallyman_core.events import record_event
 from tallyman_xorq import BuildError, build_and_persist, full_diff, list_entries, staleness
+from tallyman_xorq.dependents import references_own_alias
 from tallyman_xorq.recalc import classify_orphans, recalc
 
 log = logging.getLogger("tallyman_mcp")
@@ -617,12 +618,22 @@ def catalog_create(name: str, code: str, prompt: str = "") -> dict:
 def catalog_revise(name: str, code: str, prompt: str = "") -> dict:
     """Persist a NEW VERSION of an existing alias.
 
-    The alias is repointed to the new content hash. The previous hash remains
-    in the catalog as a forensic artifact and is recorded in alias_history.
+    The alias is repointed to the new content hash; the previous hash remains as
+    a forensic artifact in alias_history.
 
-    Code conventions and gotchas are documented in `catalog_run`. The same
-    rules apply here. Use `tracked_expr_from_alias(name)` to chain off the previous
-    version of the alias (or any other named entry).
+    Write the revision as a SELF-CONTAINED recipe — start from this entry's
+    current code and extend it, so the code tab reads as the full state of this
+    version in one view. A revision that references its OWN alias by name
+    (`tracked_expr_from_alias("<name>")` / `pinned_expr_from_alias("<name>")`) is
+    rejected (#135) — it makes an opaque, follows-its-own-head entry. Two good
+    shapes instead:
+      - source-shaped entry -> inline the source: `read_project_file(...)` /
+        `read_csv` plus the transforms, then your change.
+      - expensive parent (Aggregate/Join/Sort/window/UDF) -> reference the
+        previous version by its content HASH: `pinned_expr_from_alias("<hash>")`,
+        which reads its baked snapshot instead of re-running the computation.
+
+    Code conventions and gotchas are documented in `catalog_run`.
 
     Args:
         name: An existing alias.
@@ -636,6 +647,26 @@ def catalog_revise(name: str, code: str, prompt: str = "") -> dict:
     out = _run_and_record(project, code, prompt, tool="catalog_revise")
     if "error" in out:
         return out
+    if references_own_alias(project, out["hash"], name):
+        msg = (
+            f"this revision references its own alias {name!r}, which makes an opaque, "
+            f"permanently-stale (follows-its-own-head) entry. Write a self-contained recipe: "
+            f"inline the source (read_project_file / read_csv …) for a source-shaped entry, or "
+            f"reference the previous version by hash with pinned_expr_from_alias({prev_hash!r}) "
+            f"for an expensive one."
+        )
+        rec = record_error(project, code=code, message=msg, prompt=prompt or None, tool="catalog_revise")
+        record_event(
+            project,
+            "build_error",
+            session=SESSION_ID,
+            tool="catalog_revise",
+            prompt=prompt or None,
+            code=code,
+            message=msg,
+            error_id=rec["id"],
+        )
+        return {"error": msg, "error_id": rec["id"]}
     info = set_alias(project, name, out["hash"], expect_exists=True)
     record_event(
         project, "alias_set", session=SESSION_ID, tool="catalog_revise",

src/tallyman_xorq/dependents.py

@@ -31,6 +31,19 @@ def parents_of(project: str, content_hash: str) -> list[ParentRef]:
     return list(read_manifest(entry_dir(project, content_hash)).parents or [])
 
 
+def references_own_alias(project: str, content_hash: str, alias: str) -> bool:
+    """True if the entry references its own ``alias`` *by name* (#135).
+
+    A revision of alias X whose recipe calls ``tracked_expr_from_alias("X")`` /
+    ``pinned_expr_from_alias("X")`` records a parent edge with ``ref == X``. That
+    makes the entry an opaque self-reference — and a permanently-stale,
+    follows-its-own-head entry — so ``catalog_revise`` rejects it. A reference to
+    a prior version *by hash* records ``ref == <hash>`` (not the alias name) and
+    is allowed.
+    """
+    return any(p.ref == alias for p in parents_of(project, content_hash))
+
+
 def sources_of(project: str, content_hash: str) -> dict[str, str] | None:
     """The recorded source-leaf digests of one entry (``{rel_path: digest}``).