mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-11-18 17:55:26 +01:00
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>
3.6 KiB
3.6 KiB
Phase 04a
Date: 2026-03-27
Status: active
Purpose: close the critical V2 ownership-validation gap by making sender/session ownership explicit in both simulation and the standalone enginev2 slice
Goal
Validate the core V2 claim more deeply:
- one stable sender identity per replica
- one active recovery session per replica
- endpoint change, epoch bump, and supersede rules invalidate stale work
- stale late results from old sessions cannot mutate current state
This phase is not about adding broad new simulator surface. It is about proving the ownership model that is supposed to make V2 better than V1.5.
Why This Phase Exists
Current simulation is already strong on:
- quorum / commit rules
- stale epoch rejection
- catch-up vs rebuild
- timeout / race ordering
- changed-address recovery at the policy level
The remaining critical risk is narrower:
- the simulator still validates V2 strongly as policy
- but not yet strongly enough as owned sender/session protocol state
That is the highest-value validation gap to close before trusting V2 too much.
Source Of Truth
Design:
sw-block/docs/archive/design/v2-first-slice-session-ownership.mdsw-block/design/v2-acceptance-criteria.mdsw-block/design/v2-open-questions.mdsw-block/design/protocol-development-process.md
Simulator / prototype:
sw-block/prototype/distsim/sw-block/prototype/enginev2/
Historical / review context:
learn/projects/sw-block/phases/phase-13-v2-boundary-tests.mdsw-block/design/v2-scenario-sources-from-v1.md
Scope
In scope
- explicit sender/session identity validation in
distsim - explicit stale-session invalidation rules
- bridge tests from
distsimscenarios toenginev2sender/session invariants - doc cleanup so V2-boundary tests point to real simulator and
enginev2coverage
Out of scope
- Smart WAL expansion
- broad new timing realism
- TCP / disk realism
- V1 production integration
- new backend/storage engine work
Critical Questions To Close
- can an old session completion mutate state after a new session supersedes it?
- does endpoint change invalidate or supersede the active session cleanly?
- does epoch bump remove all authority from prior sessions?
- can duplicate recovery triggers create overlapping active sessions?
Assigned Tasks For sw
P0
- add explicit session identity to
distsim
- model session ID or equivalent ownership token
- make stale session results rejectable by identity, not just by coarse state
- add ownership scenarios to
distsim
- endpoint change during active catch-up
- epoch bump during active catch-up
- stale late completion from old session
- duplicate recovery trigger while a session is already active
- add bridge tests in
enginev2
- same-address reconnect preserves sender identity
- endpoint bump supersedes or invalidates active session
- epoch bump rejects stale completion
- only one active session per sender
P1
- tighten
learn/projects/sw-block/phases/phase-13-v2-boundary-tests.md
- point to actual
distsimscenarios - point to actual
enginev2bridge tests - state what remains real-engine-only
- only add simulator mechanics if a bridge test exposes a real ownership gap
Exit Criteria
Phase 04a is done when:
distsimexplicitly validates sender/session ownership invariantsenginev2has bridge tests for the same invariants- stale session work is shown unable to mutate current sender state
- V2-boundary doc no longer has stale simulator references
- we can say with confidence that V2 ownership semantics, not just V2 policy, are validated at prototype level