mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-10-11 08:47:46 +02:00
pingqiuandClaude Opus 4.7
d2588f5b77
All 5 feedback items accepted; no subsetting. F1 — RebuildBitmap split into standalone §2.10 entity (10 total, was 9). Rationale: bitmap has independent on-disk schema (~84 LOC rebuild_bitmap.go) + independent conflict-resolution invariant (WAL-wins-over-base). Collapsing into §2.6 RebuildSession at L1 would lose granularity for L2 — bitmap and session may have different PRESERVE/REBUILD verdicts. §2.6 now explicitly cross-references §2.10. F2 — ShipperGroup §2.2 gains "External deps" row: N = RF comes from master assignment via BlockVol.SetReplicaAddrs, not from shipper-internal decision. Cross-entity contract (master assignment ↔ ShipperGroup size ↔ ReplicaReceiver expected-connection-count ↔ DistGroupCommit quorum arithmetic) made explicit so L2 split can't silently drift sync_quorum. F3 — ReplicaBarrier §2.4 scope rewritten from "per-request ephemeral" to "per-request call-closure, BUT queue-state shared per-volume via cond.Wait". Prior wording risked 1:1-porting into a V3 stateless function, losing multi-watcher cond.Broadcast semantics. H5 added to §3 observations — cross-node epoch consistency observation window for sync_quorum. V2 implicit via ack frame carrying epoch; V3 L2 must pick "ack frame carries epoch" vs "primary maintains per-replica epoch cache" before locking. Different choices → different failover + rebuild-trigger semantics. H6 added to §3 observations — write-path vs replication-path concurrency residence. Three L2 options documented: A) StorageBackend.Write triggers shipper (violates T3a layering) B) ReplicatedBackend wraps StorageBackend+shipper (clean; +1 entity) C) Replication inside DurableProvider (extends BUG-005 lesson) L1 makes no recommendation; L2 LOCKS the decision before L3. §5 restructured into 5 gated steps; step 1 is a mandatory sw V3 pre-scan of core/frontend/durable/ + core/frontend/*.go for pre-baked replication-adjacent assumptions. Rationale cited per architect: BUG-005 latent drift came from implicit V3 convention; L1 must surface any such convention before L2 verdicts lock. Concrete grep checklist included so the scan is 5 min, not open-ended. §2 header + §4 open question #1 updated for 10-entity count. Scope block references rebuild_bitmap.go explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
V2 Design
This directory currently contains both the active V2 design canon and a large set of working notes, migration packs, and historical comparison material.
Use this README as the navigation layer. If a document is not listed under
Core Canon, treat it as supporting or historical context rather than the
current source of truth.
Core Canon
These are the documents that define the current V2 model and should be read first.
v2-protocol-truths.md— the stable semantic rulesv2-sync-recovery-protocol.md— sync, keepup, catchup, and rebuild protocol meaningv2-rebuild-mvp-session-protocol.md— rebuild session contract and data/control lanesv2-automata-ownership-map.md— assignment, session, and projection ownershipv2-protocol-claim-and-evidence.md— claims and current proof posturev2-validation-matrix.md—Rebuild Ready,Restore Ready, andV2 Readygatesv2-capability-map.md— capability-to-proof-tier mappingv2-proof-and-retest-pyramid.md— proof layering and retest strategy
Implementation Guides
These help maintainers understand how the current model maps into code.
v2-engine-maintainer-tutorial.mdv2-protocol-aware-execution.mdv2-session-protocol-shape.mdv2-two-loop-protocol.mdv2-assignment-translation-unification.mdv2-reuse-replacement-boundary.md
Validation And Rollout
These define how the active design is validated, staged, or operationalized.
v2-validation-matrix.mdv2-acceptance-criteria.mdv2-product-completion-overview.mdv2-first-launch-supported-matrix.mdv2-legacy-runtime-exit-criteria.mdv2-controlled-rollout-review.mdv2-bounded-internal-pilot-pack.mdv2-pilot-preflight-checklist.mdv2-pilot-stop-conditions.md
Working Reference
These are still useful, but they are not the shortest route to the current truth.
v2-open-questions.mdv2-phase-development-plan.mdv2-execution-muscles-inventory.mdv2-scenario-sources-from-v1.mdv2_scenarios.mdv1-v15-v2-comparison.mdv2-algorithm-overview.mdv2-algorithm-overview.zh.mdv2-detailed-algorithm.zh.mdv2-semantic-methodology.zh.mdv2-protocol-closure-map.zh.md
Migration And Historical Working Set
These files are mostly valuable for reconstruction of design history, migration intent, or earlier prototype shapes. They should usually not be the first docs opened during current development.
v2-first-migration-batch.mdv2-first-migration-task-pack.mdv2-second-migration-batch.mdv2-second-migration-task-pack.mdv2-third-migration-batch.mdv2-third-migration-task-pack.mdv2-phase14plus-semantic-framework.mdv2-pure-runtime-rf1-bootstrap.mdv2-volumev2-single-node-mvp.mdv2-loop1-surface-draft.mdv2-rf2-runtime-bounded-envelope.mdv2-rf2-runtime-bounded-envelope-review.mdv2-separation-port-layer-audit.mdv2_mini_core_design.mdwal-replication-v2.mdwal-replication-v2-state-machine.mdwal-replication-v2-orchestrator.mdwal-v2-tiny-prototype.mdwal-v1-to-v2-mapping.mdv2-dist-fsm.mdv1-v15-v2-simulator-goals.mdprotocol-version-simulation.md
Process
protocol-development-process.mdagent_dev_process.md
Cleanup Rule
When a document is superseded, prefer:
- keeping one canonical file in
Core Canon - leaving older reasoning in
Migration And Historical Working Set - avoiding duplicate "read first" lists across many files
Future cleanup should physically move or archive files only after their inbound references are reviewed.
Execution Note
- active development tracking lives under
../.private/phase/ - current phase contract and slice packages live there rather than in this directory
The original project-level copies under learn/projects/sw-block/design/
remain as shared references for now.