seaweedfs/sw-block/docs/archive/design/phase-08-engine-skeleton-map.md

Phase 08 Engine Skeleton Map

Date: 2026-03-31 Status: historical phase map Purpose: provide a short structural map for the Phase 08 hardening path so implementation can move faster without reopening accepted V2 boundaries

Scope

This is not the final standalone sw-block architecture.

It is the shortest useful engine skeleton for the accepted Phase 08 hardening path:

• RF=2
• sync_all
• existing Seaweed master / volume-server heartbeat path
• V2 engine owns recovery policy
• blockvol remains the execution backend

Module Map

1. Control plane

Role:

• authoritative control truth

Primary sources:

• weed/server/master_grpc_server.go
• weed/server/master_block_registry.go
• weed/server/master_block_failover.go
• weed/server/volume_grpc_client_to_master.go

What it produces:

• confirmed assignment
• Epoch
• target Role
• failover / promotion / reassignment result
• stable server identity

2. Control bridge

Role:

• translate real control truth into V2 engine intent

Primary files:

• weed/storage/blockvol/v2bridge/control.go
• sw-block/bridge/blockvol/control_adapter.go
• entry path in weed/server/volume_server_block.go

What it produces:

• AssignmentIntent
• stable ReplicaID
• Endpoint
• SessionKind

3. Engine runtime

Role:

• recovery-policy core

Primary files:

• sw-block/engine/replication/orchestrator.go
• sw-block/engine/replication/driver.go
• sw-block/engine/replication/executor.go
• sw-block/engine/replication/sender.go
• sw-block/engine/replication/history.go

What it decides:

• zero-gap / catch-up / needs-rebuild
• sender/session ownership
• stale authority rejection
• resource acquisition / release
• rebuild source selection

4. Storage bridge

Role:

• translate real blockvol storage truth and execution capability into engine-facing adapters

Primary files:

• weed/storage/blockvol/v2bridge/reader.go
• weed/storage/blockvol/v2bridge/pinner.go
• weed/storage/blockvol/v2bridge/executor.go
• sw-block/bridge/blockvol/storage_adapter.go

What it provides:

• RetainedHistory
• WAL retention pin / release
• snapshot pin / release
• full-base pin / release
• WAL scan execution

5. Block runtime

Role:

• execute real I/O

Primary files:

• weed/storage/blockvol/blockvol.go
• weed/storage/blockvol/replica_apply.go
• weed/storage/blockvol/replica_barrier.go
• weed/storage/blockvol/recovery.go
• weed/storage/blockvol/rebuild.go
• weed/storage/blockvol/wal_shipper.go

What it owns:

• WAL
• extent
• flusher
• checkpoint / superblock
• receiver / shipper
• rebuild server

Execution Order

Control path

master heartbeat / failover truth
  -> BlockVolumeAssignment
  -> volume server ProcessAssignments
  -> v2bridge control conversion
  -> engine ProcessAssignment
  -> sender/session state updated

Catch-up path

assignment accepted
  -> engine reads retained history
  -> engine plans catch-up
  -> storage bridge pins WAL retention
  -> engine executor drives v2bridge executor
  -> blockvol scans WAL / ships entries
  -> engine completes session

Rebuild path

assignment accepted
  -> engine detects NeedsRebuild
  -> engine selects rebuild source
  -> storage bridge pins snapshot/full-base/tail
  -> executor drives transfer path
  -> blockvol performs restore / replay work
  -> engine completes rebuild

Local durability path

WriteLBA / Trim
  -> WAL append
  -> shipping / barrier
  -> client-visible durability decision
  -> flusher writes extent
  -> checkpoint advances
  -> retention floor decides WAL reclaimability

Interim Fields

These are currently acceptable only as explicit hardening carry-forwards:

localServerID

Current source:

• BlockService.listenAddr

Meaning:

• temporary local identity source for replica/rebuild-side assignment translation

Status:

• interim only
• should become registry-assigned stable server identity later

CommittedLSN = CheckpointLSN

Current source:

• v2bridge.Reader / BlockVol.StatusSnapshot()

Meaning:

• current V1-style interim mapping where committed truth collapses to local checkpoint truth

Status:

• not final V2 truth
• must become a gate decision before a production-candidate phase

heartbeat as control carrier

Current source:

• existing master <-> volume-server heartbeat path

Meaning:

• current transport for assignment/control delivery

Status:

• acceptable as current carrier
• not yet a final proof that no separate control channel will ever be needed

Hard Gates

These should remain explicit in Phase 08:

Gate 1: committed truth

Before production-candidate:

• either separate CommittedLSN from CheckpointLSN
• or explicitly bound the first candidate path to currently proven pre-checkpoint replay behavior

Gate 2: live control delivery

Required:

• real assignment delivery must reach the engine on the live path
• not only converter-level proof

Gate 3: integrated catch-up closure

Required:

• engine -> executor -> v2bridge -> blockvol must be proven as one live chain
• not planner proof plus direct WAL-scan proof as separate evidence

Gate 4: first rebuild execution path

Required:

• rebuild must not remain only a detection outcome
• the chosen product path needs one real executable rebuild closure

Gate 5: unified replay

Required:

• after control and execution closure land, rerun the accepted failure-class set on the unified live path

Reuse Map

Reuse directly

• weed/server/master_grpc_server.go
• weed/server/volume_grpc_client_to_master.go
• weed/server/volume_server_block.go
• weed/server/master_block_registry.go
• weed/server/master_block_failover.go
• weed/storage/blockvol/blockvol.go
• weed/storage/blockvol/replica_apply.go
• weed/storage/blockvol/replica_barrier.go
• weed/storage/blockvol/v2bridge/

Reuse as implementation reality, not truth

• shipperGroup
• RetentionFloorFn
• ReplicaReceiver
• checkpoint/superblock machinery
• existing failover heuristics

Do not inherit as V2 semantics

• address-shaped identity
• old degraded/catch-up intuition from V1/V1.5
• CommittedLSN = CheckpointLSN as final truth
• blockvol-side recovery policy decisions

Short Rule

Use this skeleton as:

• a hardening map for the current product path

Do not mistake it for:

• the final standalone sw-block architecture