diff --git a/openspec/changes/add-format-versioning/.openspec.yaml b/openspec/changes/archive/2026-07-15-add-format-versioning/.openspec.yaml similarity index 100% rename from openspec/changes/add-format-versioning/.openspec.yaml rename to openspec/changes/archive/2026-07-15-add-format-versioning/.openspec.yaml diff --git a/openspec/changes/add-format-versioning/design.md b/openspec/changes/archive/2026-07-15-add-format-versioning/design.md similarity index 100% rename from openspec/changes/add-format-versioning/design.md rename to openspec/changes/archive/2026-07-15-add-format-versioning/design.md diff --git a/openspec/changes/add-format-versioning/proposal.md b/openspec/changes/archive/2026-07-15-add-format-versioning/proposal.md similarity index 100% rename from openspec/changes/add-format-versioning/proposal.md rename to openspec/changes/archive/2026-07-15-add-format-versioning/proposal.md diff --git a/openspec/changes/add-format-versioning/specs/block-graph/spec.md b/openspec/changes/archive/2026-07-15-add-format-versioning/specs/block-graph/spec.md similarity index 100% rename from openspec/changes/add-format-versioning/specs/block-graph/spec.md rename to openspec/changes/archive/2026-07-15-add-format-versioning/specs/block-graph/spec.md diff --git a/openspec/changes/add-format-versioning/tasks.md b/openspec/changes/archive/2026-07-15-add-format-versioning/tasks.md similarity index 100% rename from openspec/changes/add-format-versioning/tasks.md rename to openspec/changes/archive/2026-07-15-add-format-versioning/tasks.md diff --git a/openspec/specs/block-graph/spec.md b/openspec/specs/block-graph/spec.md index a2e8bef..4e497eb 100644 --- a/openspec/specs/block-graph/spec.md +++ b/openspec/specs/block-graph/spec.md @@ -58,3 +58,53 @@ The in-memory graph and all derived indexes SHALL be updated incrementally on ev #### Scenario: Incremental equals rebuild - **WHEN** a randomized sequence of at least 1,000 edit operations (create, edit, move, delete, tag, reference) is applied - **THEN** the incrementally-maintained indexes are equal to indexes rebuilt from scratch from the Loro document + +### Requirement: Graph directory format is versioned +The graph directory SHALL carry a semantic format version, written at graph +creation and readable without decoding the Loro document. Opening a graph +whose format version exceeds the running build's supported version MUST fail +with an error identifying both versions, without reading or modifying any +other file in the directory. A graph directory without a version stamp SHALL +be treated as format version 1 and stamped on next open. + +#### Scenario: Newer format is refused untouched +- **WHEN** a build supporting format 2 opens a graph stamped format 3 +- **THEN** the open fails with an error naming both versions and every file + in the graph directory is byte-identical to its pre-open state + +#### Scenario: Legacy graph acquires a stamp +- **WHEN** a graph directory created before versioning existed is opened +- **THEN** it is treated as format 1, opens normally, and carries a format + stamp afterwards + +### Requirement: Older formats migrate through a contiguous chain +Opening a graph with an older format version SHALL migrate it through +sequential compiled migration steps (each step raising the version by exactly +one) before normal loading, re-stamping after each step so an interrupted +migration resumes at the failed step. The registry of migration steps MUST be +verified contiguous from version 1 to the current version by a test. Before +the first migration step modifies the directory, the pre-migration snapshot +MUST be preserved as a backup. + +#### Scenario: Migration chain has no gaps +- **WHEN** the current format version is N +- **THEN** a test asserts exactly N−1 registered migration steps, so a + version bump without its migration fails the build + +#### Scenario: Interrupted migration resumes safely +- **WHEN** the process dies between migration steps +- **THEN** the next open resumes migration from the recorded intermediate + version and completes normally, and the pre-migration snapshot backup + still exists + +### Requirement: Cross-release open compatibility is continuously verified +The test suite SHALL include a committed golden graph directory that every +test run opens and verifies content-identical (block text, structure, +references) against a recorded expectation. The golden directory SHALL be +regenerated only together with a deliberate format version bump. + +#### Scenario: Dependency upgrade cannot silently break decoding +- **WHEN** a change (including a Loro version bump) alters how existing graph + files are decoded +- **THEN** the golden-graph test fails, forcing either a fix or an explicit + format version bump with a migration