mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-11-10 13:58:24 +01:00
pingqiu
9b6e103dde
Architect framing 2026-04-27: enumerate ten protocol boundary rules and address engine-evolution question. Engine vs primary runtime vs master split: - Engine owns: recovery FSM, single in-flight per peer, generation/epoch fence, probe→decision, backoff/cooldown policy, stale-ack-cannot-promote-health rule, recovery reason / projection - Primary runtime/adapter owns: timer / degraded-peer loop, transport probe execution, feeding probe result into engine, executing engine-emitted commands, ReplicationVolume / ReplicaPeer connection lifecycle - Master owns: identity / topology / assignment / health observation ONLY. No runtime recovery. No epoch bumps for short up/down. Six in-scope boundary rules (#1, #2, #3, #4, #7, #8): - #1 Admitted Peer Rule — already INV-G5-5C-PRIMARY-RECOVERY-AUTHORITY-BOUNDED - #2 Generation Fence — NEW INV-G5-5C-GENERATION-FENCE - #3 Single In-Flight Per Peer — NEW INV-G5-5C-SINGLE-INFLIGHT-PER-PEER - #4 Probe Before Catch-Up — NEW INV-G5-5C-PROBE-BEFORE-CATCHUP - #7 Backoff/Cooldown — NEW INV-G5-5C-RECOVERY-BACKOFF (extends v0.4 fixed-5s into 5s→10s→20s→40s→60s cap, reset on success) - #8 Stale Ack Guard — NEW INV-G5-5C-STALE-ACK-NO-HEALTH-PROMOTION (cross-refs G5-5 round-14 gate-degraded artifact) Three forward-carries OUT of G5-5C (per §5): - #5 Durability Mode Explicit → G5-2 / G5-6 - #6 RF Health Reporting Separate From Recovery → future master observability batch - #10 Status Surface (recovery reason, effective RF, last probe) → G5-3 metrics/backpressure One citation (#9 Replica-side lineage check): already enforced by T4 acceptMutationLineage gate; G5-5C cites, no new code. §1.H code-start audit gate: sw audits per-INV current owner location BEFORE writing any code. Halt-condition: if recovery FSM is embedded in ReplicationVolume, fence is re-derived per call site, in-flight is implicit, or stale-ack guard is missing — sw stops and re-scopes as engine-evolution batch instead of layering ifs in core/replication/. Audit findings published as commit note pre-code; PR includes audit-summary. §2 acceptance criteria: add #13 (stale-ack guard), #14 (backoff progression), #15 (code-start audit). Acceptance count now 15 covering 7 INVs (6 new + reconnect orthogonality from v0.4.3). Standing by for architect single-sign of v0.4.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.