openspec/changes/add-format-versioning/.openspec.yaml openspec/changes/archive/2026-07-15-add-format-versioning/.openspec.yaml

Reviewed

openspec/changes/add-format-versioning/design.md openspec/changes/archive/2026-07-15-add-format-versioning/design.md

Reviewed

openspec/changes/add-format-versioning/proposal.md openspec/changes/archive/2026-07-15-add-format-versioning/proposal.md

Reviewed

openspec/changes/add-format-versioning/specs/block-graph/spec.md openspec/changes/archive/2026-07-15-add-format-versioning/specs/block-graph/spec.md

Reviewed

openspec/changes/add-format-versioning/tasks.md openspec/changes/archive/2026-07-15-add-format-versioning/tasks.md

Reviewed

+50

openspec/specs/block-graph/spec.md

Reviewed

··· 58 58 #### Scenario: Incremental equals rebuild 59 59 - **WHEN** a randomized sequence of at least 1,000 edit operations (create, edit, move, delete, tag, reference) is applied 60 60 - **THEN** the incrementally-maintained indexes are equal to indexes rebuilt from scratch from the Loro document 61 61 + 62 62 + ### Requirement: Graph directory format is versioned 63 63 + The graph directory SHALL carry a semantic format version, written at graph 64 64 + creation and readable without decoding the Loro document. Opening a graph 65 65 + whose format version exceeds the running build's supported version MUST fail 66 66 + with an error identifying both versions, without reading or modifying any 67 67 + other file in the directory. A graph directory without a version stamp SHALL 68 68 + be treated as format version 1 and stamped on next open. 69 69 + 70 70 + #### Scenario: Newer format is refused untouched 71 71 + - **WHEN** a build supporting format 2 opens a graph stamped format 3 72 72 + - **THEN** the open fails with an error naming both versions and every file 73 73 + in the graph directory is byte-identical to its pre-open state 74 74 + 75 75 + #### Scenario: Legacy graph acquires a stamp 76 76 + - **WHEN** a graph directory created before versioning existed is opened 77 77 + - **THEN** it is treated as format 1, opens normally, and carries a format 78 78 + stamp afterwards 79 79 + 80 80 + ### Requirement: Older formats migrate through a contiguous chain 81 81 + Opening a graph with an older format version SHALL migrate it through 82 82 + sequential compiled migration steps (each step raising the version by exactly 83 83 + one) before normal loading, re-stamping after each step so an interrupted 84 84 + migration resumes at the failed step. The registry of migration steps MUST be 85 85 + verified contiguous from version 1 to the current version by a test. Before 86 86 + the first migration step modifies the directory, the pre-migration snapshot 87 87 + MUST be preserved as a backup. 88 88 + 89 89 + #### Scenario: Migration chain has no gaps 90 90 + - **WHEN** the current format version is N 91 91 + - **THEN** a test asserts exactly N−1 registered migration steps, so a 92 92 + version bump without its migration fails the build 93 93 + 94 94 + #### Scenario: Interrupted migration resumes safely 95 95 + - **WHEN** the process dies between migration steps 96 96 + - **THEN** the next open resumes migration from the recorded intermediate 97 97 + version and completes normally, and the pre-migration snapshot backup 98 98 + still exists 99 99 + 100 100 + ### Requirement: Cross-release open compatibility is continuously verified 101 101 + The test suite SHALL include a committed golden graph directory that every 102 102 + test run opens and verifies content-identical (block text, structure, 103 103 + references) against a recorded expectation. The golden directory SHALL be 104 104 + regenerated only together with a deliberate format version bump. 105 105 + 106 106 + #### Scenario: Dependency upgrade cannot silently break decoding 107 107 + - **WHEN** a change (including a Loro version bump) alters how existing graph 108 108 + files are decoded 109 109 + - **THEN** the golden-graph test fails, forcing either a fix or an explicit 110 110 + format version bump with a migration