seaweedfs/sw-block/design/v2-third-migration-task-pack.md

V2 Third Migration Task Pack

Date: 2026-04-04 Status: active

Purpose

This note turns the third separation batch into validate-able engineering tasks.

The key remaining concentration is no longer in v2bridge, but in weed/server/block_recovery.go, where host wiring and reusable recovery coordination still live together.

Shared Rules

All tasks in this pack inherit these rules:

1. weed/server should remain the runtime host shell
2. reusable coordination should move toward sw-block
3. legacy no-core support may stay, but only as compatibility-only logic
4. no task in this pack may redefine recovery policy or core semantics

Task H: Pending Execution Coordinator Extraction

Goal

Extract pending-execution caching and fail-closed command matching from weed/server/block_recovery.go into reusable runtime helpers.

Source

1. weed/server/block_recovery.go
2. pendingRecoveryExecution
3. storePendingExecution
4. takePendingExecution
5. peekPendingExecution
6. hasPendingExecution
7. cancelPendingExecution
8. ExecutePendingCatchUp
9. ExecutePendingRebuild

Destination

1. reusable coordinator helpers in sw-block/engine/replication/runtime
2. thin host-side wiring in weed/server/block_recovery.go

Authority Rule

Pending execution ownership is runtime coordination logic. It belongs closer to the engine/runtime boundary than to the product adapter shell.

The host shell may store concrete handles, but it should not own the reusable matching/cancelation semantics.

Adapter Boundary

weed/ may:

1. supply concrete volume IDs, replica IDs, and IO bindings
2. trigger coordinator actions from host callbacks

weed/ must not:

1. keep the only implementation of fail-closed pending command matching
2. duplicate target-mismatch cancellation logic in multiple host sites

Acceptance

1. pending execution matching/cancelation logic is reusable outside weed/server
2. weed/server/block_recovery.go shrinks to host-side calls into that helper
3. fail-closed mismatch behavior remains explicit and covered

Validation

1. go test ./sw-block/engine/replication/...
2. go test ./weed/server -run "TestP16B_|TestP4_"

Current proof anchors

1. TestP16B_RunCatchUp_EscalatesNeedsRebuildIntoCoreProjection
2. TestP16B_RunRebuild_FailClosedWithoutFreshStartRebuildCommand
3. TestP4_LivePath_RealVol_ReachesPlan

Task I: Recovery Execution Helper Extraction

Goal

Extract reusable catch-up/rebuild plan execution helpers so weed/server supplies only:

1. concrete IO bindings
2. host callbacks
3. logging/context shell

Source

1. weed/server/block_recovery.go
2. runCatchUp
3. runRebuild
4. executeCatchUpPlan
5. executeRebuildPlan

Destination

1. reusable execution helpers in sw-block/engine/replication/runtime
2. thin host-side volume/session access in weed/server

Authority Rule

The engine still decides plan outcome. This task does not move policy.

What moves is the reusable execution-path coordination that applies an existing plan using supplied IO and emits the corresponding completion callbacks.

Adapter Boundary

weed/ may:

1. fetch real BlockVol and build concrete Reader / Pinner / Executor
2. look up sender/session state
3. host goroutines and cancellation contexts

weed/ must not:

1. remain the sole owner of reusable catch-up/rebuild execution wiring
2. mix host concerns and execution-helper concerns in one large function

Acceptance

1. reusable execution helper logic no longer requires weed/server ownership
2. runCatchUp and runRebuild become noticeably smaller host-shell methods
3. catch-up and rebuild still preserve the current bounded command-driven path

Validation

1. go test ./sw-block/engine/replication/...
2. go test ./weed/server -run "TestP16B_|TestP4_"
3. go test ./weed/server -run "TestBlockService_ApplyAssignments_(PrimaryRole_UsesCoreStartRecoveryTaskForCatchUp|RebuildingRole_UsesCoreRecoveryPathWithoutLegacyDirectStart)"

Current proof anchors

1. TestP16B_RunCatchUp_UpdatesCoreProjectionFromLiveRecovery
2. TestP16B_RunRebuild_UsesCoreStartRebuildCommandOnLivePath
3. TestP4_SerializedReplacement_DrainsBeforeStart
4. TestP4_ShutdownDrain

Task J: Legacy No-Core Isolation

Goal

Make no-core startup behavior explicitly legacy-scoped so the core-present path and the compatibility path are structurally separate.

Source

1. weed/server/block_recovery.go
2. HandleAssignmentResult
3. no-core branches inside runCatchUp and runRebuild
4. sw-block/design/v2-legacy-runtime-exit-criteria.md

Destination

1. explicit legacy-only entry points or helper section in weed/server
2. updated design note if the isolation shape needs to be recorded

Authority Rule

Legacy compatibility may remain, but it must stop looking like part of the mainline runtime owner path.

Adapter Boundary

weed/ may:

1. keep no-core compatibility while the product still needs it
2. retain legacy P4 coverage as compatibility guard

weed/ must not:

1. hide compatibility startup inside the same mainline path used for core-present ownership
2. let no-core behavior continue to blur the supported owner model

Acceptance

1. no-core startup paths are clearly labeled and structurally separated
2. core-present runtime ownership remains the obvious default path
3. legacy proofs remain compatibility-only and are not strengthened into semantic-authority claims

Validation

1. go test ./weed/server -run "TestP4_"
2. go test ./weed/server -run "TestP16B_|TestBlockService_ApplyAssignments_"

Current proof anchors

1. TestP4_LivePath_RealVol_ReachesPlan
2. TestP4_SerializedReplacement_DrainsBeforeStart
3. TestP4_ShutdownDrain
4. TestBlockService_ApplyAssignments_PrimaryRole_UsesCoreStartRecoveryTaskForCatchUp
5. TestBlockService_ApplyAssignments_RebuildingRole_UsesCoreRecoveryPathWithoutLegacyDirectStart

Recommended Execution Order

Recommended order:

1. Task H
2. Task I
3. Task J

Reason:

1. the pending coordinator is the narrowest reusable slice
2. execution helper extraction should build on that coordinator boundary
3. legacy isolation should happen after the mainline path is already cleaner