seaweedfs/sw-block/design/v2-second-migration-batch.md

V2 Second Migration Batch

Date: 2026-04-04 Status: delivered

Purpose

This note defines the second migration batch for the sw-block separation work.

The first batch established contract ownership and canonical translation in sw-block. The second batch starts the next frontier: backend-binding extraction.

Batch Goal

Separate reusable execution-muscle logic from concrete BlockVol bindings so that more code can physically move toward sw-block without importing weed/storage/blockvol.

Batch Scope

In scope

1. reader backend-binding extraction
2. pinner backend-binding extraction
3. executor backend capability extraction
4. recovery-side shim reduction where those bindings are still copied manually

Out of scope

1. moving raw BlockVol backend code into sw-block
2. moving weed/server/block_recovery.go whole
3. redesigning the rebuild TCP protocol
4. changing engine semantics or recovery policy

Current Boundary Problem

After the first batch, the ownership split is better, but the reusable logic is still physically stuck next to BlockVol because:

1. weed/storage/blockvol/v2bridge/reader.go reads BlockVol directly
2. weed/storage/blockvol/v2bridge/pinner.go mixes hold bookkeeping with concrete retention-floor wiring
3. weed/storage/blockvol/v2bridge/executor.go mixes reusable recovery steps with concrete backend calls
4. weed/server/block_recovery.go still contains reader/pinner shims that copy contract shapes manually

Target Package Shape

Recommended landing zone inside sw-block:

1. keep pure contracts in sw-block/bridge/blockvol
2. allow a new execution-oriented package for reusable muscle logic: sw-block/bridge/blockvol/runtime

Weed-side code should shrink toward:

1. thin BlockVol binding
2. runtime hosting
3. network/wire adaptation

Concrete Batch Steps

1. extract reader logic so weed/ only fetches backend snapshot data
2. extract pinner hold bookkeeping so weed/ only performs concrete retention binding and state checks
3. extract executor-facing backend capabilities so reusable orchestration no longer depends on direct BlockVol imports
4. remove redundant reader/pinner contract-shape shims from weed/server/block_recovery.go where the new extracted layer makes them unnecessary

Execution Form

This batch is executed through the validate-able tasks in:

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

Why This Batch Is Second

This batch comes second because the first batch had to finish first:

1. backend-binding extraction is unsafe until contracts and canonical rules are stable
2. after Batch 1, the remaining coupling is mostly physical implementation coupling, not semantic drift
3. shrinking weed/server only becomes meaningful once weed/storage/... stops owning reusable muscle logic

Exit Condition

This batch is complete when:

1. reusable reader/pinner/executor logic can live in sw-block without direct weed/storage/blockvol imports
2. weed-side files are reduced to thin backend bindings and runtime hosting
3. recovery-side manual shims are either removed or reduced to trivial wiring

Delivery Note

This batch is now delivered:

1. Task E removed reader contract-shape shimming and made v2bridge.Reader return the bridge contract directly
2. Task F removed the pinner shim from weed/server/block_recovery.go
3. Task G was reviewed and confirmed already clean because v2bridge.Executor already satisfies the engine IO interfaces directly