mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-11-15 16:28:30 +01:00
pingqiuandClaude Opus 4.7
6d8d088273
Closes QA round-2 feedback loop. Three concerns resolved and one L2-blocker hazard added. ## Q1-Q3 resolution (sw-verifiable per QA concern; V2 source check) Q1 scope completeness: VERIFIED complete. V2 grep shows sync_all_* are three test files only — `sync_all_adversarial_test.go`, `sync_all_bug_test.go`, `sync_all_protocol_test.go`. Zero production files for sync_all / split_brain / takeover / arbiter. These are cross-entity invariants, not distinct types. 10-entity set stands. Q2 ReplicaReceiver scope: VERIFIED per-volume, not per-assignment. `v.replRecv = recv` at `blockvol.go:1515` is the only write site; zero `replRecv = nil` assignments in codebase. Receiver is constructed-once per BlockVol instance. L1 §2.3 wording stands. Q3 RebuildSession/Bitmap durability: VERIFIED no sidecar. Grep `rebuild_bitmap.go` + `rebuild_session.go` for `os.Open / os.Create / WriteFile / ReadFile / persist / sidecar` → empty. Recovery is WAL hydration only (`hydrateBitmapFromRecoveredWAL` at `rebuild_session.go:102`). L1 §2.10 invariant #3 CORRECTED — earlier draft incorrectly called out a "sidecar schema" that doesn't exist. ## QA concern #3 resolution: §3.14 new hazard `AllBlocks()` semantic divergence: V3 `walstore.go:565` and `smartwal/store.go:367` both call `s.Read(lba)` which reads through the dirty map (includes unflushed WAL bytes). V2 `rebuild.go:handleExtentStream` uses `readBlockFromExtent` which BYPASSES dirty map (flushed-only). Concrete impact: V3 base stream can contain bytes the primary hasn't fsynced. If primary crashes pre-fsync, replica's copy is "newer" than primary's recovered state. Epoch fencing + WAL-wins bitmap still prevent corruption, but the invariant chain is "eventually consistent via epoch churn" instead of V2's "base stream never contains unflushed bytes". Different contracts, same end state. Two L2 options proposed: (a) keep AllBlocks semantics + document non-claim in §2.7 bridge; (b) add `LogicalStorage.AllBlocksFlushed()` preserving V2 invariant. H5 architect-line decision affects which path is safer. ## QA concern #2 resolution: §3.a locked-pairs section (new) Documents pre-coupled L2 decisions driven by V3 existing shape: H6 Option C → H7b locks automatically (Provider intercepts at LogicalStorage layer; Backend.Write stays host-facing, doesn't carry LSN) §3.14 + H5 → AllBlocks safety rationale depends on which H5 shape wins Per BUG-005 documentation-discipline lesson: record coupled pairs explicitly rather than leaving them as "implied". Saves L2 cycles and gives future readers visible intent for why Backend.Write excludes LSN. ## QA concern #1 deferred to L2 Volumes map extension (single-map with role discrimination vs two separate primaryHandles + replicaHandles maps) is a legitimate L2 design concern. L1 appropriately hedges with "likely needs to grow" (§3.11 Option C); L2 picks shape. QA's BUG-005-adjacent concern (role-discriminated handle callers forgetting to check role) is the right frame for the L2 decision. No L1 edit needed; flagged for L2 attention. ## §4 open questions status Q1-Q3 ✓ resolved Q4 DistGroupCommit residence → effectively answered by §3.11 C Q5 protocol-frame wire-compat stance → still architect-line (pairs with H5) Blocking L2 start now: only H5 + Q5, both architect-line. QA to draft one-page arch memo per round-2 offer. ## Change log §5 feedback-round log gains round-3 entry §6 change log gains full round-3 detail with V2 line citations 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.