| index f7509cd50..b045afcf2 100644 |
| --- a/docs/superpowers/plans/2026-10-03-replicator-authority-plan.md |
| +++ b/docs/superpowers/plans/2026-10-03-replicator-authority-plan.md |
| @@ -36,12 +36,20 @@ The admission model (`internal/ops/admissionmodel`) is the executable contract; |
| 2. **The barrier (built: `DurabilityContent.Barred`, counted in the snapshot's read transaction; `CompletenessFor` refuses while it is positive; box-wide, so the ancestry query waits for owner scope).** The publisher's snapshot (`snapshotOnce`) treats a day incomplete for an owner while a durable unsettled admission of that owner, or of any fleet whose unacknowledged ancestry includes the admission's fleet, is admitted on or before that day (box-wide: any owner); it is a query over `admissions` and `fleets`, writes nothing, and lifts at settlement. Mirrors: the model's barrier invariant and `TestSuccessorBarredByPredecessorAdmission`, `TestLandedAmbiguousCommitBarsBeforeReadBack`. |
| 3. **Discovery, the uncertainty and the latch (built in the ledger, with review nine's and ten's corrections: `Replay` reads the latch again under the locks and takes its instant after them, and a replay that finds an uncertainty of the fleet open folds into it (one open uncertainty per fleet); publication enumerates an unresolved latch from the ledger's earliest day, returning an error if the interval exceeds 4000 days; every hold write and every admission and settlement dirty their days through `touchDay` with a fresh sequence and `publish` enumerates the latched discoveries' days (`latchedDates`), so publication revisits a day a bound reaches or a barrier leaves; `discoveryState.generation` makes a snapshot read again across a replay; a failed discovery latches the bound and counted set it computed or latches unresolved; `Replay` recomputes the bound in its transaction and closes on `maybeClose`'s test; `uncertainties.discovered_at` floors every closure; `SetPendingCounter` takes an `*atomic.Int64`, lock-free by contract. `Discover` with the fixed bound and the counted set, `uncertainties` and box-wide `holds` rows in one transaction, closed at once with nothing counted or pending; the settlement's hook writing `[admitted_at, settled_at]` and closing when no row and no pending registration remains, the fleet's pending count by `SetPendingCounter`; `EmptySettlement`; a failed transaction latched in memory with its bound and counted tokens, barring publication through the snapshot's `Barred` until `Replay`, one transaction; `DurabilityContent.Held` refusing completeness; the fleet's discovery mutex, registration and the latch's refusal of requests are the gate slice).** `Discover(fleet, at, proof, lastCleanLook)`: under the fleet's discovery mutex (new in `MeteredFleet`: registration, the recheck and the start of a discovery serialise on it, the pending set counted), the fixed bound, the counted set, the `uncertainties` row and the holds of `[from, now]` for the owners reached in one transaction, closed at once with nothing pending; a failed write latches the pending discovery in the existing failure latch (extended with the bound, the owners reached and the counted tokens; the publisher's overlay reaches successors through the ancestry query) and the fleet refuses requests until `Replay`, one transaction as the design has it. Mirrors: `TestZeroPendingClosesAtOnceAcrossMidnight`, `TestFailedDiscoveryLatchBarsUntilReplay`, `TestFailedDiscoveryReplayKeepsSettlements`, `TestReplayHoldsTheLowerBoundWhileOpen`, `TestReplayWritesSettledTokenWhileOpen`, `TestLatchOverlayReachesSuccessor`, the lower-bound tests (the in-flight request across a clean look, the proof term, the earlier-of threshold, the fixed cutoff in both orders, the admission instant, the exact bound, the empty terminals excluded). |
| 4. **The fleet journal, construction backfill and acknowledgement.** `OpenFleet(predecessor, owners, witness)` writes the `open` row and the backfill of every interval its unacknowledged ancestry holds; `stale`, `closing`, `closed` as the design's transactions (closure carries a pending replay and refuses with an unsettled admission); `Acknowledge(successor)` root-first, copying the effective set into `inherited` and writing the holds for the closed ones. The ledger's reach query replaces the model's `reach`. Mirrors: `TestAncestryReachAndRootFirstAcknowledgement`, `TestHealthyChainContributesNothing`, the per-step inheritance invariant as a property test over a recorded schedule. |
| -5. **The gate and the fleet (built: `internal/ops/litestream_admission.go` and the fleet's wiring in `litestream_metered.go`; `lease.RequestGate` returns a `lease.Admission` whose transport the gate middleware completes at the SDK's finalize step and whose recorder the meter completes beside its own writes, in the worker: registered when `Start` lands, finished when `Finish` lands, abandoned with a late `Start` or a failed `Finish`, unrecorded when `Start` failed; a gate with no ledger is `lease.ProofGate`, admitting with `lease.Unadmitted`, and a gate answering with no admission is refused. The fleet's gate: the proof, a registration in the pending set under the discovery mutex (refused while stale, latched or in discovery), the row committed by one writer goroutine within `admissionBudget`, the recheck under the mutex (stale, latched, in discovery or an epoch passed: `unissued`), a definite failure cancelled with its empty settlement, an ambiguous one read back by its token by the independent retry worker until the ledger answers, left pending and counted meanwhile; past the budget `ErrAdmissionNotDurable` and the writer's outcome resolved by the writer. Discovery once per fleet from `goStaleFrom`, with the pending instants, the proof and the last clean look; a latched one replayed from the watch and at Close. The journal: the open row at build (a fleet that cannot be journalled is not built), `closing` at Close after the final look, `transport-lost` for every issued admission whose transport never finalised, `closed` waited for within `closeSettleWait` with closure retained by the retry worker past it; acknowledgement at Open and at every watch tick until it lands. The helper process does not exist yet, so all of it runs in the agent. Tests: every send admitted and settled, the journal's rows and a replacement's acknowledgement, a discovery between registration and commit refusing the commit at its recheck with the registration counted, the budget and a writer failing against a ledger that cannot answer, transport-lost at Close with the recorder pending.)** Contract (review nine, Opus P2-2; review ten, Opus P2-2): the ledger is never called with the fleet's discovery mutex held, and the pending counter the ledger reads is the lock-free `*atomic.Int64`, so a settlement under the ledger's mutex never waits on the mutex a gate recheck holds while it writes `unissued`; a registration that resolves decrements the counter before it tells the ledger (`EmptySettlement`, or the row's own transition), so the closure test sees the counter already down, and `CloseFleet` closes an open uncertainty on the same test regardless; the ledger's `Discover` does not check the fleet's journal state (the model returns unless open), which is this slice's to enforce before it calls. `MeteredFleet.admit` becomes the proof (unchanged) plus the admission: registration in the pending set under the discovery mutex, the ledger's `Admit`, the recheck, the token handed to the SDK middleware (`lease.RequestGate` returns the token; the callbacks identify it, but the persisted meter attempt still lacks its admission-token association (outstanding); the Deserialize handler return writes `TransportDone`). `lookNow` is the discovery when it finds a change; `closeNow` is `closing` then `closed`. The helper process does not exist yet (Part B): the transport and the recorder run in the agent, so the lifecycle guard is the fleet's own, `transport-lost` is written at `Close` for a transport that never finalised, and `unrecorded` where the meter's `Start` failed. Mirrors: `TestHelperDeathAndRecorderGuard` (as the agent's close), `TestSendNeedsDurableIssuedAdmission` (the middleware refuses without a token), `TestReadBackOnlyAfterTheHandleCloses`, `TestBetweenCommitAndAnswer`. |
| -6. **The producer fence and recovery.** `admissions.lock` flocked by the agent before its first admission on an open file description every helper will later inherit (today: the agent alone); `OpenDurabilityLedger`'s `recover` extended: with the fence, in one transaction, every unsettled admission `recovered-unknown` with its interval, every fleet not `closed` closed with its interval, every unacknowledged fleet acknowledged root-first by the first fleet built. Mirrors: `TestFenceOutlivesAgent`, `TestFenceHeldTokenSentAfterCrash`, `TestLandedAmbiguousThenCrash`, the kill-at-every-transition tests (a second process reopening the ledger after a kill at each boundary). |
| -7. **Part C2's reader.** The `holds` rows in the published day (`DurabilityContent`), the reader treating a box-wide row as failing every owner and an owner row as failing that owner alone, and the older-reader marker (a box-wide incompleteness marker whenever any hold exists). Box-wide stays the default; decision 10's per-owner fleets are not built. |
| +5. **The gate and the fleet (built: `internal/ops/litestream_admission.go` and the fleet's wiring in `litestream_metered.go`; `lease.RequestGate` returns a `lease.Admission` whose transport the gate middleware completes at the SDK's finalize step and whose recorder the meter completes beside its own writes, in the worker: registered when `Start` lands, finished when `Finish` lands, abandoned with a late `Start` or a failed `Finish`, unrecorded when `Start` failed; a gate with no ledger is `lease.ProofGate`, admitting with `lease.Unadmitted`, and a gate answering with no admission is refused. The fleet's gate: the proof, a registration in the pending set under the discovery mutex (refused while stale, latched or in discovery), the row committed by one writer goroutine within `admissionBudget`, the recheck under the mutex (stale, latched, in discovery or an epoch passed: `unissued`), a definite failure cancelled with its empty settlement, an ambiguous one read back by its token by the independent retry worker until the ledger answers, left pending and counted meanwhile; past the budget `ErrAdmissionNotDurable` and the writer's outcome resolved by the writer. Discovery once per fleet from `goStaleFrom`, with the pending instants, the proof and the last clean look; a latched one replayed from the watch and at Close. The journal: the open row at build (a fleet that cannot be journalled is not built), `closing` at Close after the final look, `transport-lost` for every issued admission whose transport never finalised, `closed` waited for within `closeSettleWait` with closure retained by the retry worker past it; acknowledgement at Open and at every watch tick until it lands. The helper process does not exist yet, so all of it runs in the agent. Tests: every send admitted and settled, the journal's rows and a replacement's acknowledgement, a discovery between registration and commit refusing the commit at its recheck with the registration counted, the budget and a writer failing against a ledger that cannot answer, transport-lost at Close with the recorder pending.)** Contract (review nine, Opus P2-2; review ten, Opus P2-2): the ledger is never called with the fleet's discovery mutex held, and the pending counter the ledger reads is the lock-free `*atomic.Int64`, so a settlement under the ledger's mutex never waits on the mutex a gate recheck holds while it writes `unissued`; a registration that resolves decrements the counter before it tells the ledger (`EmptySettlement`, or the row's own transition), so the closure test sees the counter already down, and `CloseFleet` closes an open uncertainty on the same test regardless; the ledger's `Discover` does not check the fleet's journal state (the model returns unless open), which is this slice's to enforce before it calls. `MeteredFleet.admit` becomes the proof (unchanged) plus the admission: registration in the pending set under the discovery mutex, the ledger's `Admit`, the recheck, the token handed to the SDK middleware (`lease.RequestGate` returns the token; the callbacks identify it, and StartAdmitted commits the attempt and token association atomically before a successfully recorded send; the Deserialize handler return writes `TransportDone`). `lookNow` is the discovery when it finds a change; `closeNow` is `closing` then `closed`. The helper process does not exist yet (Part B): the transport and the recorder run in the agent, so the lifecycle guard is the fleet's own, `transport-lost` is written at `Close` for a transport that never finalised, and `unrecorded` where the meter's `Start` failed. Mirrors: `TestHelperDeathAndRecorderGuard` (as the agent's close), `TestSendNeedsDurableIssuedAdmission` (the middleware refuses without a token), `TestReadBackOnlyAfterTheHandleCloses`, `TestBetweenCommitAndAnswer`. |
| +6. **The producer fence and recovery (built; independent Codex review accepts this slice, Opus pending).** `admissions.lock` flocked by the agent before its first admission on an open file description every helper will later inherit (today: the agent alone); `OpenDurabilityLedger`'s `recover` extended: with the fence, in one transaction, every unsettled admission `recovered-unknown` with its interval, every fleet not `closed` closed with its interval, every unacknowledged fleet acknowledged root-first by the first fleet built. Mirrors: `TestFenceOutlivesAgent`, `TestFenceHeldTokenSentAfterCrash`, `TestLandedAmbiguousThenCrash`, the kill-at-every-transition tests (a second process reopening the ledger after a kill at each boundary). |
| +7. **Part C2's reader (built; independent Codex review accepts this slice, Opus pending).** The `holds` rows in the published day (`DurabilityContent`), the reader treating a box-wide row as failing every owner and an owner row as failing that owner alone, and the older-reader marker (a box-wide incompleteness marker whenever any hold exists). Box-wide stays the default; decision 10's per-owner fleets are not built. |
| |
| **What waits.** The helper process (Part B) and the fence's descriptor transfer, until the VFS spike; owner-scoped holds (decision 10); the activator-to-fleet handover (not designed). |
| |
| ## Later, each behind its gate |
| |
| Part D's uid lifecycle and the sleeping binding (the unit observer extended), claims by identity, the lineage record; Part B on the VFS spike's result; the parameter-dependent pieces last, each only after its decision. |
| + |
| +## Codex checkpoint, 2026-10-03 |
| + |
| +Task 4 slices 6 and 7 and the admission-to-attempt association are implemented on this design branch. The preserved gitless task4b/task4m copies were inspected and left untouched; slice 6 was salvaged with corrected fence lifetime, recovery topology, retry identity and acknowledgement behavior. Successful StartAdmitted writes the attempt and unique association in one transaction. Failed recording retains the existing send-and-hold behavior. Recovery retains the producer fence beyond Close and garbage collection while admissions remain unsettled, preserves participant timestamps, and atomically inherits all recovered unacknowledged histories into the first new fleet. Live acknowledgement remains adjacent and root-first. |
| + |
| +New snapshots are V3. Hold rows are validated with their count and a synthetic legacy recording-failure marker; real recording failures remain separate. Owner-aware Scope excludes held owners, while any box-wide hold, barrier or real recording failure still holds every owner. Strict old readers refuse all V3 snapshots, including clean days; permissive old readers see the legacy marker on held or barred days. Production hold creation remains box-wide, so decision 10 is not activated. |
| + |
| +Independent Codex reviewers accepted each scoped delta by inspection. Opus is unavailable and its review remains pending. Local normal/race tests and mutation tests are evidence about these implementations, not evidence of AWS/Stripe operation or whole-feature acceptance. The integrated full gate and exact-commit Amadan CI are tracked in the run-root checkpoint notes. Part B, agent wiring, deployment support conditions and all unapproved policy parameters remain blocked as listed above. |
amadan