diff --git a/sw-block/.private/phase/phase-17-checkpoint-review.md b/sw-block/.private/phase/phase-17-checkpoint-review.md new file mode 100644 index 000000000..05c915b74 --- /dev/null +++ b/sw-block/.private/phase/phase-17-checkpoint-review.md @@ -0,0 +1,183 @@ +# Phase 17 Checkpoint Review + +Date: 2026-04-04 +Status: ready for review + +## Review Object + +Review the current `Phase 17` checkpoint as: + +1. `Phase 16` finish-line checkpoint accepted as the bounded runtime stop-line +2. `17A` delivered as a broader recovery/lifecycle branch map +3. `17B` delivered as a bounded failover/publication whole-chain contract draft +4. `17C` delivered as a long-window restart/disturbance policy draft +5. `17D` delivered as a first launch-envelope draft + +This checkpoint should be judged as a bounded product-claim checkpoint, not as a +broad production-readiness or rollout-approval review. + +## What Is In Scope + +### Current checkpoint claim + +The checkpoint may now claim that, for the bounded chosen path: + +1. the broader recovery/lifecycle branches are explicitly enumerated and no + longer hidden in implementation-only reasoning +2. one bounded failover/publication whole-chain statement is explicit and tied + to named evidence +3. long-window restart/disturbance handling is expressed as explicit runtime + rule, explicit temporary inconsistency policy, or explicit non-claim +4. the first launch envelope is finite, with supported scope, exclusions, and + launch blockers written down + +### Expected judgment + +1. the checkpoint is a real product-claim-shaping step, not only wording +2. claims, non-claims, and blockers are evidence-backed and bounded +3. the stop-line remains disciplined: nothing here should silently broaden into + generic launch approval + +## What Is Explicitly Out Of Scope + +Do NOT review this checkpoint as claiming: + +1. broad generic production readiness +2. support for every restart/failover/disturbance branch +3. broad transport/frontend matrix support +4. `RF>2` product closure +5. pilot success or soak success as generic production proof + +## Primary Files + +Checkpoint framing: + +1. `sw-block/.private/phase/phase-17.md` +2. `sw-block/.private/phase/phase-17-checkpoint-review.md` +3. `sw-block/design/v2-first-launch-supported-matrix.md` +4. `sw-block/design/v2-product-completion-overview.md` +5. `sw-block/design/v2-protocol-truths.md` +6. `sw-block/design/v2-protocol-claim-and-evidence.md` + +Primary evidence code/tests: + +1. `weed/server/master_block_registry.go` +2. `weed/server/master_block_registry_test.go` +3. `weed/server/qa_block_publication_test.go` +4. `weed/server/qa_block_disturbance_test.go` +5. `weed/server/qa_block_cp11b3_adversarial_test.go` +6. `weed/server/volume_server_test.go` + +## Accepted Claim Set + +1. broader recovery/lifecycle branches on the chosen path are now classified as + closed, partially proven, or residual +2. one bounded failover/publication contract is explicit: + after failover completion and winning-primary assignment delivery/applied, + lookup/publication must point to the winning primary and agree with registry + truth +3. one bounded disturbance policy table is explicit for startup + non-authoritative inventory, repeated restart before convergence, stale rejoin + input, repeated failover windows, and degraded sparse heartbeat handling +4. one first-launch envelope draft is explicit for the bounded chosen path + +## Explicit Non-Claims + +1. broad whole-surface failover/publication proof +2. broad restart-window behavior outside the explicit `17C` policy table +3. broad transport/frontend approval beyond the named bounded envelope +4. launch approval, pilot approval, or rollout approval + +## Residual Gaps + +1. stronger whole-surface publication proof across more outward surfaces +2. broader restart/rejoin/repeated-disturbance closure beyond the current policy + table +3. pilot-pack, preflight, stop-condition, and controlled-rollout artifacts +4. any broader launch claim that cannot map directly to named accepted evidence + +## Evidence Summary + +### `17A` branch map + +1. branch inventory is derived from `Phase 16` finish-line residuals plus named + restart/disturbance/failover tests in `weed/server` +2. result: + - restart same-lineage reconstruction is classified closed on the bounded + chosen path + - the remaining major branches are classified partially proven rather than + silently implied + +### `17B` failover/publication contract + +1. `TestP11P3_Failover_PublicationSwitches` +2. `TestP12P1_FailoverPublication_Switch` +3. `TestP11P3_HeartbeatReconstruction` +4. failover/promotion tests in `qa_block_cp11b3_adversarial_test.go` +5. result: + - one bounded whole-chain publication statement is supportable + +### `17C` disturbance policy + +1. `TestStartBlockService_ScanFailureEmitsNonAuthoritativeInventory` +2. `TestRegistry_UpdateFullHeartbeatWithInventoryAuthority_(NonAuthoritativeEmptyDoesNotDelete|AuthoritativeEmptyStillDeletes)` +3. `TestP12P1_(Restart_SameLineage|RepeatedFailover_EpochMonotonic|StaleSignal_OldEpochRejected)` +4. missing-field truth-retention tests in `master_block_registry_test.go` +5. result: + - the main long-window disturbance classes are now policy-shaped rather than + only code-shaped + +### `17D` launch envelope + +1. `Phase 12 P4` bounded floor / rollout-gate package +2. `CP13-1..9` +3. `Phase 16` finish-line checkpoint +4. `Phase 17A-17C` branch/contract/policy package +5. result: + - first supported envelope, exclusions, and launch blockers are finite and + named + +## Review Questions + +### For `sw` + +Please check implementation and checkpoint coherence: + +1. Is the `Phase 17` package coherent as one bounded product-claim checkpoint? +2. Are the envelope exclusions and blockers disciplined enough to avoid silent + overclaim? +3. Is any part of the current package still too vague to support review or later + global-doc synchronization? + +### For `tester` + +Please challenge the proof posture: + +1. Is the `17B` contract actually supported by the cited tests, or only loosely + suggested by them? +2. Does the `17C` policy table faithfully separate runtime rule from temporary + inconsistency window? +3. Are there any obvious missing outward surfaces that make the current launch + envelope too optimistic even in bounded form? + +### For `manager` + +Please challenge scope and stop-line discipline: + +1. Is `Phase 17` the right place to stop this checkpoint package before + productionization? +2. Are the current launch blockers and explicit non-claims sufficient to prevent + the package from being misread as launch approval? +3. Should any current item be moved out of `Phase 17` and into productionization + instead? + +## Requested Output Shape + +Please reply with one of: + +1. `ACCEPT` +2. `ACCEPT WITH MINOR FIXES` +3. `REJECT` + +If not `ACCEPT`, list findings ordered by severity and keep them bounded to this +checkpoint's actual claim set. diff --git a/sw-block/.private/phase/phase-17.md b/sw-block/.private/phase/phase-17.md index a96b7c74c..2385b4d47 100644 --- a/sw-block/.private/phase/phase-17.md +++ b/sw-block/.private/phase/phase-17.md @@ -1,411 +1,634 @@ -# Phase 17 - -Date: 2026-04-04 -Status: active -Purpose: track post-`Phase 16` code separation so adapter/runtime ownership in -`weed/server` and backend-binding ownership in `weed/storage/blockvol/v2bridge` -continue to converge without losing engineering continuity - -## Why This Phase Exists - -`Phase 14-16` established and widened one bounded `V2`-owned runtime path: - -1. `Phase 14` made the explicit core real -2. `Phase 15` rebound bounded integrated surfaces to consume core-owned truth -3. `Phase 16` closed one bounded runtime path where the core owns command and - observation semantics - -That semantic/runtime line is now real, but a separate engineering line has -been running in parallel: - -1. move canonical rules toward `sw-block` -2. thin `weed/server` into a host shell -3. keep `v2bridge` limited to backend-binding responsibilities -4. avoid creating a new mixed-ownership layer while the migration proceeds - -This phase exists to track that separation line explicitly so commits, reviews, -and next steps do not drift away from the phase log. - -## Relationship To Phase 16 - -`Phase 16` remains the semantic/runtime-ownership phase. - -`Phase 17` is different: - -1. it does not redefine the bounded `V2` runtime claims from `Phase 16` -2. it tracks code movement and ownership cleanup after those claims became real -3. it records which adapter/binding responsibilities moved where - -In short: - -1. `Phase 16` answers: who owns runtime semantics? -2. `Phase 17` answers: where does the code now live, and what is left to move? - -## Phase Goal - -Track and complete the post-`Phase 16` separation of command/runtime/binding -responsibilities so the codebase approaches this split: - -1. `sw-block` - - owns canonical contracts, core/runtime helpers, and reusable semantics -2. `weed/storage/blockvol/v2bridge` - - owns concrete `BlockVol` and wire/backend bindings -3. `weed/server` - - owns host-shell orchestration, host effects, and product integration only - -## Scope - -### In scope - -1. migration batches that thin `weed/server` -2. migration batches that keep backend binding in `v2bridge` -3. migration batches that move reusable coordination toward `sw-block` -4. explicit tracking of delivered / partial / next separation seams - -### Out of scope - -1. changing the semantic claims already owned by `Phase 14-16` -2. broad protocol redesign -3. full removal of legacy compatibility paths without replacement criteria -4. changing `blockvol` into a `sw-block` package - -## Batch Tracking - -### Batch 1: Contracts And Canonical Translation - -Goal: - -1. stabilize contract ownership and canonical identity/recovery-target mapping - -Status: - -1. delivered - -Delivered result: - -1. `sw-block/bridge/blockvol` owns the canonical contract/helper layer -2. `Task A` removed duplicate identity/recovery-target derivation from adapter - code -3. `Task B/C/D` were confirmed already clean at the acceptance bar - -Evidence: - -1. `a38e04c03` -2. design notes: - - `sw-block/design/v2-first-migration-batch.md` - - `sw-block/design/v2-first-migration-task-pack.md` - -### Batch 2: Backend-Binding Shim Reduction - -Goal: - -1. remove redundant reader/pinner shims and confirm thin backend bindings - -Status: - -1. delivered - -Delivered result: - -1. `v2bridge.Reader` returns bridge contract state directly -2. `pinnerShimForRecovery` was removed -3. `Executor` was confirmed already clean as a direct engine-IO implementer - -Evidence: - -1. `680b53031` -2. `519c84994` -3. design notes: - - `sw-block/design/v2-second-migration-batch.md` - - `sw-block/design/v2-second-migration-task-pack.md` - -### Batch 3: Recovery Runtime Helper Extraction - -Goal: - -1. move reusable recovery coordination out of `weed/server/block_recovery.go` - -Status: - -1. delivered - -Delivered result: - -1. `sw-block/engine/replication/runtime` owns pending coordination and reusable - execution helpers -2. `block_recovery.go` uses those helpers on the production path -3. no-core behavior is structurally isolated behind explicit legacy helpers - -Evidence: - -1. `6fea93e82` -2. `e200df779` -3. `e075d7761` -4. `3a5fbbfde` - -### Batch 4: Typed Runtime Boundary And Host-Shell Reduction - -Goal: - -1. remove `interface{}` drift and simplify recovery host-shell logic - -Status: - -1. delivered - -Delivered result: - -1. `PendingExecution` is fully typed -2. rebuild completion shaping moved into runtime helper -3. `buildRecoveryBundle()` removed repeated host-side assembly - -Evidence: - -1. `0bcfc678d` -2. `ded84b25e` - -### Batch 5: Recovery Binding Factory Extraction - -Goal: - -1. move recovery bundle assembly into the backend-binding layer - -Status: - -1. delivered - -Delivered result: - -1. `block_recovery.go` no longer constructs `Reader/Pinner/StorageAdapter/Executor` - directly -2. `v2bridge.BuildRecoveryBundle()` became the concrete backend-binding seam - -Evidence: - -1. `263611004` - -### Batch 6: Recovery Context Resolver Extraction - -Goal: - -1. make one resolver own the host-side recovery context - -Status: - -1. delivered - -Delivered result: - -1. `resolveRecoveryContext()` owns: - - `volPath` - - `rebuildAddr` - - bundle construction - - replica flushed progress lookup -2. `runCatchUp()` / `runRebuild()` now read as: - - resolve - - plan - - branch - -Evidence: - -1. `a48da0f67` -2. `41082bf92` - -### Batch 7: Command Dispatch Split - -Goal: - -1. move command-switch orchestration out of `volume_server_block.go` -2. keep it out of `v2bridge` - -Status: - -1. delivered - -Delivered result: - -1. `weed/server/blockcmd` owns command dispatch -2. `weed/server` keeps host effects -3. `v2bridge` remains free of `engine.Command` switch / event-emission - semantics - -Evidence: - -1. `11c6aaf31` - -### Batch 8: BlockVol Command-Binding Extraction - -Goal: - -1. move concrete `BlockVol`-backed command operations out of - `volume_server_block.go` - -Status: - -1. delivered - -Delivered result: - -1. `v2bridge.CommandBindings` owns: - - role apply binding - - receiver startup binding - - primary shipper configuration binding - - shipper-connected probe -2. `weed/server` still owns readiness-state updates and event semantics - -Evidence: - -1. `38b504299` - -### Batch 9: Non-BlockVol Service-Ops Extraction - -Goal: - -1. move the remaining non-`BlockVol` command operations out of - `volume_server_block.go` into the server-adapter layer - -Status: - -1. delivered - -Delivered result: - -1. `weed/server/blockcmd.ServiceOps` owns: - - recovery-task startup - - pending catch-up/rebuild execution - - sender invalidation through projection + resolver -2. `volume_server_block.go` now keeps: - - host effects - - backend-facing thin wrappers - - assignment/event ingress - -Evidence: - -1. `38b504299` - -### Batch 10: Host-Effects Adapter Extraction - -Goal: - -1. move the remaining command-completion host effects out of - `volume_server_block.go` while keeping them on the `weed/server` side - -Status: - -1. delivered - -Chosen slice: - -1. `10A`: extract a dedicated server-side host-effects adapter into - `weed/server/blockcmd` -2. keep this slice bounded to: - - `RecordCommand` - - `EmitCoreEvent` - - `PublishProjection` - - projection-cache write routing -3. do not fold backend-side readiness mutation into this first cut - -Acceptance: - -1. `coreCommandEffects` is no longer defined in `volume_server_block.go` -2. `PublishProjection` cache-write logic is no longer inline in - `volume_server_block.go` -3. `weed/server` still owns host-effect semantics, but exposes them through a - thinner adapter object -4. focused proofs remain green - -Delivered result: - -1. `weed/server/blockcmd/host_effects.go` now owns the concrete dispatcher-side - host-effects adapter -2. `volume_server_block.go` now only wires recorder/event/cache dependencies - into that adapter -3. server-owned projection cache writing moved behind `BlockService.StoreProjection()` - -Evidence: - -1. working tree change on top of `38b504299` - -### Batch 11: Stop-Line Review For Readiness Mutation - -Goal: - -1. decide whether the remaining adapter-local readiness mutation should move out - of `volume_server_block.go` - -Status: - -1. delivered - -Decision: - -1. stop at the current package boundary -2. do not extract readiness-state mutation into `weed/server/blockcmd` - -Reason: - -1. the remaining methods are not dispatcher-side host effects -2. they are direct writes to `BlockService`-owned `replStates` -3. they encode adapter-local cache/state semantics, not reusable command - orchestration logic -4. moving them into `blockcmd` would mostly add callback indirection without - clarifying ownership - -Covered methods: - -1. `noteRoleApplied` -2. `markPrimaryTransportConfigured` -3. `markReceiverReady` -4. `ReadinessSnapshot` remains the read-side consumer of the same local state - -Accepted stop line: - -1. `weed/server/blockcmd` - - owns dispatch, service ops, and host-effects adapter -2. `weed/server` - - owns host state fields and adapter-local readiness/cache mutation -3. `weed/storage/blockvol/v2bridge` - - owns concrete backend bindings only - -## Current Position - -The separation line is now in the late-stage thinning phase. - -Current split: - -1. `sw-block` - - canonical contracts / helpers - - runtime coordination helpers -2. `weed/storage/blockvol/v2bridge` - - `BlockVol`-backed recovery and command bindings -3. `weed/server/blockcmd` - - command dispatch, service-side command operations, and host-effects adapter -4. `weed/server` - - assignment ingress, product integration, and adapter-local readiness/cache state - -## Non-Claims - -`Phase 17` does not yet claim: - -1. every remaining host-side helper must move -2. full deletion of compatibility-only paths -3. that `weed/server` becomes empty or trivial - -The stop line is practical, not ideological: - -1. keep real host/product integration in `weed/server` -2. keep backend binding in `v2bridge` -3. keep reusable semantics/runtime helpers out of both - -## Immediate Next Step - -The current separation stop line is now explicit: - -1. keep dispatcher-side logic in `weed/server/blockcmd` -2. keep backend bindings in `weed/storage/blockvol/v2bridge` -3. keep `BlockService` local state mutation in `weed/server` - -Any next task should now be one of two kinds: - -1. cleanup inside the accepted stop line -2. a new semantic/runtime phase, not another ownership-shuffle task +# Phase 17 + +Date: 2026-04-04 +Status: active +Purpose: turn the bounded `Phase 16` runtime checkpoint into a bounded +product-claim checkpoint with explicit recovery/failover scope, disturbance +policy, and launch-envelope boundaries + +## Why This Phase Exists + +`Phase 16` closed the visible bounded runtime seams on the chosen path: + +1. steady-state and bounded restart reconstruction preserve accepted explicit + truth +2. sparse heartbeats no longer silently erase accepted truth +3. empty full-inventory delete behavior is explicit rather than heuristic + +That is enough to stop `Phase 16`. + +It is not enough to make a stronger product statement yet. + +The next missing work is larger than heartbeat-field closure: + +1. broader recovery-loop closure across more lifecycle branches +2. failover/publication whole-chain statement +3. long-window restart/disturbance policy +4. first-launch envelope freeze + +This phase exists to package those larger objects explicitly instead of +continuing indefinite micro-slicing. + +## Supersession Note + +This document supersedes the earlier `Phase 17` separation-tracking draft. + +That older draft was useful as an engineering migration record, but it is no +longer the right active phase object after the `Phase 16` finish-line +checkpoint. + +For current planning: + +1. use this file as the active `Phase 17` definition +2. treat any older separation-tracking notes only as historical context + +## Relationship To Phase 16 + +`Phase 16` answered: + +1. who owns bounded runtime semantics on the chosen path +2. whether the heartbeat/master/API path can preserve accepted explicit truth + +`Phase 17` is different. + +It answers: + +1. which broader recovery/failover branches are actually closed +2. what stronger outward/publication statement is supportable +3. what long-window disturbance behavior is policy, not accident +4. what the first supported launch envelope really is + +In short: + +1. `Phase 16` = bounded runtime checkpoint +2. `Phase 17` = bounded product-claim checkpoint + +## Phase Goal + +Produce one bounded post-`Phase 16` checkpoint where: + +1. the broader recovery-loop branch map is finite and explicitly classified +2. at least one stronger failover/publication whole-chain statement is defined + and proven +3. long-window restart/disturbance behavior is reduced to explicit policy or + explicit non-claim +4. the first supported launch envelope is frozen from accepted evidence + +## Scope + +### In scope + +1. broader recovery-loop branch mapping and classification +2. stronger outward/publication consistency statement after failover +3. restart/rejoin/repeated-failover policy on the chosen path +4. supported-envelope and explicit exclusion freeze +5. proof-package and review artifact for the resulting claim boundary + +### Out of scope + +1. broad protocol rediscovery +2. broad transport-matrix expansion +3. `RF>2` general product closure +4. indefinite soak/pilot execution inside this phase +5. silent widening of runtime scope beyond the chosen path + +## Phase 17 Workstreams + +### `17A`: Broader Recovery-Loop Closure Map + +Goal: + +1. replace the current implicit branch set with one explicit recovery/lifecycle + map + +Acceptance object: + +1. the main recovery/lifecycle branches are listed explicitly +2. each branch is classified as: + - closed and proven + - partially proven + - residual / out of scope +3. there is no hidden "probably supported" branch left in wording only + +Target branch classes: + +1. steady-state failover +2. restart same-lineage reconstruction +3. restart after ownership change +4. replica rejoin after demotion/promotion +5. repeated failover in one disturbance window +6. startup not-yet-authoritative window +7. degraded-but-not-rebuild path +8. rebuild-entry / rebuild-exit path + +Status: + +1. delivered as first branch-map slice + +Current chosen map: + +1. steady-state failover + - classification: partially proven + - current evidence: + - `TestP12P1_FailoverPublication_Switch` + - `TestP11P3_Failover_PublicationSwitches` + - failover timer/promotion tests in `qa_block_cp11b3_adversarial_test.go` + - current gap: + - stronger whole-chain outward publication contract still belongs to `17B` +2. restart same-lineage reconstruction + - classification: closed and proven on the bounded chosen path + - current evidence: + - `TestP12P1_Restart_SameLineage` + - `TestP11P3_HeartbeatReconstruction` + - `TestMasterRestart_HigherEpochWins` + - current boundary: + - bounded chosen path only, not generic restart-product proof +3. restart after ownership change + - classification: partially proven + - current evidence: + - `TestMasterRestart_HigherEpochRebasesExplicitPrimaryTruth` + - `TestMasterRestart_HigherEpochSparsePrimaryClearsOldExplicitTruth` + - `TestMasterRestart_LowerEpochBecomesReplica` + - current gap: + - ownership truth rebasing is proven, but broader outward failover statement + is not yet frozen +4. replica rejoin after demotion/promotion + - classification: partially proven + - current evidence: + - `TestMasterRestart_ReplicaHeartbeat_AddedCorrectly` + - `TestMasterRestart_DuplicateReplicaHeartbeat_NoDuplicate` + - `TestQA_CP82_MasterRestart_ReconstructReplicas_ThenFailover` + - current gap: + - rejoin semantics are only boundedly covered, not elevated to a full branch + contract +5. repeated failover in one disturbance window + - classification: partially proven + - current evidence: + - `TestP12P1_RepeatedFailover_EpochMonotonic` + - `TestQA_T2_RF3_OrphanedPrimary_BestReplicaPromoted` + - `TestQA_T3_OrphanDeferredTimer_FiresAndPromotes` + - current gap: + - broader repeated-disturbance publication coherence is not yet a closed + product claim +6. startup not-yet-authoritative window + - classification: partially proven + - current evidence: + - `TestStartBlockService_ScanFailureEmitsNonAuthoritativeInventory` + - `TestRegistry_UpdateFullHeartbeatWithInventoryAuthority_NonAuthoritativeEmptyDoesNotDelete` + - `TestQA_Reg_FullHeartbeatEmptyServer` + - current gap: + - one real sender path exists, but long-window startup policy remains for + `17C` +7. degraded-but-not-rebuild path + - classification: partially proven + - current evidence: + - bounded `Phase 15/16` readiness/publication/mode tests + - `EntryToVolumeInfo` and block-volume handler coherence proofs + - current gap: + - current evidence proves bounded surface truth, not full lifecycle policy +8. rebuild-entry / rebuild-exit path + - classification: partially proven + - current evidence: + - `16B-16K` bounded recovery execution ownership + - `TestQA_Rebuild_FullCycle_CreateFailoverRecoverRebuild` + - `TestQA_RF3_Rebuild_DeadReplicaCatchesUp` + - current gap: + - branch exists and is exercised, but broader recovery-loop closure is not + yet claimed + +Delivered result: + +1. `Phase 17` now has one explicit recovery/lifecycle branch inventory instead + of an implicit "some broader runtime remains" statement +2. the current state is now separated into: + - one branch already closed on the bounded chosen path + - several branches with real bounded evidence but not yet product-grade + closure +3. this narrows the next work: + - `17B` should focus on outward failover/publication statement + - `17C` should focus on long-window policy for the partially proven branches + +Evidence basis: + +1. `Phase 16` finish-line review and proof package +2. restart and heartbeat tests in `master_block_registry_test.go` +3. disturbance/publication QA tests in `weed/server/qa_block_*_test.go` + +### `17B`: Failover / Publication Whole-Chain Statement + +Goal: + +1. strengthen from internal truth preservation to an outward statement that can + be used in product review + +Acceptance object: + +1. one explicit failover/publication contract is written down +2. the contract names which outward surfaces must stay coherent: + - mode + - reason + - readiness + - publish health + - publication/lookup visibility +3. at least one full failover chain is proven against that contract +4. any allowed transient inconsistency window is explicit + +Status: + +1. delivered as first contract-draft slice + +Current chosen contract: + +On the bounded chosen path, once failover has completed and the winning primary +assignment has been delivered/applied, the following must hold for one named +volume: + +1. publication ownership + - outward lookup/publication points to the winning primary, not the old + primary +2. publication address coherence + - publication-facing transport fields exposed by lookup agree with the + registry entry for the winning primary +3. failover surface coherence + - failover changes publication visibility/address truth rather than leaving + stale old-primary publication outwardly visible +4. restart reconstruction compatibility + - heartbeat reconstruction and restart-era registry truth do not break the + same bounded publication contract + +Current bounded whole-chain: + +1. create on chosen path +2. establish primary publication truth +3. trigger failover +4. promote winning primary +5. deliver winning-primary assignment through the real VS path +6. verify outward lookup/publication now points to the new primary and agrees + with registry truth + +Bounded proven surfaces: + +1. `LookupBlockVolume()` +2. registry-backed publication fields +3. heartbeat reconstruction path used by restart recovery + +Explicitly not yet included in this first contract draft: + +1. full list/status/UI surface coherence after failover +2. long-window transient behavior before the winning assignment is delivered +3. every repeated-failover publication sequence +4. generic frontend/transport matrix guarantees beyond the chosen path + +Allowed transient window on the current contract: + +1. before failover completion and winning-primary assignment delivery, this + contract does not yet require all outward surfaces to have converged +2. after that point, bounded lookup/publication truth must reflect the winning + primary and must not still expose stale old-primary publication + +Delivered result: + +1. `Phase 17` now has one explicit failover/publication whole-chain statement + instead of only a general "publication should switch" expectation +2. the strongest currently supportable statement is now bounded to: + - failover completion + - winning assignment delivered/applied + - lookup/registry publication coherence on the chosen path +3. this makes the remaining work explicit: + - widen to more outward surfaces only with named evidence + - move long-window and pre-convergence behavior to `17C` + +Evidence basis: + +1. `TestP11P3_Failover_PublicationSwitches` +2. `TestP12P1_FailoverPublication_Switch` +3. `TestP11P3_HeartbeatReconstruction` +4. failover/promotion tests in `qa_block_cp11b3_adversarial_test.go` + +Current gap after first contract draft: + +1. the contract is strong enough for one bounded product-review statement +2. it is not yet a broad whole-surface publication proof +3. `17C` must define the long-window and pre-convergence policy around this + contract + +### `17C`: Long-Window Restart / Disturbance Policy + +Goal: + +1. turn restart/disturbance behavior into explicit policy instead of continuing + local seam repair + +Acceptance object: + +1. startup/restart/rejoin/disturbance cases are grouped into a finite policy set +2. each case has one of: + - explicit runtime rule + - explicit temporary inconsistency policy + - explicit non-claim +3. "not yet authoritative" states are described as policy, not inferred only + from code shape + +Target disturbance classes: + +1. startup inventory not yet authoritative +2. repeated restart before convergence +3. rejoin with stale ownership/publication context +4. repeated failover during one disturbance window +5. long-window degraded heartbeat sparsity + +Status: + +1. delivered as first policy-draft slice + +Current chosen policy table: + +1. startup inventory not yet authoritative + - policy type: explicit runtime rule + - rule: + - non-authoritative empty full heartbeat must preserve existing entries + - authoritative empty full heartbeat may still drive stale-delete + - evidence: + - `TestStartBlockService_ScanFailureEmitsNonAuthoritativeInventory` + - `TestRegistry_UpdateFullHeartbeatWithInventoryAuthority_NonAuthoritativeEmptyDoesNotDelete` + - `TestRegistry_UpdateFullHeartbeatWithInventoryAuthority_AuthoritativeEmptyStillDeletes` + - current non-claim: + - this does not yet define broad long-window startup behavior for every + delayed-load or multi-step bootstrap case +2. repeated restart before convergence + - policy type: explicit temporary inconsistency policy + - rule: + - until winning-primary assignment is delivered/applied, full outward + convergence is not yet required by the current bounded contract + - after delivery/applied, registry epoch/publication truth must not regress + - evidence: + - `TestP12P1_Restart_SameLineage` + - `TestP11P3_HeartbeatReconstruction` + - `TestMasterRestart_HigherEpochWins` + - current non-claim: + - this is not yet generic proof for arbitrarily long repeated restart + windows +3. rejoin with stale ownership/publication context + - policy type: explicit runtime rule + - rule: + - stale old-epoch or stale old-role input must not overwrite the winning + ownership/publication truth + - replica rejoin may reconstruct bounded replica state without becoming the + new publication owner merely by reconnecting + - evidence: + - `TestP12P1_StaleSignal_OldEpochRejected` + - `TestMasterRestart_LowerEpochBecomesReplica` + - `TestMasterRestart_ReplicaHeartbeat_AddedCorrectly` + - current non-claim: + - broader rejoin policy across all frontend/publication surfaces remains + outside this first draft +4. repeated failover during one disturbance window + - policy type: explicit temporary inconsistency policy + - rule: + - repeated failover may create a bounded convergence window + - epoch must still move monotonically and duplicate-promotion shapes must + not become accepted steady state + - evidence: + - `TestP12P1_RepeatedFailover_EpochMonotonic` + - `TestQA_T2_RF3_OrphanedPrimary_BestReplicaPromoted` + - `TestQA_T3_OrphanDeferredTimer_FiresAndPromotes` + - current non-claim: + - this is not yet a broad user-visible publication-stability guarantee under + arbitrary oscillation +5. long-window degraded heartbeat sparsity + - policy type: explicit runtime rule + - rule: + - once accepted on the bounded path, explicit degraded/mode/readiness truth + must not be silently erased by later sparse heartbeats on existing entries + - degraded state remains degraded until bounded readiness/publication truth + closes again + - evidence: + - `TestRegistry_UpdateFullHeartbeat_MissingFieldsPreserveAcceptedExplicitPrimaryTruth` + - `TestRegistry_UpdateFullHeartbeat_ReplicaReadyMissingFieldPreservesAcceptedExplicitTruth` + - degraded surface proofs in `master_block_observability_test.go` and + `master_server_handlers_block_test.go` + - current non-claim: + - this does not yet claim indefinite sparse-heartbeat tolerance on every + lifecycle branch + +Delivered result: + +1. `Phase 17` now has a finite disturbance-policy table instead of only a + general "restart/disturbance still remains" statement +2. the current policy shape is explicit about which cases are: + - hard runtime rules + - bounded temporary inconsistency windows + - still non-claims +3. this reduces the remaining ambiguity before launch-envelope work + +Evidence basis: + +1. `Phase 16` finish-line proof package +2. restart/disturbance tests in `qa_block_disturbance_test.go` +3. restart/heartbeat truth-retention tests in `master_block_registry_test.go` +4. expand/empty-heartbeat disturbance tests in `qa_block_expand_adversarial_test.go` + +Current gap after first policy draft: + +1. the policy table is sufficient for bounded claim hygiene +2. it is not yet a broad production hardening or soak statement +3. `17D` must freeze the supported launch envelope using these explicit rules + and non-claims + +### `17D`: Launch Envelope Freeze + +Goal: + +1. freeze the first supported product envelope from accepted `Phase 12-17` + evidence + +Acceptance object: + +1. supported topology/transport matrix is explicit +2. explicit exclusions are written down +3. launch-blocking vs post-launch items are separated +4. every launch claim maps back to accepted evidence +5. missing evidence remains an explicit constraint rather than silent support + +Status: + +1. delivered as first launch-envelope draft + +Current chosen launch envelope: + +1. replication and durability envelope + - supported: + - `RF=2` + - `sync_all` + - evidence basis: + - `C-RF2-SYNCALL-CONTRACT` + - `CP13-1..9` + - `C-PHASE16-RUNTIME-CHECKPOINT` +2. control/runtime envelope + - supported: + - existing master / volume-server heartbeat path + - bounded `Phase 16` runtime checkpoint + - bounded `Phase 17A-17C` claim/policy envelope + - evidence basis: + - `Phase 10` accepted control-plane closure + - `Phase 16` finish-line review + - current `phase-17.md` +3. backend/runtime envelope + - supported: + - `blockvol` as execution backend + - `v2bridge` as backend-binding adapter + - explicit `V2 core` as semantic owner + - evidence basis: + - `Phase 09` execution closure + - `Phase 14-16` accepted checkpoints +4. frontend/product-surface envelope + - supported on the bounded chosen path: + - `iSCSI` + - bounded `CSI` integration + - bounded `NVMe` publication/integration already accepted on the chosen path + - current launch-reading rule: + - these surfaces are only supported inside the same bounded chosen envelope, + not as generic transport-matrix approval +5. operating-mode envelope + - supported: + - bounded failover/publication statement from `17B` + - bounded restart/disturbance policy from `17C` + - current launch-reading rule: + - use the explicit `17B` contract and `17C` policy table as the launch + interpretation boundary + +Explicit exclusions in the first draft: + +1. `RF>2` +2. broad transport/frontend matrix support beyond the chosen path +3. broad whole-surface failover/publication proof +4. generic long-window soak or pilot success as production proof +5. broad restart-window behavior outside the explicit `17C` policy table +6. broad launch approval beyond the named bounded envelope + +Launch-blocking items: + +1. no review outcome yet for the full `Phase 17` package +2. no pilot pack/preflight/stop-condition artifact yet +3. no controlled-rollout review artifact yet +4. no explicit broader failover/publication claim beyond the bounded `17B` + contract + +Explicitly not launch-blocking inside this first draft: + +1. lack of generic `RF>2` support +2. lack of broad transport-matrix support +3. lack of broad rollout approval +4. lack of indefinite soak proof inside this phase + +Claim-mapping rule: + +1. any first-launch claim must map back to: + - `Phase 12 P4` bounded floor / rollout-gate evidence + - `CP13` bounded contract and workload evidence + - `Phase 16` bounded runtime checkpoint + - `Phase 17A-17C` branch/contract/policy framing +2. if a claim cannot map back to one of those named evidence anchors, it belongs + in exclusions or later productionization work, not in the first-launch + envelope + +Delivered result: + +1. the first launch envelope is now finite instead of implied +2. supported scope, exclusions, and launch blockers are all named in one place +3. this gives the product line a bounded pre-pilot statement without pretending + that broad launch approval already exists +4. the phase now has explicit review/checkpoint and supported-matrix artifacts: + - `sw-block/.private/phase/phase-17-checkpoint-review.md` + - `sw-block/design/v2-first-launch-supported-matrix.md` + +Evidence basis: + +1. `Phase 12 P4` bounded floor / rollout-gate package +2. `CP13-1..9` bounded contract/workload/mode evidence +3. `Phase 16` finish-line checkpoint +4. `Phase 17A-17C` branch/contract/policy drafts +5. `v2-protocol-claim-and-evidence.md` +6. `sw-block/.private/phase/phase-17-checkpoint-review.md` +7. `sw-block/design/v2-first-launch-supported-matrix.md` + +Current gap after first envelope draft: + +1. the envelope is frozen as a bounded draft, not yet a full launch decision +2. pilot pack, preflight, stop conditions, and controlled rollout review remain + for productionization +3. broader claims still require either explicit new evidence or explicit + exclusion handling + +## Stop-Line Rule + +Do not keep widening `Phase 17` if a task requires: + +1. broad failover architecture redesign +2. broad transport-matrix expansion +3. generic production proof from pilot/soak behavior +4. implicit launch approval without explicit evidence mapping + +If one of those appears: + +1. stop the current slice +2. record it as a residual or productionization item +3. do not hide it inside a runtime-logic patch + +## Proof Shape + +The target proof posture for `Phase 17` is still an engineering proof package, +not a mathematical proof. + +Required shape: + +1. branch map + - finite recovery/lifecycle branch inventory +2. contract + - explicit failover/publication statement +3. policy table + - explicit disturbance and startup-window rules +4. envelope + - supported matrix and exclusions +5. review + - one checkpoint review artifact with claims, non-claims, residuals, and + exact proof commands + +## Phase Closeout Target + +`Phase 17` should close only when one checkpoint can credibly say: + +1. broader recovery-loop branches are named and classified +2. at least one stronger failover/publication whole-chain statement is proven +3. long-window disturbance behavior is explicit as rule or non-claim +4. the first launch envelope is frozen from accepted evidence +5. residual gaps are named instead of hidden + +## Non-Claims + +`Phase 17` should still not claim by default: + +1. broad generic production readiness +2. support for every restart/failover/disturbance branch +3. `RF>2` product closure +4. broad transport-matrix support +5. pilot success as generic production proof + +## Immediate Next Step + +After the first `17A` branch map, first `17B` contract draft, first `17C` +policy draft, and first `17D` envelope draft, stop `Phase 17` and package the +checkpoint before widening anything else. + +Reason: + +1. `17A` now makes the branch inventory explicit +2. `17B` now makes one bounded failover/publication contract explicit +3. `17C` now makes the long-window and pre-convergence policy explicit +4. `17D` now freezes the first supported launch envelope from those explicit + claims and non-claims +5. anything broader than that should enter productionization or a new explicit + contradiction-driven slice, not silently widen `Phase 17` +6. the next artifacts after this phase are: + - review outcome on `phase-17-checkpoint-review.md` + - productionization documents driven by `v2-first-launch-supported-matrix.md` diff --git a/sw-block/design/v2-first-launch-supported-matrix.md b/sw-block/design/v2-first-launch-supported-matrix.md new file mode 100644 index 000000000..c89399804 --- /dev/null +++ b/sw-block/design/v2-first-launch-supported-matrix.md @@ -0,0 +1,123 @@ +# V2 First-Launch Supported Matrix + +Date: 2026-04-04 +Status: draft +Purpose: freeze the first bounded launch envelope from accepted `Phase 12-17` +evidence, with explicit supported scope, explicit exclusions, and explicit +launch blockers + +## Reading Rule + +This document is a bounded support matrix. + +It does NOT mean: + +1. broad launch approval +2. generic production readiness +3. support for every failover/restart/disturbance branch +4. broad transport/frontend approval outside the named chosen path + +It means only: + +1. these are the strongest support statements currently justified by accepted + evidence +2. anything outside them is an exclusion, a blocker, or future + productionization work + +## Supported Matrix + +| Dimension | Supported in first draft | Boundary rule | Primary evidence | +|-----------|--------------------------|---------------|------------------| +| Replication factor | `RF=2` | bounded chosen path only | `CP13-1..7`, `C-RF2-SYNCALL-CONTRACT` | +| Durability mode | `sync_all` | bounded chosen path only | `CP13`, `v2-protocol-claim-and-evidence.md` | +| Control/runtime path | existing master / volume-server heartbeat path | same path as `Phase 10`, `Phase 16`, `Phase 17` checkpoints | `Phase 10`, `Phase 16` finish-line review | +| Semantic owner | explicit `V2 core` | semantics stay `V2`-owned even when implementation reuses `weed/` and `blockvol` | `Phase 14-16` | +| Execution backend | `blockvol` via `v2bridge` | reuse implementation; no V1 semantic inheritance | `Phase 09`, `Phase 14-16` | +| Product surfaces | bounded `iSCSI`, bounded `CSI`, bounded `NVMe` on the chosen path | not a generic transport matrix | `Phase 11`, publication tests, NVMe tests | +| Restart/failover reading | bounded `17B` + `17C` interpretation | use only the explicit contract and policy table from `Phase 17` | `phase-17.md`, `phase-17-checkpoint-review.md` | + +## Supported Statement + +The strongest currently supported first-launch statement is: + +1. on the bounded chosen `RF=2 sync_all` path, using the existing + master/volume-server heartbeat path, explicit `V2`-owned semantics and the + accepted `Phase 16-17` contract/policy package provide one finite support + envelope for bounded block product use +2. bounded `iSCSI`, `CSI`, and `NVMe` surfaces are supported only inside that + same chosen-path interpretation +3. failover/publication and disturbance behavior must be read through the + explicit `Phase 17` contract/policy package, not through broader inferred + product assumptions + +## Explicit Exclusions + +The following are OUTSIDE the first-launch supported matrix: + +1. `RF>2` +2. durability modes outside the accepted bounded envelope +3. broad transport/frontend matrix approval beyond bounded `iSCSI` / `CSI` / + `NVMe` chosen-path support +4. broad whole-surface failover/publication proof +5. broad restart-window behavior outside the explicit `17C` disturbance policy + table +6. generic soak/pilot success as production proof +7. broad rollout approval + +## Launch Blockers + +These are still required before this matrix can be read as a real launch +decision package: + +1. a frozen `Phase 17` checkpoint review outcome +2. a pilot pack with: + - preflight checklist + - success criteria + - stop / rollback conditions +3. controlled-rollout review artifacts +4. any additional evidence needed if the product wants claims broader than the + current bounded `17B/17C` contract/policy package + +## Not Launch-Blocking In This Draft + +These are intentionally NOT blockers for the bounded first-draft envelope: + +1. lack of `RF>2` support +2. lack of broad transport/frontend approval +3. lack of broad launch approval language +4. lack of generic soak proof inside the phase package itself + +## Claim Mapping Rule + +Any first-launch support claim must map back to accepted evidence in ALL of the +following layers: + +1. hardening/floor layer + - `Phase 12 P4` +2. contract/workload/mode layer + - `CP13-1..9` +3. runtime truth-closure layer + - `Phase 16` finish-line checkpoint +4. product-claim checkpoint layer + - `Phase 17A-17D` + +If a claim cannot map cleanly back through those layers: + +1. it is not in the first-launch matrix +2. it belongs in exclusions, blockers, or later productionization work + +## Operator Reading Guide + +When using this matrix, read it with these constraints: + +1. bounded chosen path first, not generic platform promise +2. explicit exclusions are real product boundaries, not temporary omissions +3. launch blockers are real blockers, not optional polish +4. pilot success later may validate this envelope, but cannot redefine it + +## Primary References + +1. `sw-block/.private/phase/phase-17.md` +2. `sw-block/.private/phase/phase-17-checkpoint-review.md` +3. `sw-block/design/v2-product-completion-overview.md` +4. `sw-block/design/v2-protocol-claim-and-evidence.md` diff --git a/sw-block/design/v2-phase-development-plan.md b/sw-block/design/v2-phase-development-plan.md index fdbae571d..9b34baeb8 100644 --- a/sw-block/design/v2-phase-development-plan.md +++ b/sw-block/design/v2-phase-development-plan.md @@ -1,6 +1,6 @@ # V2 Phase Development Plan -Date: 2026-04-02 +Date: 2026-04-04 Status: active Purpose: define the execution-oriented phase plan after the current candidate-path work, with explicit module status and target phase ownership @@ -35,22 +35,26 @@ Use these rules for all later phases: ## Current Baseline -Current accepted path through `Phase 13`, with `Phase 14` now the immediate next engineering focus: +Current accepted path now runs through the `Phase 16` finish-line checkpoint: 1. protocol/algo truth set is strong 2. engine recovery core is strong on the chosen path 3. control-plane closure is accepted on the chosen path 4. selected product-surface rebinding is accepted on the chosen path 5. bounded production hardening is accepted on the chosen path -6. one bounded accepted path exists for: - - `RF=2` - - `sync_all` - - existing master / volume-server heartbeat path - - `blockvol` as execution backend -7. `Phase 13` has now closed the bounded `WAL V1.5` contract package for the current constrained chosen path: - - real-workload package accepted - - assignment/publication closure accepted - - bounded mode normalization accepted +6. explicit `V2 core` extraction and adapter/projection rebinding are accepted as + bounded engineering structure +7. one bounded `V2`-native runtime checkpoint is now accepted for: + - `RF=2` + - `sync_all` + - existing master / volume-server heartbeat path + - `blockvol` as execution backend +8. `Phase 13` froze the bounded `WAL V1.5` contract package and `Phase 14-16` + carried that package forward into a bounded runtime-owned checkpoint: + - real-workload package accepted + - assignment/publication closure accepted + - bounded mode normalization accepted + - bounded heartbeat/restart truth closure accepted Phase-accounting note: @@ -60,28 +64,32 @@ Phase-accounting note: 4. `Phase 11` is closed 5. `Phase 12` is the accepted hardening baseline for the chosen path 6. `Phase 13` is closed and should be read as one bounded constrained-runtime contract package, not as launch approval -7. `Phase 14` is now the immediate next engineering focus: - - explicit `V2 core` extraction - - not more deepening of constrained-`V1` validation by default +7. `Phase 14` is closed as explicit `V2 core` extraction +8. `Phase 15` is closed as bounded adapter/projection rebinding +9. `Phase 16` is closed as a bounded `V2`-native runtime checkpoint, not as broad product/launch proof +10. the immediate next planning focus is now the productionization program plus the larger post-`Phase 16` gates: + - broader recovery/failover/publication statement + - launch-envelope freeze + - pilot/rollout discipline Important interpretation rule: 1. the accepted chosen path and claim/evidence set are real 2. the current `weed/` runtime structure is not automatically the final `V2` structure -3. until `Phase 14` establishes an explicit `V2 core`, current integrated tests should be read primarily as: - - `V1` runtime validation under `V2` constraints - - not proof that a completed `V2 runtime` already exists +3. even after the `Phase 16` finish-line checkpoint, current integrated evidence should still be read as: + - one bounded `V2`-owned runtime path on the chosen integration + - not broad proof for every recovery/failover/disturbance or launch scenario 4. future phases must treat: - `v2-protocol-claim-and-evidence.md` as current claim authority - `v2_mini_core_design.md` as engineering-structure authority - `v2-reuse-replacement-boundary.md` as reuse vs replacement authority -This means the next phases should focus mainly on: +This means the next work should focus mainly on: -1. extracting the long-term `V2 core` structure explicitly -2. rebinding `weed/` into adapter / projection / backend roles -3. closing one bounded `V2`-native runtime path before productionization -4. using `Phase 13` evidence as acceptance input rather than continuing to treat constrained-`V1` validation as the main workstream +1. keeping accepted `Phase 14-16` closure closed +2. turning the bounded runtime checkpoint into an explicit launch envelope +3. deciding broader failover/recovery/publication claims only through named evidence +4. using `Phase 13-16` evidence as acceptance input rather than reopening micro-seams by default ## Phase Roadmap @@ -414,6 +422,12 @@ Key files / ownership: 2. `sw-block/design/v2-phase14plus-semantic-framework.md` 3. `sw-block/engine/replication/` +Current status: + +1. complete as a bounded engineering-structure phase +2. accepted output is explicit `state / event / command / projection` ownership, + not broad live-runtime or launch proof + ### Phase 15: Adapter And Projection Rebinding Goal: @@ -463,6 +477,12 @@ Key files / ownership: 5. `weed/server/master_block_registry.go` 6. `weed/server/master_block_failover.go` +Current status: + +1. complete as bounded adapter/projection rebinding on the chosen path +2. accepted output is explicit adapter/projection ownership, not broad + runtime-closure or launch proof + ### Phase 16: V2-Native Runtime Closure Goal: @@ -497,6 +517,19 @@ Key files / ownership: 2. `weed/server/` 3. selected `weed/storage/blockvol/v2bridge/*` files +Current status: + +1. complete as a bounded runtime checkpoint through the `Phase 16` finish line +2. accepted checkpoint now covers: + - steady-state and bounded restart reconstruction preserve accepted explicit + truth on the chosen path + - sparse heartbeats do not silently erase already accepted truth + - empty full-inventory delete behavior is explicit rather than heuristic +3. non-claims remain explicit: + - not broad recovery-loop closure + - not broad failover/publication proof + - not launch / rollout readiness + ### Cross-Phase Review Rule For `Phase 14+` For any new transition, command, or projection rule in `Phase 14+`, require a @@ -572,25 +605,25 @@ Cross-cutting rules: | Module area | Current status | Current owner phase | Next target phase | Notes | | ----------- | -------------- | ------------------- | ----------------- | ----- | -| `sw-block/engine/replication` core FSM/orchestrator/driver | Strong long-term `V2 core` asset | `Phase 09` accepted, `Phase 13` active constraints | `Phase 14` | Main next work is explicit `state / event / command / projection` extraction, not reopening accepted semantics. | -| Engine executor real I/O boundary (`CatchUpIO` / `RebuildIO`) | Strong on chosen path | `Phase 09` accepted | `Phase 14/16` | Keep the boundary stable; later work is to connect it to explicit `V2 core` ownership and runtime closure. | -| `weed/storage/blockvol/v2bridge/control.go` | Strong boundary adapter on chosen path | `Phase 08/09/10` accepted | `Phase 15` | Remains a bridge between `V2` truth and runtime execution; should not accumulate new semantic authority casually. | -| `weed/storage/blockvol/v2bridge/reader.go` | Strong backend-facing adapter | `Phase 09` accepted | `Phase 15/16` | Mostly stable; later work is explicit boundary ownership and runtime proof, not new protocol semantics. | -| `weed/storage/blockvol/v2bridge/pinner.go` | Strong backend-facing adapter | `Phase 09` accepted | `Phase 15/16` | Retention safety is proven on the chosen path; later work is keeping it under explicit `V2` control boundaries. | -| `weed/storage/blockvol/v2bridge/executor.go` WAL scan | Strong backend-facing adapter | `Phase 09` accepted | `Phase 15/16` | Real execution path is closed on the chosen path; later work is core-driven runtime integration. | -| `v2bridge` `TransferFullBase` | Strong on chosen path | `Phase 09 P1` accepted | `Phase 16` | Execution closure is accepted; do not reopen casually unless core-driven runtime closure exposes a real contradiction. | -| `v2bridge` `TransferSnapshot` | Strong on chosen path | `Phase 09 P2` accepted | `Phase 16` | Execution closure is accepted; later work is bounded runtime closure rather than first-implementation discovery. | -| `v2bridge` `TruncateWAL` | Strong on chosen path | `Phase 09 P3` accepted | `Phase 16` | Narrow contract is accepted; later work is preserving that contract under explicit runtime ownership. | -| `weed/server/volume_server_block.go` V2 assignment intake | Adapter-boundary reality with accepted chosen-path closure | `Phase 10 P4` accepted, `Phase 13` contradiction pressure | `Phase 15` | This is where assignment/readiness/publication closure must become explicit adapter behavior rather than mixed service semantics. | -| `weed/server/block_recovery.go` live runtime ownership | V2-owned runtime truth on chosen path | `Phase 09/10` accepted | `Phase 15/16` | Serialized ownership is accepted; later work is making it cooperate with explicit `V2 core` and projection boundaries. | -| `weed/server/master_block_registry.go` / failover / handlers | Mixed projection/truth reality | `Phase 10-12` accepted surfaces | `Phase 15` | Should converge toward projection store + operator-visible truth surfaces rather than mixed business-logic/state storage. | -| `blockvol` WAL/flusher/checkpoint runtime | Reuse reality | Existing production code | `Phase 16` | Reuse implementation; do not let `V1` replication semantics redefine `V2` truth. | -| `blockvol` rebuild transport/server reality | Reuse with redesign boundary | Existing production code | `Phase 16` | Bounded chosen-path integration is accepted; later work is runtime closure under `V2` authority. | -| local server identity (`localServerID`) | Strong chosen-path rule with narrowed semantics | `Phase 10 P1` accepted, `Phase 13` constraints | `Phase 15` | Stable identity must remain distinct from transport address shape and explicit in later adapter/projection work. | -| Snapshot product path | Strong on chosen path | `Phase 11` accepted | `Phase 16` | Product-visible snapshot workflow is accepted on the chosen path; later work is preserving it under `V2`-native runtime closure. | -| `CSI` integration | Strong on chosen path | `Phase 11` accepted | `Phase 16` | Bounded controller/node lifecycle rebinding is accepted; later work is runtime preservation, not first rebinding. | -| `NVMe` / `iSCSI` front-ends | Strong on chosen path | `Phase 11` accepted | `Phase 16` | Publication/address truth rebinding is accepted; later work is proving the `V2`-driven runtime path beneath them. | -| Testrunner / infra / metrics | Strong support layer | existing | `Phase 13-16` | Reuse to validate contract closure, adapter contradictions, runtime closure, and later productization gates. | +| `sw-block/engine/replication` core FSM/orchestrator/driver | Strong long-term `V2 core` asset | `Phase 14` accepted, `Phase 16` runtime checkpoint accepted | Productionization / broader failover gate | Main next work is not new core extraction; it is using the accepted core as authority when deciding broader post-`Phase 16` claims. | +| Engine executor real I/O boundary (`CatchUpIO` / `RebuildIO`) | Strong on chosen path | `Phase 09` accepted, `Phase 16` integrated on bounded path | Productionization / broader recovery-loop gate | Keep the boundary stable; later work is broader runtime/failover evidence, not first implementation. | +| `weed/storage/blockvol/v2bridge/control.go` | Strong boundary adapter on chosen path | `Phase 15` accepted, `Phase 16` checkpoint accepted | Productionization | Remains a bridge between `V2` truth and runtime execution; should not accumulate new semantic authority casually. | +| `weed/storage/blockvol/v2bridge/reader.go` | Strong backend-facing adapter | `Phase 09` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / broader disturbance hardening | Mostly stable; later work is evidence under wider disturbance classes, not new protocol semantics. | +| `weed/storage/blockvol/v2bridge/pinner.go` | Strong backend-facing adapter | `Phase 09` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / broader disturbance hardening | Retention safety is proven on the chosen path; later work is long-window hardening rather than ownership redesign. | +| `weed/storage/blockvol/v2bridge/executor.go` WAL scan | Strong backend-facing adapter | `Phase 09` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / broader recovery-loop gate | Real execution path is closed on the chosen path; later work is broader runtime evidence. | +| `v2bridge` `TransferFullBase` | Strong on chosen path | `Phase 09 P1` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / broader recovery-loop gate | Execution closure is accepted; do not reopen casually unless broader runtime evidence exposes a real contradiction. | +| `v2bridge` `TransferSnapshot` | Strong on chosen path | `Phase 09 P2` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / launch-envelope gate | Execution closure is accepted; later work is first supported-envelope accounting. | +| `v2bridge` `TruncateWAL` | Strong on chosen path | `Phase 09 P3` accepted, `Phase 16` bounded runtime checkpoint accepted | Productionization / broader recovery-loop gate | Narrow contract is accepted; later work is preserving that contract under broader disturbance evidence. | +| `weed/server/volume_server_block.go` V2 assignment intake | Adapter-boundary reality with accepted chosen-path closure | `Phase 15` accepted, `Phase 16` finish-line checkpoint accepted | Productionization / broader failover gate | This boundary is now explicit on the chosen path; next work is wider gate evidence, not another rebinding phase. | +| `weed/server/block_recovery.go` live runtime ownership | V2-owned runtime truth on chosen path | `Phase 16` finish-line checkpoint accepted | Productionization / broader recovery-loop gate | Serialized ownership is accepted on the bounded path; later work is proving more of the surrounding loop without widening claims casually. | +| `weed/server/master_block_registry.go` / failover / handlers | Bounded projection/truth closure accepted on chosen path | `Phase 15` accepted, `Phase 16` finish-line checkpoint accepted | Productionization / broader failover/publication gate | Heartbeat/restart truth-closure seams are closed on the bounded path; remaining work is broader gate evidence and launch scoping. | +| `blockvol` WAL/flusher/checkpoint runtime | Reuse reality | Existing production code, bounded path accepted through `Phase 16` | Productionization / broader disturbance hardening | Reuse implementation; do not let `V1` replication semantics redefine `V2` truth. | +| `blockvol` rebuild transport/server reality | Reuse with redesign boundary | Existing production code, bounded path accepted through `Phase 16` | Productionization / broader recovery-loop gate | Bounded chosen-path integration is accepted; later work is wider disturbance/failover evidence under `V2` authority. | +| local server identity (`localServerID`) | Strong chosen-path rule with narrowed semantics | `Phase 10 P1` accepted, carried through `Phase 16` | Productionization / launch-envelope gate | Stable identity must remain distinct from transport address shape; next work is supported-envelope/accounting, not semantic redesign. | +| Snapshot product path | Strong on chosen path | `Phase 11` accepted, preserved through `Phase 16` | Productionization / launch-envelope gate | Product-visible snapshot workflow is accepted on the chosen path; next work is first supported envelope and exclusions. | +| `CSI` integration | Strong on chosen path | `Phase 11` accepted, preserved through `Phase 16` | Productionization / launch-envelope gate | Bounded controller/node lifecycle rebinding is accepted; next work is supported-matrix/accounting rather than first rebinding. | +| `NVMe` / `iSCSI` front-ends | Strong on chosen path | `Phase 11` accepted, preserved through `Phase 16` | Productionization / launch-envelope gate | Publication/address truth rebinding is accepted; next work is envelope freeze and broader incident-driven hardening. | +| Testrunner / infra / metrics | Strong support layer | existing, used through `Phase 13-16` checkpointing | Productionization | Reuse to validate launch-envelope gates, pilot packs, incident buckets, and broader hardening claims. | ## Completion-State Targets @@ -615,40 +648,50 @@ Use these rough targets to judge whether a phase is moving the product meaningfu If the goal is to maximize product completion efficiently, the recommended order is now: -1. keep `Phase 09-12` accepted closures closed and do not reopen them casually -2. keep `Phase 13` closed as the bounded `WAL V1.5` contract package -3. move next to `Phase 14` core extraction: - - explicit `state / event / command / projection` - - minimal `ApplyEvent() -> Decide() -> EmitCommands()` path -4. then `Phase 15` adapter/projection rebinding: - - assignment - - readiness - - publication - - diagnostics -5. then `Phase 16` bounded `V2`-native runtime closure -6. only then move to the productionization program: - - freeze launch envelope - - run limited internal pilot - - harden from incidents - - review controlled rollout +1. keep `Phase 09-16` accepted closures closed and do not reopen them casually +2. treat the `Phase 16` finish-line checkpoint as the bounded runtime stop-line, + not as a reason to continue indefinite micro-slicing +3. move next to the productionization program: + - `P0` launch-envelope freeze + - `P1` limited internal pilot pack + - `P2` incident-driven hardening loop + - `P3` controlled rollout review +4. only reopen runtime logic if broader failover/recovery/publication evidence + exposes a real contradiction +5. keep larger post-`Phase 16` gates explicit: + - broader recovery-loop closure + - broader failover/publication statement + - long-window restart/disturbance hardening The most important near-term engineering weight should now go to: -1. making `sw-block/engine/replication` the explicit long-term `V2 core` -2. keeping `weed/` changes bounded to adapter / projection / backend roles unless they are explicitly promoted into `V2`-owned authority -3. using `CP13-1..9` as acceptance input for new `V2 core` work rather than as a reason to keep extending constrained-`V1` validation +1. freezing the first supported launch envelope from accepted `Phase 12-16` + evidence +2. deciding what broader failover/recovery/publication claims are actually + supportable before widening product scope +3. keeping `weed/` changes bounded unless a real contradiction requires broader + runtime work ## Short Summary -The V2 line now has accepted execution, control, product-surface, and hardening closure on one bounded chosen path. +The V2 line now has an accepted bounded path through: -The next development plan should not jump directly from `Phase 12` to productionization. -It should move through four bounded engineering phases first: +1. execution closure +2. control-plane closure +3. product-surface rebinding +4. bounded hardening +5. constrained-runtime contract freeze +6. explicit `V2 core` extraction +7. adapter/projection rebinding +8. bounded `Phase 16` runtime closure -1. `Phase 13`: freeze the current `WAL V1.5` constrained-runtime contract package -2. `Phase 14`: extract the explicit `V2 core` -3. `Phase 15`: rebind `weed/` as adapter/projection reality -4. `Phase 16`: close one bounded `V2`-native runtime path +The roadmap should now stop treating `Phase 14-16` as future work. +Their bounded checkpoint is complete. -Only after that should the roadmap move into bounded launch-envelope freeze, internal pilot, incident-driven hardening, and controlled rollout review. +From here the practical plan is: + +1. freeze the first supported launch envelope +2. decide the larger post-`Phase 16` failover/recovery/publication claim boundary +3. run a limited internal pilot +4. harden from incidents without silently widening scope diff --git a/sw-block/design/v2-product-completion-overview.md b/sw-block/design/v2-product-completion-overview.md index e96c022e0..2a852e668 100644 --- a/sw-block/design/v2-product-completion-overview.md +++ b/sw-block/design/v2-product-completion-overview.md @@ -45,9 +45,9 @@ It already has: 2. accepted engine execution closure on the chosen path 3. accepted control-plane and product-surface rebinding on the chosen path 4. accepted hardening evidence for the bounded chosen path -5. an active `Phase 16` runtime-closure program that is moving live ownership - from host-local orchestration toward explicit core-driven command / event / - projection seams +5. an accepted `Phase 16` finish-line runtime checkpoint +6. an active `Phase 17` product-claim package that now makes broader branch, + contract, policy, and launch-envelope boundaries explicit The most important current distinction is: @@ -67,14 +67,14 @@ These levels are rough engineering estimates, not exact percentages. | Engine recovery core | Strong | Sender/session/orchestrator/driver/executor are substantially implemented and remain the semantic center. | | Weed bridge integration | Strong | Reader / pinner / control / executor are real and tested on the chosen path. | | Integrated candidate path | Strong on chosen path | Backend, control-plane, and selected product surfaces are accepted on one bounded chosen path. | -| Runtime ownership inside live server loop | Strong on bounded path, still widening | `Phase 16A-16I` now give one substantial core-command-driven runtime path, but broad recovery-loop closure is not yet claimed. | +| Runtime ownership inside live server loop | Strong on bounded checkpoint | `Phase 16` finish-line closed the bounded runtime checkpoint; broader lifecycle closure is now handled as explicit `Phase 17` product-claim work. | | Production-grade data transfer | Strong on chosen path | `TransferFullBase` and `TransferSnapshot` execution closure are accepted on the chosen path; later work is hardening. | | Truncation / replica-ahead execution | Strong on chosen path | `TruncateWAL` narrow chosen-path closure is accepted; later work is hardening/planning improvement. | | End-to-end control-plane closure | Strong on chosen path | `Phase 10` accepted bounded end-to-end control-path closure on the chosen path. | | Product surfaces (`CSI`, `NVMe`, `iSCSI`, snapshot productization) | Strong on chosen path | `Phase 11` accepted bounded product-surface rebinding on the chosen path. | | Production hardening / ops | Strong on bounded path, not full launch proof | `Phase 12` closed the bounded hardening bar, but not the whole first-launch envelope. | | Multi-replica catch-up runtime ownership | Strong on bounded startup/execution path | `16F-16I` made command/event/pending/aggregation/startup ownership replica-scoped enough for the bounded primary multi-replica path. | -| Broad failover / publication / launch envelope | Partial | Main remaining product gap: prove wider runtime closure and freeze a supported launch envelope. | +| Broad failover / publication / launch envelope | Structured but still bounded | `Phase 17` now defines a branch map, bounded failover/publication contract, disturbance policy table, and first-launch envelope draft, but not broad launch approval. | ## Reuse Strategy @@ -156,41 +156,49 @@ For the chosen `RF=2 sync_all` path, the project can already claim: The biggest remaining product-completion gaps are no longer "invent the first working path". They are closure and launch-envelope gaps: -1. broader recovery-loop closure - - current `Phase 16` evidence is strong on one bounded runtime path, but not - yet a claim that all recovery lifecycle branches are core-owned end to end +1. broader recovery-loop closure beyond the current `17A` branch map + - branches are now classified explicitly, but most remain only partially + proven rather than broadly closed 2. broader failover / publication closure - - product-facing truth under failover, replay, and disturbance still needs a - stronger whole-chain statement, not only local runtime proofs -3. restart / disturbance preservation - - accepted behavior must remain correct under restart, rejoin, repeated - failover, and address churn without reopening semantic ambiguity -4. long-run / soak / performance floor - - accepted behavior must remain stable under longer operation with explicit - floor numbers and bounded rollout gates -5. launch-envelope freeze - - the first supported launch matrix, exclusions, operator expectations, and - stop conditions must be written down explicitly + - `17B` now defines one bounded whole-chain statement, but not yet a broad + whole-surface publication proof +3. restart / disturbance preservation outside the current `17C` policy table + - current long-window behavior is now policy-shaped, but not yet a broad + production hardening statement +4. pilot / rollout package + - the first launch envelope is now drafted, but pilot pack, preflight, stop + conditions, and rollout review artifacts are still missing +5. long-run / soak / performance extension beyond the bounded floor + - `Phase 12 P4` remains the bounded floor; broader confidence still belongs to + later productionization ## Recommended Completion Roadmap -### Stage 1: Finish `Phase 16` runtime closure cleanly +### Stage 1: Review And Freeze The `Phase 17` Checkpoint Target: -1. close the next bounded `Phase 16` runtime gap with explicit bounds and - package one clear reviewable runtime checkpoint +1. package the current `Phase 17` branch/contract/policy/envelope work into one + clear reviewable product-claim checkpoint + +Status: + +1. in progress Main output: -1. one accepted bounded `V2`-native runtime path that is explicit about what is - core-owned, what is adapter-owned, and what is still only compatibility -2. one short list of residual recovery-loop gaps after `16I` +1. one `Phase 17` checkpoint review artifact +2. one first-launch supported-matrix artifact +3. one bounded statement of: + - branch map + - failover/publication contract + - disturbance policy + - launch envelope Why it matters: -This is now the main semantic engineering blocker between a strong bounded path -and a launchable product statement. +This is now the main boundary-setting blocker between a strong bounded path and a +bounded launch decision package. ### Stage 2: Freeze the first supported launch envelope @@ -201,12 +209,13 @@ Target: Status: -1. not yet frozen +1. first draft frozen inside `Phase 17` +2. not yet accepted as a launch decision package Main work: -1. define the supported environment / replication / durability matrix -2. define explicit exclusions that remain outside the first launch claim +1. accept or refine the bounded supported matrix +2. accept or refine explicit exclusions outside the first launch claim 3. bind product-facing surfaces to the named supported envelope 4. define preflight, success, and stop conditions @@ -261,33 +270,33 @@ The most important gates from here are: If the goal is to maximize product completion efficiently: 1. do not reopen accepted execution, control-plane, or product-surface semantics casually -2. treat the remaining `Phase 16` work as runtime-closure work, not as another - round of broad redesign -3. finish the next bounded recovery-loop gaps before claiming more product scope -4. then freeze the first supported launch envelope -5. then run a limited internal pilot -6. then widen only through explicit incident review and rollout-gate review +2. treat `Phase 16` as closed at its finish-line checkpoint +3. use `Phase 17` to keep branch/contract/policy/envelope claims explicit and + bounded +4. then run a limited internal pilot +5. then widen only through explicit incident review and rollout-gate review In short: -1. runtime closure first -2. launch-envelope freeze second +1. runtime checkpoint first +2. product-claim / launch-envelope freeze second 3. bounded productionization third ## Short Summary The V2 line is already beyond "algorithm only". It has an accepted bounded chosen path through backend, control-plane, selected -product surfaces, bounded hardening, and substantial `Phase 16` runtime closure. +product surfaces, bounded hardening, an accepted `Phase 16` runtime checkpoint, +and an active `Phase 17` product-claim package. The main remaining work is not "build the first real thing". It is: -1. finish broader recovery-loop and failover/publication closure strongly enough - for a product statement -2. freeze the first supported launch envelope from accepted evidence -3. run a limited internal pilot with explicit stop conditions -4. harden from incidents without silently broadening scope +1. finish review/freeze of the bounded `Phase 17` branch/contract/policy/envelope + package +2. run a limited internal pilot with explicit stop conditions +3. harden from incidents without silently broadening scope +4. only broaden claims when new evidence supports them That is the practical path from the current bounded runtime-complete candidate to a bounded first-launch block product. diff --git a/sw-block/design/v2-protocol-claim-and-evidence.md b/sw-block/design/v2-protocol-claim-and-evidence.md index ad74a1737..80e28952b 100644 --- a/sw-block/design/v2-protocol-claim-and-evidence.md +++ b/sw-block/design/v2-protocol-claim-and-evidence.md @@ -57,7 +57,7 @@ This is the bounded envelope currently allowed for active V2 claims: | Durability mode | `sync_all` | `v2-protocol-closure-map.zh.md`, `Phase 13` | | Control path | current master / volume-server heartbeat path | `v2-protocol-closure-map.zh.md` | | Execution backend | `blockvol` | `v2-protocol-closure-map.zh.md`, `v2-reuse-replacement-boundary.md` | -| Frontend in active validation | iSCSI | `Phase 11`, `CP13-8` | +| Frontend/product surfaces in bounded support envelope | iSCSI, CSI, NVMe on the chosen path | `Phase 11`, `Phase 17` | | Real-workload checkpoint | `CP13-8` | `Phase 13` | Current explicit exclusions: @@ -109,6 +109,8 @@ These are the claims that may currently be made without overreach. | `C-CONSTRAINED-V1-RUNTIME` | current integrated checks are evaluating `V1` runtime behavior under `V2` constraints rather than validating a completed `V2 runtime` | current chosen path only, until explicit `V2 core` extraction | `v2_mini_core_design.md`, `Phase 13` docs | allowed | | `C-MODE-NORMALIZATION` | one bounded mode-policy / normalization package is closed on the current constrained chosen path | bounded chosen path only; does not imply pure `V2 core` extraction or broad product policy | `CP13-9` docs/tests | allowed | | `C-PHASE16-RUNTIME-CHECKPOINT` | the bounded heartbeat/master/API runtime path now preserves accepted explicit truth across the delivered `16M-16W` restart/disturbance seams | bounded chosen path only; excludes broad recovery-loop, broad failover/publication, and launch claims | `sw-block/.private/phase/phase-16-finish-review.md`, `phase-16.md`, focused `weed/server` tests | allowed | +| `C-PHASE17-PRODUCT-CHECKPOINT` | the current broader recovery-branch map, bounded failover/publication contract, bounded disturbance policy table, and first-launch envelope draft are explicit for the chosen path | bounded chosen path only; excludes broad production readiness, broad transport/frontend approval, and broad whole-surface failover/publication proof | `sw-block/.private/phase/phase-17.md`, `sw-block/.private/phase/phase-17-checkpoint-review.md` | allowed | +| `C-FIRST-LAUNCH-ENVELOPE-DRAFT` | one bounded first-launch supported matrix is frozen as a draft with explicit exclusions and launch blockers | bounded chosen path only; not a launch decision, pilot approval, or rollout approval | `sw-block/design/v2-first-launch-supported-matrix.md` | allowed | | `C-LAUNCH-APPROVAL` | broad product launch readiness | outside current phase | future | not allowed | ## Evidence Map @@ -126,6 +128,9 @@ These are the claims that may currently be made without overreach. | Assignment/publication closure | assignment does not imply readiness/publication and corrected wiring refreshes replication truth explicitly | `CP13-8A` code/tests/debug evidence | tester investigation, bug docs | | Mode normalization | one bounded mode set is explicit and surface-consistent on the constrained current path | `CP13-9` contract/doc/tests | tester validation report | | Runtime truth closure under restart/disturbance | accepted explicit truth survives the delivered bounded `Phase 16` heartbeat/restart seams through `16W` | `phase-16-finish-review.md`, `phase-16.md`, focused restart/heartbeat tests in `weed/server` | `v2-product-completion-overview.md`, `v2-protocol-truths.md` | +| Failover/publication bounded contract | one bounded whole-chain statement is explicit for publication ownership/address coherence after failover completion and winning assignment delivery | `phase-17.md`, `phase-17-checkpoint-review.md`, publication/disturbance tests in `weed/server` | `v2-first-launch-supported-matrix.md` | +| Disturbance policy table | startup/restart/rejoin/repeated-failover/degraded-sparsity behavior is explicit as runtime rule, temporary inconsistency policy, or non-claim | `phase-17.md`, `phase-17-checkpoint-review.md`, restart/disturbance tests in `weed/server` | `v2-product-completion-overview.md` | +| First-launch supported matrix | one bounded launch envelope draft is explicit with supported scope, exclusions, and launch blockers | `v2-first-launch-supported-matrix.md` | `phase-17-checkpoint-review.md`, `Phase 12 P4`, `CP13`, `Phase 16` | ## Invalidated Or Narrowed Evidence