feat: add immutable road revision storage

test/road-revisions.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const assert = require('assert/strict');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { nativeRoadEdits, roadRevisions } = require('../src');
+
+const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'road-revisions-'));
+const source = '<osm version="0.6"><node id="1" lon="114.1" lat="22.5"/></osm>\n';
+const overrides = { schema: 'native-road-overrides/v1', overrides: [] };
+const signals = {
+  schema: 'native-traffic-signals/v1',
+  provenance: 'empty',
+  assemblies: { type: 'FeatureCollection', features: [] },
+};
+
+fs.writeFileSync(path.join(directory, 'source.osm'), source);
+fs.writeFileSync(path.join(directory, 'native-road-overrides.json'), `${JSON.stringify(overrides, null, 2)}\n`);
+fs.writeFileSync(path.join(directory, 'native-traffic-signals.json'), `${JSON.stringify(signals, null, 2)}\n`);
+const legacyBytes = new Map(
+  ['source.osm', 'native-road-overrides.json', 'native-traffic-signals.json'].map((file) => [
+    file,
+    fs.readFileSync(path.join(directory, file)),
+  ]),
+);
+
+const first = roadRevisions.ensureRevisionStore(directory);
+assert.equal(first.baseline.manifest.id, 'rev-0001');
+assert.equal(first.baseline.manifest.schema, roadRevisions.REVISION_SCHEMA);
+assert.equal(first.active.activeRevisionId, 'rev-0001');
+assert.equal(first.baseline.directEdits.schema, nativeRoadEdits.EDITS_SCHEMA);
+assert.equal(first.baseline.directEdits.documentVersion, 0);
+for (const [file, bytes] of legacyBytes)
+  assert.deepEqual(fs.readFileSync(path.join(directory, file)), bytes, `${file} remains byte-for-byte unchanged`);
+
+const digest = crypto.createHash('sha256').update(source).digest('hex');
+assert.equal(first.baseline.manifest.source.osmSha256, digest);
+assert.equal(fs.readdirSync(path.join(directory, 'osm')).filter((file) => file.endsWith('.osm')).length, 1);
+roadRevisions.ensureRevisionStore(directory);
+assert.equal(
+  fs.readdirSync(path.join(directory, 'osm')).filter((file) => file.endsWith('.osm')).length,
+  1,
+  'same OSM is stored once',
+);
+
+const activeEdits = nativeRoadEdits.emptyEditDocument({
+  osmSha256: digest,
+  compilerGeometryVersion: 'native-road-package/v1.1',
+});
+activeEdits.operations = [{ id: 'op-1', createdAt: '2026-08-26T12:00:00.000Z', constraintIds: [] }];
+fs.writeFileSync(path.join(directory, 'active', 'native-road-edits.json'), `${JSON.stringify(activeEdits, null, 2)}\n`);
+const checkpoint = roadRevisions.createCheckpoint(directory, 'Before junction changes');
+assert.equal(checkpoint.manifest.id, 'rev-0002');
+assert.equal(checkpoint.manifest.label, 'Before junction changes');
+assert.equal(checkpoint.manifest.parentRevisionId, 'rev-0001');
+assert.deepEqual(checkpoint.nativeRoadOverrides, overrides);
+assert.deepEqual(checkpoint.trafficSignals, signals);
+assert.deepEqual(checkpoint.directEdits, activeEdits);
+assert.equal(
+  checkpoint.manifest.digests.nativeRoadOverrides,
+  crypto
+    .createHash('sha256')
+    .update(fs.readFileSync(path.join(directory, 'revisions', 'rev-0002', 'native-road-overrides.json')))
+    .digest('hex'),
+);
+assert.deepEqual(
+  roadRevisions.readRevision(directory, 'rev-0002'),
+  checkpoint,
+  'a checkpoint can be completely restored',
+);
+assert.throws(() => roadRevisions.createCheckpoint(directory, ''), /label must be a non-empty string/);
+assert.throws(() => roadRevisions.readRevision(directory, '../rev-0002'), /Invalid revision id/);
+
+fs.rmSync(directory, { recursive: true, force: true });
+console.log('road revision storage tests passed');