Recovery path for already-completed graphs carrying two-value :introduced-by corruption

[adityamukho]

Summary

PR #243 stopped new two-value :introduced-by corruption and added a repair to the Stage B correction sweep. But the repair reaches only graphs that keep ingesting new commits above the old ceiling. A graph whose ingestion has already completed cannot be repaired at all, and that is the modal state for a memory graph in the field.

There is currently no supported way to recover such a graph short of deleting it and re-ingesting from scratch.

Why a completed graph is unreachable

A finished run parks :ingestion/correction-sweep-through (mcp_server.py:8796) at frontier-high's :hi-hash. On the next run, _correction_sweep_select_position (mcp_server.py:8854) computes ceiling_pos from that bound and returns None on its first call:

if pos > ceiling_pos:
    return None  # reached frontier-high's own :hi-hash; nothing left to correct

(mcp_server.py:8922)

So _correction_sweep_apply — which owns the repair — runs zero times. Measured during #235: watermark at linearization position 13 of 13, one select call, zero apply calls. Re-running ingestion repairs nothing.

The behaviour is correct for the sweep's original purpose (it has genuinely finished its work). It is simply not a recovery path.

What already works

• Prevention — every future ingestion, on any graph.
• Repair — for graphs that keep receiving new commits above the old ceiling, and then only for entities that are candidates in those commits; also on an interrupted/resumed run, where Stage B still has region to sweep.

What is missing

An explicit path to re-sweep a range of an already-completed graph, so its corrupted entities collapse to a single :introduced-by.

Design notes

Detection is cheap and should probably come first. The whole-graph audit is one query — the same one #235's oracle uses:

[:find ?e (count ?c) :where [?e :introduced-by ?c]]

Filter to count > 1. A read-only "audit" step that reports how many entities are affected (and whether any are) is useful on its own, and lets a user decide whether a reset is worth its cost. It also answers a question nobody can answer today: how widespread this actually is in real graphs.

Re-sweeping is not cheap. _correction_sweep_apply was 131.8s of a 720.6s 450-commit run in #235's A/B — a full re-sweep is a substantial fraction of an ingestion. Worth considering whether the reset can be scoped to the commits that actually introduced the affected entities, rather than resetting the whole watermark. The audit query above yields the entity idents; their :introduced-by values name the candidate commits directly.

Safety constraints:

• Moving :ingestion/correction-sweep-through backwards must not cause duplicate facts. The sweep is idempotent per entity by design (case 1 confirms, case 3 guards self-introduction), but that should be verified deliberately rather than assumed, especially interacting with _forward_apply(lifecycle_only=True) which the 2d Stage B loop runs after every swept commit.
• The repair itself is already inert when pos_by_commit_ident is None or empty, so a reset path must be sure to supply it — see _correction_sweep_apply's "Reach, stated plainly" docstring section.
• Whatever the surface (MCP tool, CLI flag, env var), it should be explicit and hard to trigger accidentally: it re-does work and moves a durability watermark backwards.

Prior art in this file: _lineage_confirmed_through_update and _watermark_update are the existing patterns for reading and moving these bookkeeping idents, and _correction_sweep_through_update (mcp_server.py:8813) is the exact writer to reuse.

Scope question worth settling first

Is a one-off recovery script sufficient (run once by whoever has an affected graph), or does this warrant a supported tool? That depends on the audit's answer. If real graphs turn out to be widely affected, it is a tool; if it is rare, a documented script may be the honest scope.

Related: #235 (the corruption and its partial repair), #222.

[adityamukho]

Does the standing "rebuild, never migrate" decision make this issue dead?

Raising this as a question rather than acting on it.

This issue asks for an explicit path to re-sweep a range of an already-completed graph so its corrupted entities collapse to a single :introduced-by. The standing decision recorded in CLAUDE.md and in docs/superpowers/specs/2026-08-14-ident-rule-r3-and-format-version-design.md says the opposite for exactly this class of graph:

Graph format version — there is no migration, by design. [...] any graph built before #222 closes gets rebuilt into a fresh graph path, never migrated or re-ingested in place: several #222-arc fixes (#235, #251/#253, #238/#245, phase 2d) write facts that do not self-heal on a later ingest, so those graphs are condemned independently of any one bug.

A graph carrying two-value :introduced-by corruption is by definition pre-#243, therefore pre-#222-closure, therefore already condemned by that decision on grounds that have nothing to do with this specific defect. Repairing only its :introduced-by facts would leave every other non-self-healing residue in place, so the repaired graph still is not trustworthy — which makes the recovery path a lot of machinery for a graph that still has to be rebuilt.

GRAPH_FORMAT_VERSION also now enforces this mechanically: ingestion refuses to run against any other version, including an absent stamp.

Two things in this issue may still be worth keeping regardless of the answer:

1. The detection query. The issue notes the whole-graph audit is a single query — the same one bug: forward walk mints a second :introduced-by, creating permanent two-value lineage ambiguity #235's oracle uses. A cheap "is this graph corrupted?" check is useful even when the answer is "rebuild it", because it tells a user why they have to.
2. The diagnosis itself. The mechanism recorded here — a finished run parks :ingestion/correction-sweep-through at frontier-high's :hi-hash, so _correction_sweep_select_position returns None on its first call and _correction_sweep_apply runs zero times — is a real property of the sweep worth having written down, whether or not a recovery path is ever built.

So the options look like: close this and keep the detection query as a separate small issue, or narrow this issue to detection-only. Both are preferable to building the re-sweep. Deferring to @adityamukho on which.

[adityamukho]

Closing: the rebuild decision stands, so the repair path is dead

Confirmed by @adityamukho — rebuild, don't repair.

A graph carrying two-value :introduced-by corruption is by definition pre-#243, therefore pre-#222-closure, and the standing decision condemns it on grounds independent of this defect: several #222-arc fixes (#235, #251/#253, #238/#245, phase 2d) write facts that do not self-heal on a later ingest. Repairing only its :introduced-by facts would leave every other residue in place, so the graph still has to be rebuilt. The re-sweep would be substantial machinery — _correction_sweep_apply was 131.8 s of a 720.6 s 450-commit run in #235's A/B — spent on a graph that gets thrown away anyway.

GRAPH_FORMAT_VERSION now enforces this mechanically: ingestion refuses to run against any other version, including an absent stamp.

What was NOT dropped

The detection half of this issue is worth keeping and is now #287 — the one-query whole-graph audit. It stays useful precisely because the answer is "rebuild": it tells a user whether their graph is affected and therefore why they have to. It also answers a question nobody can answer today — how widespread this actually is in real graphs.

The diagnosis recorded here is preserved in that issue too: a finished run parks :ingestion/correction-sweep-through at frontier-high's :hi-hash, so _correction_sweep_select_position returns None on its first call (mcp_server.py:8922) and _correction_sweep_apply runs zero times. That is correct for the sweep's original purpose and simply is not a recovery path — which is the fact this issue established and which remains true.