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

V2 Second Migration Task Pack

Date: 2026-04-04 Status: delivered

Purpose

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

The first batch proved that contract ownership and translation authority already belong in sw-block. The second batch now targets the remaining physical coupling: backend bindings.

Shared Rules

All tasks in this pack inherit these rules:

1. sw-block must not directly import weed/storage/blockvol
2. reusable execution-muscle logic should move toward sw-block
3. weed-side code should shrink toward thin concrete bindings
4. no task in this pack may redefine engine semantics or recovery policy

Task E: Reader Backend-Binding Extraction

Goal

Extract reusable reader logic from direct BlockVol coupling so the BlockVol-specific part becomes a thin snapshot binding.

Source

1. weed/storage/blockvol/v2bridge/reader.go
2. weed/server/block_recovery.go reader shim

Destination

1. reusable reader logic in sw-block/bridge/blockvol/runtime
2. thin BlockVol snapshot binding in weed/storage/blockvol/v2bridge

Authority Rule

The reusable logic that shapes backend snapshot data into bridge.BlockVolState belongs with sw-block execution muscles.

The weed-side binder may fetch snapshot fields from real BlockVol, but it must not own the reusable state-shaping layer.

Adapter Boundary

weed/ may:

1. call StatusSnapshot() on real BlockVol
2. expose raw backend snapshot data to the extracted layer

weed/ must not:

1. keep a second contract-shape mapping layer in block_recovery.go
2. reinterpret retained-history meaning

Acceptance

1. reusable reader logic no longer depends on direct BlockVol import
2. weed/storage/blockvol/v2bridge/reader.go is reduced to thin binding code
3. readerShimForRecovery is removed or reduced to trivial wiring

Validation

1. go test ./sw-block/bridge/blockvol
2. go test ./weed/storage/blockvol/v2bridge -run "TestReader_"
3. if the recovery shim changes, run:
   • go test ./weed/server -run "TestP4_|TestP16B_"

Current proof anchors

1. TestStorageAdapter_RetainedHistoryFromReader
2. TestReader_RealBlockVol_StatusSnapshot
3. TestReader_RealBlockVol_HeadAdvancesWithWrites

Task F: Pinner Backend-Binding Extraction

Goal

Extract hold bookkeeping and release lifecycle from direct BlockVol coupling so weed-side code only performs concrete retention-floor binding and state validation.

Source

1. weed/storage/blockvol/v2bridge/pinner.go
2. weed/server/block_recovery.go pinner shim

Destination

1. reusable hold bookkeeping in sw-block/bridge/blockvol/runtime
2. thin BlockVol retention binding in weed/storage/blockvol/v2bridge

Authority Rule

Hold bookkeeping is reusable execution-muscle logic. Concrete interaction with the flusher and StatusSnapshot() stays in weed/, but ID tracking and release symmetry should not require direct BlockVol imports.

Adapter Boundary

weed/ may:

1. install retention-floor callbacks on real BlockVol
2. validate requested hold positions against live backend snapshot state

weed/ must not:

1. keep reusable hold lifecycle ownership trapped in weed/
2. force recovery policy knowledge into the pinner binding

Acceptance

1. reusable hold bookkeeping can live in sw-block without BlockVol imports
2. weed-side pinner code shrinks toward concrete callback/state binding
3. pinnerShimForRecovery is removed or reduced to trivial wiring

Validation

1. go test ./sw-block/bridge/blockvol
2. go test ./weed/storage/blockvol/v2bridge -run "TestPinner_|TestBridge_"
3. if the recovery shim changes, run:
   • go test ./weed/server -run "TestP4_|TestP16B_"

Current proof anchors

1. TestStorageAdapter_WALPinRejectsRecycled
2. TestStorageAdapter_SnapshotPinRejectsUntrusted
3. TestStorageAdapter_PinReleaseSymmetry
4. TestPinner_RealBlockVol_HoldWALRetention
5. TestPinner_RealBlockVol_HoldRejectsRecycled

Task G: Executor Backend-Capability Extraction

Goal

Split executor logic into:

1. reusable orchestration that belongs with sw-block execution muscles
2. concrete backend capabilities and wire operations that remain in weed/

Source

1. weed/storage/blockvol/v2bridge/executor.go
2. related tests in:
   • weed/storage/blockvol/v2bridge/*transfer*
   • weed/storage/blockvol/v2bridge/*snapshot*
   • weed/storage/blockvol/v2bridge/*truncate*

Destination

1. reusable executor orchestration in sw-block/bridge/blockvol/runtime
2. thin backend capability bindings in weed/storage/blockvol/v2bridge

Authority Rule

The engine still owns recovery policy. This task does not move policy.

The reusable execution sequence for:

1. bounded WAL replay
2. full-base install plus second catch-up
3. snapshot transfer verification
4. truncate escalation boundary

should no longer be inseparable from direct BlockVol imports.

Adapter Boundary

weed/ may:

1. implement concrete backend operations on real BlockVol
2. own rebuild TCP framing and network transport while it still depends on blockvol protocol types

weed/ must not:

1. keep the whole recovery step orchestration trapped behind direct BlockVol imports when capability interfaces can be extracted
2. redefine engine-visible boundary meaning

Acceptance

1. executor reusable logic depends on extracted capability interfaces, not direct BlockVol imports
2. weed-side executor code is reduced to concrete backend/network bindings
3. outcome classification still remains outside the executor layer

Validation

1. go test ./sw-block/bridge/blockvol
2. go test ./weed/storage/blockvol/v2bridge -run "TestExecutor_|TestBridge_"
3. focused runtime integration still passes:
   • go test ./weed/server -run "TestBlockService_ApplyAssignments_(PrimaryRole_UsesCoreStartRecoveryTaskForCatchUp|RebuildingRole_UsesCoreRecoveryPathWithoutLegacyDirectStart)"

Current proof anchors

1. TestContract_BlockVolReaderInterface
2. TestExecutor_RealBlockVol_StreamWALEntries
3. TestExecutor_RealBlockVol_StreamPartialRange
4. TestExecutor_ErrorPaths

Recommended Execution Order

Recommended order:

1. Task E
2. Task F
3. Task G

Reason:

1. reader extraction is lowest risk and pure read-path
2. pinner extraction adds lifecycle but still avoids policy
3. executor extraction is the largest surface and should build on the previous two cuts

Delivery Note

Final outcome:

1. Task E was completed by code change
2. Task F was completed by code change
3. Task G was reviewed and confirmed already clean
4. after Batch 2, weed/server/block_recovery.go no longer carries reader/pinner shim types