Engine execution layer for V2 replication protocol: - RebuildInstaller: full state handoff (dirty map, WAL, superblock, flusher) - TruncateToLSN: exact safety predicate (checkpointLSN == truncateLSN), ErrTruncationUnsafe escalation to NeedsRebuild - SyncReceiverProgress: unconditional Store for post-rebuild alignment - V2StatusSnapshot: CommittedLSN = nextLSN-1 for sync_all V2 bridge real I/O executors: - TransferFullBase: TCP streaming + RebuildInstaller + second catch-up - TransferSnapshot: SHA-256 verified streaming to disk - TruncateWAL: ErrTruncationUnsafe detection + escalation - StreamWALEntries: rebuild-mode TCP apply Engine executor interfaces: - CatchUpIO.TruncateWAL, RebuildIO.TransferFullBase returns achievedLSN - CatchUpExecutor truncation-only skip, NeedsRebuild escalation - RebuildExecutor uses achievedLSN for progress tracking Design docs reorganized: superseded planning docs removed, protocol truths and closure map added. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
9.0 KiB
Phase 05
Date: 2026-03-29
Status: complete
Purpose: begin the real V2 engine track under sw-block/ by moving from prototype proof to the first engine slice
Why This Phase Exists
The project has now completed:
- V2 design/FSM closure
- V2 protocol/simulator validation
- Phase 04 prototype closure
- Phase 4.5 evidence hardening
So the next step is no longer:
- extend prototype breadth
The next step is:
- start disciplined real V2 engine work
Phase Goal
Start the real V2 engine line under sw-block/ with:
- explicit engine module location
- Slice 1 ownership-core boundaries
- first engine ownership-core implementation
- engine-side validation tied back to accepted prototype invariants
Relationship To Previous Phases
Phase 05 is built on:
sw-block/docs/archive/design/v2-engine-readiness-review.mdsw-block/docs/archive/design/v2-engine-slicing-plan.mdsw-block/.private/phase/phase-04.mdsw-block/.private/phase/phase-4.5.md
This is a new implementation phase.
It is not:
- more prototype expansion
- V1 integration
- backend redesign
Scope
In scope
- choose real V2 engine module location under
sw-block/ - define Slice 1 file/module boundaries
- write short engine ownership-core spec
- start Slice 1 implementation:
- stable per-replica sender object
- stable recovery-session object
- session identity fencing
- endpoint / epoch invalidation
- ownership registry / sender-group equivalent
- add focused engine-side ownership/fencing tests
Out of scope
- Smart WAL expansion
- full storage/backend redesign
- full rebuild-source decision logic
- V1 production integration
- performance work
- full product integration
Planned Slices
P0: Engine Planning Setup
- choose real V2 engine module location under
sw-block/ - define Slice 1 file/module boundaries
- write ownership-core spec
- map 3-5 acceptance scenarios to Slice 1 expectations
Status:
- accepted
- engine module location chosen:
sw-block/engine/replication/ - Slice 1 boundaries are explicit enough to start implementation
P1: Slice 1 Ownership Core
- implement stable per-replica sender object
- implement stable recovery-session object
- implement sender/session identity fencing
- implement endpoint / epoch invalidation
- implement ownership registry
Status:
- accepted
- stable
ReplicaIDis now explicit and separate from mutableEndpoint - engine registry is keyed by stable identity, not address-shaped strings
- real changed-
DataAddrpreservation is covered by test
P2: Slice 1 Validation
- engine-side tests for ownership/fencing
- changed-address case
- stale-session rejection case
- epoch-bump invalidation case
- traceability back to accepted prototype behavior
Status:
- accepted
- Slice 1 ownership/fencing tests are in place and passing
- acceptance/gate mapping is strong enough to move to Slice 2
P3: Slice 2 Planning Setup
- define Slice 2 boundaries explicitly
- distinguish Slice 2 core from carried-forward prototype support
- map Slice 2 engine expectations from accepted prototype evidence
- prepare Slice 2 validation targets
Status:
- accepted
- Slice 2 recovery execution core is implemented and validated
- corrected tester summary accepted:
12ownership tests18recovery tests30total
P4: Slice 3 Planning Setup
- define Slice 3 boundaries explicitly
- connect recovery decisions to real engine recoverability inputs
- make trusted-base / rebuild-source decision use real engine data inputs
- prepare Slice 3 validation targets
Status:
- accepted
- Slice 3 data / recoverability core is implemented and validated
- corrected tester summary accepted:
12ownership tests18recovery tests18recoverability tests48total
- important boundary preserved:
- engine proves historical-correctness prerequisites
- full historical reconstruction proof remains simulator-side
Slice 3 Guardrails
Slice 3 is the point where V2 must move from:
- recovery automaton is coherent
to:
- recovery basis is provable
So Slice 3 must stay tight.
Guardrail 1: No optimistic watermark in place of recoverability proof
Do not accept:
- loose head/tail watermarks
- "looks retained enough"
- heuristic recoverability
Slice 3 should prove:
- why a gap is recoverable
- why a gap is unrecoverable
Guardrail 2: No current extent state pretending to be historical correctness
Do not accept:
- current extent image as substitute for target-LSN truth
- checkpoint/base state that leaks newer state into older historical queries
Slice 3 should prove historical correctness at the actual recovery target.
Guardrail 3: No snapshot + tail without trusted-base proof
Do not accept:
- "snapshot exists" as sufficient
Require:
- trusted base exists
- trusted base covers the required base state
- retained tail can be replayed continuously from that base to the target
If not, recovery must use:
FullBase
Guardrail 4: Truncation is protocol boundary, not cleanup policy
Do not treat truncation as:
- optional cleanup
- post-recovery tidying
Treat truncation as:
- divergent tail removal
- explicit safe-boundary restoration
- prerequisite for safe
InSync/ recovery completion where applicable
P5: Slice 4 Planning Setup
- define Slice 4 boundaries explicitly
- connect engine control/recovery core to real assignment/control intent entry path
- add engine observability / debug surface for ownership and recovery failures
- prepare integration validation against V2-boundary failure classes
Status:
- accepted
- Slice 4 integration closure is implemented and validated
- corrected tester summary accepted:
12ownership tests18recovery tests18recoverability tests11integration tests59total
Slice 4 Guardrails
Slice 4 should close integration, not just add an entry point and some logs.
Guardrail 1: Entry path must actually drive recovery
Do not accept:
- tests that manually push sender/session state while only pretending to use integration entry points
Require:
- real assignment/control intent entry path
- session creation / invalidation / restart triggered through that path
- recovery flow driven from that path, not only from unit-level helper calls
Guardrail 2: Changed-address must survive the real entry path
Do not accept:
- changed-address correctness proven only at local object level
Require:
- stable
ReplicaIDsurvives real assignment/update entry path - endpoint update invalidates old session correctly
- new recovery session is created correctly on updated endpoint
Guardrail 3: Observability must show protocol causality
Do not accept:
- only state snapshots
- only phase dumps
Require observability that can explain:
- why recovery entered
NeedsRebuild - why a session was superseded
- why a completion or progress update was rejected
- why endpoint / epoch change caused invalidation
Guardrail 4: Failure replay must be explainable
Do not accept:
- a replay that reproduces failure but cannot explain the cause from engine observability
Require:
- selected failure-class replays through the real entry path
- observability sufficient to explain the control/recovery decision
- reviewability against key V2-boundary failures
Exit Criteria
Phase 05 Slice 1 is done when:
- the real V2 engine module location is chosen
- Slice 1 boundaries are explicit
- engine ownership core exists under
sw-block/ - engine-side ownership/fencing tests pass
- Slice 1 evidence is reviewable against prototype expectations
This bar is now met.
Phase 05 Slice 2 is done when:
- engine-side recovery execution flow exists
- zero-gap / catch-up / needs-rebuild branching is explicit
- stale execution is rejected during active recovery
- bounded catch-up semantics are enforced in engine path
- rebuild execution shell is validated
This bar is now met.
Phase 05 Slice 3 is done when:
- recoverable vs unrecoverable gap uses real engine recoverability inputs
- trusted-base / rebuild-source decision uses real engine data inputs
- truncation / safe-boundary handling is tied to real engine state
- history-driven engine APIs exist for recovery decisions
- Slice 3 validation is reviewable without overclaiming full historical reconstruction
This bar is now met.
Phase 05 Slice 4 is done when:
- real assignment/control intent entry path exists
- changed-address recovery works through the real entry path
- observability explains protocol causality, not only state snapshots
- selected V2-boundary failures are replayable and diagnosable through engine integration tests
This bar is now met.
Assignment For sw
Phase 05 is now complete.
Next phase:
Phase 06broader engine implementation stage
Assignment For tester
Phase 05 validation is complete.
Next phase:
Phase 06engine implementation validation against real-engine constraints and failure classes
Management Rule
Phase 05 should stay narrow.
It should start the engine line with:
- ownership
- fencing
- validation
It should not try to absorb later slices early.