docs: reactive-recalc doc + auto-recalc-on-revise plan#130
Merged
Conversation
Two reactive-recalc documentation artifacts, no code change. - docs/reactive-recalc.md — rewrite of the reactive recalc system doc. Leads with how a simple catalog is built and the revise-an-alias -> recompute-dependents workflow, then documents when new alias revisions are created, the two staleness axes, the scan/recalc MCP+HTTP surfaces, the one-checkpoint semantics, and cross-process SSE. Accurate against main as of #129. - plans/auto-recalc-on-revise.md — design plan for making revise auto-cascade to its stale dependents in one atomic checkpoint. Resolves the decision tree: catalog-repo config (env-overridable, default ON), followers-only scope with orphan-stale logging + durable recalc-failure records, stop-and-report failure, sync v1, and triggers on every existing-alias head-mover (revise + promote_diff, both surfaces) with a scan-surface backstop. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two documentation artifacts for the reactive recalc system, no code change. Off
latest main (includes #129).
What lands
docs/reactive-recalc.md— a rewrite of the reactive-recalc system doc. Itleads with the two things you actually do — build a simple catalog, then revise an
alias and recompute its dependents — and then documents when new alias revisions are
created, the two staleness axes (alias + source), the scan/recalc surfaces (MCP +
HTTP), the one-checkpoint-per-walk semantics, and the cross-process notify/SSE path.
Accurate against main as of fix(#89): recalc review fixes (#128) — notify reload, SSE shape, manifest-less root guard #129 (the
_recalc_sse_eventshape, manifest-less rootguard, and
/internal/notifyrecalc handling it describes are all merged).plans/auto-recalc-on-revise.md— the design plan for auto-recalc on revise:revising an alias optionally recomputes its stale dependents in the same atomic
checkpoint. Settled during design review:
git add -A); reviseembeds a checkpoint-free
_recalc_walk, so there are no checkpoint plumbingchanges — a refactor, not new machinery.
config.jsonin the catalog repo, env-overridable,default ON.
durable recalc-failure records, so leaked staleness is always logged and
tie-back-able.
catalog_revise+catalog_promote_diff, both MCP and companion) via a shared helper, with acatalog_scan_stalenessbackstop for the bypasses it can't hook.Implementation (Stage A/B) is a follow-up; this PR is the plan + doc only.
🤖 Generated with Claude Code