Design 47 keeps the catch-up tool in the restore point

At a revert the manifest being applied is the one from before the change,
which names no catch-up tool, so the node agent could not find it there. The
newer build's manifest declares it beside the kept data whose form it changes,
the backup records it in the restore point, and the node agent takes it from
there.

Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i
This commit is contained in:
2026-11-06 21:37:09 +01:00
parent 25d9f8df61
commit 49ecfb6cdf
@@ -760,7 +760,7 @@ ADR 0656 decides the direction and leaves every choice made in working it out to
| No old form written beside the new; a revert restores the parts' kept data on the bus from a restore point taken before they moved, then they catch up forward | only the new form is looked after (the operator, 2026-11-06 21:3x), and a revert still works, as the delivery system's capability for every change of a kept data's form |
| A module's kept data on the bus backed up before a `form` change and restored beside the live data at a revert, a missing restore point holding the revert | ADR 0404 covers only the items on a module's node, so the bus's kept data had no restore point; a restore never goes over live data, and a revert with nothing to restore must not start on the newer form unasked |
| Only kept data whose `form` changes restored, the wants never; at a revert the node-engine last on its node, and the reverted assigner and gate only after the reverted indexer took in the trunk's head | restoring anything else would set back what was decided since; restored wants, or an assigner reading an indexer not yet caught up, would send nodes to older fingerprints; the node-engine of before may not know how to restore |
| A restore point holding the consumers' positions, and each manifest's own catch-up tool called after a restore | the reverted build then hears everything since as after any restart; the stream `forge` keeps 7 days, so what fell out of it is taken in from the trunk by the part's own tool |
| A restore point holding the consumers' positions and the catch-up tool the newer manifest declares, called after a restore | the reverted build then hears everything since as after any restart; the stream `forge` keeps 7 days, so what fell out of it is taken in from the trunk by the part's own tool |
| A revision removed when no record pins it and it is not current, pins counted per revision | a trace must read every revision it moved between, and a revision neither pinned nor current is read by nobody; counting pins keeps a revision two records share |
| The indexer and the assigner hear `pinned`, `freed` and `heads-replaced` through durable consumers | an event said while either was down is applied when it comes back, so no revision leaks and none is dropped early |
| Records kept 90 days by default, the gate's setting `record-retention`, the ledger capped at 768 MiB, a record's operations removed with it | the traces asked so far went back weeks; about 840 outcome operations make a record about 200 KiB, so 90 days at an estimated 20 a day is about 360 MiB, and the cap is twice that |
@@ -1574,7 +1574,8 @@ later change of a kept data's form, not as a case of this milestone.
`node-backup` of the node holding `mesh-broker` for a restore point of that kept data, and waits for its event
`ended`, as for any backup before the apply. The bus module's account takes it, as it takes the bus's snapshots
(ADR 0235 §5). A restore point is keyed by the module, the kept data, its form and the fingerprint it was taken
before, and it holds the kept data whole and the position of each durable consumer the module reads with. A failed
before, and it holds the kept data whole, the position of each durable consumer the module reads with, and the
catch-up tool the newer manifest declares beside that kept data. A failed
backup holds that module as any failed backup does.
- **A revert restores it before the reverted build starts.** When a want takes a module back across a change of a
kept data's `form`, the node agent applying it asks that seat's verb `restore` for the restore point of that module,
@@ -1604,8 +1605,11 @@ later change of a kept data's form, not as a case of this milestone.
merge older than the stream's first message is never redelivered, and the code then leaves that repository's
modules at the restore point's fingerprints. So the restore runs one forward step: once the reverted indexer
runs, the node agent that restored it calls its tool `indexer_take_in` with each repository the gate's source names
(`NewTakeInRepository`, which takes in the head the source names for a repository). Each manifest declares its
catch-up tool beside its kept data, so the delivery system names no module's tool.
(`NewTakeInRepository`, which takes in the head the source names for a repository). The catch-up tool is declared
by the newer build's manifest, beside the kept data whose form it changes, and recorded in the restore point when
the backup is taken; the node agent takes it from the restore point, never from the manifest being applied, since
at a revert that is the manifest from before the change, which names none. So the delivery system names no
module's tool.
- **The assigner** (mesh-delivery, `modules/mesh-delivery-assigner`): it keeps nothing restored. Its pass
(`passer.wants`) writes, from what the world holds now, each node's want by the six rules from the indexer's
newest fingerprint at the trunk, and only where the value differs; so once the indexer has caught up it writes
@@ -2214,7 +2218,8 @@ list:
consumer's position on `forge`, and of the gate's `merges` and `turns`, before it moved them. A revert of milestone
G is checked on the checking program built from the revert's own heads and delivered: the indexer's and the gate's
kept data is restored beside the live data before their reverted builds start, the indexer catches up (its
`forge` consumer, then `indexer_take_in` of every repository the source names), and only then are the reverted
`forge` consumer, then `indexer_take_in` of every repository the source names, the tool taken from the restore
point while the reverted manifest declares no catch-up tool), and only then are the reverted
assigner and gate wanted; a module delivered during milestone G keeps its fingerprint while they wait; no want goes
to a fingerprint older than the trunk's; the operator is asked again only for an ask raised after the restore
point. A revert whose restore point is missing is held, naming it. Proved with the real builds of the indexer, the
@@ -2455,6 +2460,7 @@ order inside one milestone, for this one case (ADR 0644).
- Whether the builder should hold a seat of its own, so that its waits are a seat's events like the other holders':
a later proposal.
- Which manifest grants the node agent the call of a restored part's catch-up tool (noted on issue 1921).
- How long the checker's stream `checks` keeps its events (*A try*, above).
- Who is granted `checker_try` and the take-in hand tools: the operator's grants, outside this design.
- A web view of deliveries beyond the pull request's comment.