mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-10-30 17:00:48 +01:00
pingqiu
04b9d1ea53
Per repository policy: dev/design docs live in
seaweedfs/sw-block/design/, not in seaweed_block/docs/. Formal
product docs come later. This commit relocates the 7 recovery
design markdown docs (4 trunk-merged in seaweed_block phase-15;
3 in-flight on g7-redo branches) plus the 1 hardware canonical
YAML to sw-block/design/ with v3-recovery-* prefix to match the
existing naming pattern (v3-recovery-live-line-backlog-spec.md).
Companion cleanup: a follow-on PR on seaweed_block removes the
docs from docs/ (and the YAML from testrunner/scenarios/) — that
PR is the seaweed_block side of the relocation.
Files added:
v3-recovery-pin-floor-wire.md — was docs/recovery-pin-floor-wire.md
on seaweed_block phase-15 (PR #11+#16)
v3-recovery-wiring-plan.md — was docs/recovery-wiring-plan.md
(PR #13)
v3-recovery-execution-institution.md — was docs/recovery-execution-institution.md
v3-recovery-inv-test-map.md — was docs/recovery-inv-test-map.md
(PR #11/#14/#15)
v3-recovery-unified-wal-stream-kickoff.md — was docs/recovery-unified-wal-stream-kickoff.md
g7-redo/unified-wal-kickoff (v0.3)
v3-recovery-unified-wal-stream-mini-plan.md — was docs/recovery-unified-wal-stream-mini-plan.md
g7-redo/unified-wal-mini-plan (v0.2)
v3-recovery-dual-lane-canonical-runbook.md — was docs/recovery-dual-lane-canonical-runbook.md
g7-redo/hardware-canonical-paper
v3-recovery-dual-lane-canonical.yaml — was testrunner/scenarios/recovery-dual-lane-canonical.yaml
g7-redo/hardware-canonical-paper
Internal cross-references updated in-place via sed:
- docs/recovery-inv-test-map.md → v3-recovery-inv-test-map.md
- docs/recovery-pin-floor-wire.md → v3-recovery-pin-floor-wire.md
- docs/recovery-wiring-plan.md → v3-recovery-wiring-plan.md
- testrunner/scenarios/recovery-dual-lane-canonical.yaml →
v3-recovery-dual-lane-canonical.yaml
Hand-edits:
- runbook §1 companion-YAML link: was
"../v3-recovery-dual-lane-canonical.yaml" (parent dir from
seaweed_block/docs); now same-directory link in design/.
- runbook §8 §3.2 #3 reference: was relative to seaweed_block
memory file (../../.claude/...); rewritten to point to
v3-recovery-unified-wal-stream-kickoff.md §4 directly.
- mini-plan Q15: docs/archive/ wording updated to
sw-block/design/archive/.
Stages-of-evidence still readable from the docs themselves
(kickoff §11, mini-plan §10 resolution logs, inv-test-map row
versions). Original seaweed_block branches preserve git
history for the in-flight content; the cleanup PR closes them
once this lands.
NOTE: this commit does NOT include the user's unrelated
ongoing edits in feature/sw-block (M v3-batch-process.md,
M v3-dev-roadmap.md, M v3-phase-15-g6-mini-plan.md, etc.).
Those stay uncommitted for the user to handle separately.
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.