mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-09-30 03:35:37 +00:00
pingqiu
4f6e5d3e6a
Architect re-ruling 2026-04-27: control-plane / data-plane layering. Master must own identity / topology / address / RF-health; it must NOT own runtime recovery scheduling. v0.2/v0.3's Option A (master observation-driven re-emission) forces master into recovery-scheduling territory and forces PeerSetGeneration to carry two distinct semantics (authority version + peer-set-view version). That's the wrong shape: master gets heavier; control-plane heartbeat cadence couples to data-plane recovery cadence; protocol cleanliness erodes. Bind Option B (primary-side degraded-peer probe loop) with explicit constraints. No master protocol change. Changes: - §1.A rewritten: Option B bound shape (only-on-degraded, 5s interval, per-peer cooldown, in-flight guard, max-concurrent-probes=1, CP4B-2 lifecycle discipline). Why-A-retired + Why-C-rejected sections. - §1.B replaced: master protocol explicitly unchanged. v0.3's PeerSetRevision proto field, ObservationStore.obsRev counter, and UpdateReplicaSet lex-compare upgrade — all three retired. - §1.C replaced: truth-domain matrix shows zero master-side write; one truth domain (primary data-control) writes; all others untouched. - §1 Files retired master-side rows; replaced with primary-side probe loop infrastructure (peer.go probe entry + replication probe loop + flags + lifecycle/cooldown/dispatch tests + component test). Total ~225 prod + ~310 test, all primary-side. Zero LOC master / proto. - §2 acceptance criteria rewritten: lifecycle correctness, cooldown + in-flight TOCTOU, dispatch branches, hardware GREEN. New criterion #7: zero diff under core/host/master/, core/authority/, proto/. - §3 INVs replaced: drop INV-MASTER-PEER-SET-GEN-REV-MONOTONIC; add INV-REPL-PEER-RECOVERY-PROBE-LOOP-001, retain INV-REPL-PEER-RECOVERY-NO-RETRIGGER-LOOP, add INV-G5-5C-NO-MASTER-PROTOCOL-CHANGE (anti-creep guard). - §6 risks rewritten around probe loop concerns: lifecycle bugs (CP4B-2 lessons), cooldown tuning, in-flight TOCTOU, scope-creep prevention via §3 INV + §2 #7 diff inspection. - §5 forward-carry: trigger source disposition updated to Option B. - §7 sign table records full ruling history v0.1 → v0.2 → v0.3 → v0.4 with retire/keep markings; awaiting single-sign of v0.4. Standing by for architect single-sign of v0.4.
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.