feat: add immutable road revision storage

.trellis/spec/backend/index.md

@@ -0,0 +1,5 @@
+# Backend Development Guidelines
+
+## Revision Storage
+
+- [Road Revision Storage](./road-revision-storage.md) -- immutable workbench revision layout, validation, and recovery contract.

.trellis/spec/backend/road-revision-storage.md

@@ -0,0 +1,68 @@
+# Road Revision Storage
+
+## 1. Scope / Trigger
+
+`src/compile/road-revisions.js` owns the persistent v2 workbench layout. It is called after a successful import and when an existing workbench area is read, so legacy `import-*` directories migrate lazily without an administrative command.
+
+## 2. Signatures
+
+```js
+ensureRevisionStore(workspace) // -> { paths, active, baseline }
+createCheckpoint(workspace, label) // -> restored revision
+readRevision(workspace, revisionId) // -> { manifest, osm, nativeRoadOverrides, directEdits, trafficSignals }
+```
+
+## 3. Contracts
+
+- Legacy inputs remain at `source.osm`, `native-road-overrides.json`, and `native-traffic-signals.json`; migration must never rewrite them.
+- OSM bytes are stored once under `osm/<sha256>.osm`.
+- `active/native-road-edits.json` starts as a validated v2 document at version `0`; `active/state.json` points to the active revision.
+- A revision is immutable at `revisions/rev-NNNN/`. Its `manifest.json` uses `road-workbench-revision/v1`, references the content-addressed OSM, lists frozen JSON documents, and records SHA-256 digests.
+- Area-config snapshots are intentionally owned by the subsequent snapshot step. Do not silently fall back to the external config when that step is introduced.
+
+## 4. Validation And Error Matrix
+
+| Condition | Error / behavior |
+| --- | --- |
+| Required legacy input missing | `Revision source is missing: <path>` |
+| Content-addressed OSM differs from its filename digest | `Content-addressed OSM is corrupt` |
+| Revision manifest schema or ID mismatch | `Invalid revision manifest` |
+| Revision ID is not `rev-NNNN` | Reject with `Invalid revision id` |
+| Manifest path leaves its OSM or revision directory | Reject the read; never resolve an external path |
+| Referenced frozen OSM or JSON digest mismatch | Reject the read with a digest mismatch error |
+| Empty checkpoint label | Reject with `label must be a non-empty string` |
+
+## 5. Good / Base / Bad Cases
+
+- Good: first open of a legacy directory adds `osm/`, `active/`, and `revisions/rev-0001/`, leaving old files byte-identical.
+- Base: opening an already migrated directory is idempotent; an interrupted migration with a baseline but no active state repairs only the missing state file.
+- Bad: mutating a frozen revision document or its referenced OSM must make `readRevision()` fail rather than returning altered input.
+
+## 6. Tests Required
+
+`test/road-revisions.js` must cover:
+
+- legacy-byte preservation and baseline creation;
+- equal OSM bytes yielding one content-addressed copy;
+- named checkpoint creation, parent linkage, and complete restore;
+- manifest digest equality with the actual frozen files;
+- invalid checkpoint labels.
+
+## 7. Wrong Vs Correct
+
+### Wrong
+
+```js
+fs.copyFileSync(sourceOsm, path.join(revisionDirectory, 'source.osm'));
+```
+
+This duplicates equal OSM files and provides no integrity check.
+
+### Correct
+
+```js
+const { file, digest } = storeOsm(paths);
+manifest.source = { osmFile: path.relative(paths.workspace, file), osmSha256: digest };
+```
+
+The content address is both the deduplication key and the integrity contract.