@opengsd/gsd-pi 1.10.0-dev.a5e42e99 → 1.11.0

package/src/resources/extensions/gsd/db/engine.ts

@@ -47,7 +47,9 @@ import {
   applyMigrationV28MemoryLastHitAt,
   applyMigrationV29RepositoryTargets,
   applyMigrationV30ReworkBriefs,
+  applyMigrationV31CanonicalFoundation,
 } from "../db-migration-steps.js";
+import { createCanonicalFoundationSchemaV31 } from "../db-canonical-foundation-schema.js";
 import {
   isMemoriesFtsAvailableSchema,
   rebuildMemoriesFtsSchemaOnce,
@@ -97,7 +99,7 @@ const providerLoader = createSqliteProviderLoader({
   nodeVersion: process.versions.node,
   writeStderr: (message: string) => process.stderr.write(message),
 });
-export const SCHEMA_VERSION = 30;
+export const SCHEMA_VERSION = 31;
 function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null): void {
   const conservativeFilePragmas = fileBacked && _isLikelyWslDrvFsPathForTest(dbPath);
   if (fileBacked) db.exec(conservativeFilePragmas ? "PRAGMA journal_mode=DELETE" : "PRAGMA journal_mode=WAL");
@@ -135,6 +137,7 @@ function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null):
       } else {
         createCoordinationTablesV24(db);
         createRuntimeKvTableV25(db);
+        createCanonicalFoundationSchemaV31(db);
 
         // Fresh install — all tables are created above with the full current schema,
         // so it is safe to create all migration-specific indexes here.  For existing
@@ -388,6 +391,11 @@ function migrateSchema(db: DbAdapter, dbPath: string | null): void {
       recordSchemaVersion(db, 30);
     }
 
+    if (currentVersion < 31) {
+      applyMigrationV31CanonicalFoundation(db);
+      recordSchemaVersion(db, 31);
+    }
+
     if (_migrationFaultForTest) throw new Error("migration fault injected for test");
 
     db.exec("COMMIT");

package/src/resources/extensions/gsd/db-canonical-foundation-schema.ts

@@ -0,0 +1,129 @@
+// Project/App: gsd-pi
+// File Purpose: Additive v31 authority, operation provenance, domain event, and outbox schema.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+/**
+ * v31 mapping:
+ * - schema_version remains DDL compatibility, not the domain revision.
+ * - audit_events remains optional operational telemetry, not domain history.
+ * - milestone_commit_attributions remains Git-specific, not operation provenance.
+ * - command_queue and runtime_kv remain coordination/cache surfaces, not an outbox.
+ */
+export function createCanonicalFoundationSchemaV31(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS project_authority (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      project_id TEXT NOT NULL UNIQUE,
+      project_root_realpath TEXT NOT NULL DEFAULT '',
+      revision INTEGER NOT NULL DEFAULT 0 CHECK (revision >= 0),
+      authority_epoch INTEGER NOT NULL DEFAULT 0 CHECK (authority_epoch >= 0),
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_operations (
+      operation_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      operation_type TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      expected_revision INTEGER NOT NULL CHECK (expected_revision >= 0),
+      resulting_revision INTEGER NOT NULL CHECK (resulting_revision = expected_revision + 1),
+      expected_authority_epoch INTEGER NOT NULL CHECK (expected_authority_epoch >= 0),
+      resulting_authority_epoch INTEGER NOT NULL CHECK (
+        resulting_authority_epoch = expected_authority_epoch OR
+        resulting_authority_epoch = expected_authority_epoch + 1
+      ),
+      actor_type TEXT NOT NULL,
+      actor_id TEXT DEFAULT NULL,
+      source_transport TEXT NOT NULL,
+      trace_id TEXT DEFAULT NULL,
+      turn_id TEXT DEFAULT NULL,
+      request_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE (project_id, idempotency_key),
+      UNIQUE (project_id, resulting_revision),
+      UNIQUE (operation_id, project_id, resulting_revision, resulting_authority_epoch),
+      FOREIGN KEY (project_id) REFERENCES project_authority(project_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_domain_events (
+      event_id TEXT PRIMARY KEY,
+      operation_id TEXT NOT NULL,
+      event_index INTEGER NOT NULL DEFAULT 0 CHECK (event_index >= 0),
+      project_id TEXT NOT NULL,
+      project_revision INTEGER NOT NULL CHECK (project_revision > 0),
+      authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 0),
+      event_type TEXT NOT NULL,
+      entity_type TEXT NOT NULL,
+      entity_id TEXT NOT NULL,
+      caused_by_event_id TEXT DEFAULT NULL,
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      UNIQUE (operation_id, event_index),
+      FOREIGN KEY (operation_id, project_id, project_revision, authority_epoch)
+        REFERENCES workflow_operations(
+          operation_id, project_id, resulting_revision, resulting_authority_epoch
+        ),
+      FOREIGN KEY (caused_by_event_id) REFERENCES workflow_domain_events(event_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS trg_workflow_domain_events_immutable_update
+    BEFORE UPDATE ON workflow_domain_events
+    BEGIN
+      SELECT RAISE(ABORT, 'workflow domain events are immutable');
+    END
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS trg_workflow_domain_events_immutable_delete
+    BEFORE DELETE ON workflow_domain_events
+    BEGIN
+      SELECT RAISE(ABORT, 'workflow domain events are immutable');
+    END
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_outbox (
+      outbox_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_id TEXT NOT NULL,
+      destination TEXT NOT NULL,
+      available_at TEXT NOT NULL DEFAULT '',
+      attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+      claimed_by TEXT DEFAULT NULL,
+      claim_expires_at TEXT DEFAULT NULL,
+      delivered_at TEXT DEFAULT NULL,
+      last_error TEXT DEFAULT NULL,
+      UNIQUE (event_id, destination),
+      FOREIGN KEY (event_id) REFERENCES workflow_domain_events(event_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_operations_created
+    ON workflow_operations(project_id, created_at, operation_id)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_domain_events_entity
+    ON workflow_domain_events(project_id, entity_type, entity_id, project_revision, event_index)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_outbox_pending
+    ON workflow_outbox(delivered_at, available_at, outbox_id)
+  `);
+
+  db.exec(`
+    INSERT OR IGNORE INTO project_authority (
+      singleton, project_id, project_root_realpath,
+      revision, authority_epoch, created_at, updated_at
+    ) VALUES (
+      1, lower(hex(randomblob(16))), '',
+      0, 0, '', ''
+    )
+  `);
+}

package/src/resources/extensions/gsd/db-migration-steps.ts

@@ -2,6 +2,7 @@
 // File Purpose: Schema migration DDL steps for the GSD database facade.
 
 import type { DbAdapter } from "./db-adapter.js";
+import { createCanonicalFoundationSchemaV31 } from "./db-canonical-foundation-schema.js";
 import { ensureColumn } from "./db-schema-metadata.js";
 
 export function applyMigrationV2Artifacts(db: DbAdapter): void {
@@ -494,3 +495,7 @@ export function applyMigrationV30ReworkBriefs(db: DbAdapter): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
 }
+
+export function applyMigrationV31CanonicalFoundation(db: DbAdapter): void {
+  createCanonicalFoundationSchemaV31(db);
+}

package/src/resources/extensions/gsd/tests/db-canonical-foundation.test.ts

@@ -0,0 +1,459 @@
+// Project/App: gsd-pi
+// File Purpose: Executable contract for the additive v31 canonical database foundation.
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, test } from "node:test";
+import { pathToFileURL } from "node:url";
+
+import {
+  SCHEMA_VERSION,
+  _getAdapter,
+  _setMigrationFaultForTest,
+  closeDatabase,
+  openDatabase,
+} from "../gsd-db.ts";
+
+const require = createRequire(import.meta.url);
+const tempDirs = new Set<string>();
+
+interface RawDb {
+  exec(sql: string): void;
+  prepare(sql: string): {
+    get(...args: unknown[]): Record<string, unknown> | undefined;
+    all(...args: unknown[]): Array<Record<string, unknown>>;
+  };
+  close(): void;
+}
+
+function openRawDatabase(path: string): RawDb {
+  const sqlite = require("node:sqlite") as { DatabaseSync: new (path: string) => RawDb };
+  return new sqlite.DatabaseSync(path);
+}
+
+function createDatabasePath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-canonical-foundation-"));
+  tempDirs.add(dir);
+  return join(dir, "gsd.db");
+}
+
+function tableExists(db: RawDb, table: string): boolean {
+  return Boolean(
+    db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?").get(table),
+  );
+}
+
+function maxSchemaVersion(db: RawDb): number {
+  return Number(db.prepare("SELECT MAX(version) AS version FROM schema_version").get()?.version);
+}
+
+function rewindToV30(dbPath: string): void {
+  assert.equal(openDatabase(dbPath), true);
+  closeDatabase();
+
+  const raw = openRawDatabase(dbPath);
+  try {
+    raw.exec(`
+      DROP TABLE IF EXISTS workflow_outbox;
+      DROP TABLE IF EXISTS workflow_domain_events;
+      DROP TABLE IF EXISTS workflow_operations;
+      DROP TABLE IF EXISTS project_authority;
+      DELETE FROM schema_version;
+      INSERT INTO schema_version (version, applied_at) VALUES (30, '2026-07-12T00:00:00.000Z');
+      INSERT OR IGNORE INTO milestones (id, title, status, created_at)
+      VALUES ('M-LEGACY', 'Preserved legacy milestone', 'active', '2026-07-12T00:00:00.000Z');
+      INSERT OR IGNORE INTO audit_events
+        (event_id, trace_id, category, type, ts, payload_json)
+      VALUES
+        ('audit-legacy', 'trace-legacy', 'workflow', 'legacy', '2026-07-12T00:00:00.000Z', '{"kept":true}');
+    `);
+  } finally {
+    raw.close();
+  }
+}
+
+function inspectFromFreshProcess(dbPath: string): Record<string, unknown> {
+  const moduleHref = pathToFileURL(
+    join(process.cwd(), "src/resources/extensions/gsd/gsd-db.ts"),
+  ).href;
+  const script = [
+    `import { openDatabase, closeDatabase, _getAdapter } from ${JSON.stringify(moduleHref)};`,
+    "const path = process.argv[1];",
+    "if (!openDatabase(path)) throw new Error('database open failed');",
+    "const db = _getAdapter();",
+    "const version = db.prepare('SELECT MAX(version) AS value FROM schema_version').get().value;",
+    "const authority = db.prepare('SELECT project_id, revision, authority_epoch FROM project_authority').get();",
+    "const legacy = db.prepare(\"SELECT title FROM milestones WHERE id = 'M-LEGACY'\").get();",
+    "console.log(JSON.stringify({ version, authority, legacy }));",
+    "closeDatabase();",
+  ].join("\n");
+  const env = { ...process.env };
+  delete env.NODE_TEST_CONTEXT;
+  const child = spawnSync(
+    process.execPath,
+    [
+      "--import",
+      "./src/resources/extensions/gsd/tests/resolve-ts.mjs",
+      "--experimental-strip-types",
+      "--input-type=module",
+      "-e",
+      script,
+      dbPath,
+    ],
+    { cwd: process.cwd(), encoding: "utf8", env, timeout: 30_000 },
+  );
+  assert.equal(child.status, 0, child.stderr || child.stdout);
+  return JSON.parse(child.stdout) as Record<string, unknown>;
+}
+
+afterEach(() => {
+  _setMigrationFaultForTest(false);
+  closeDatabase();
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });
+  tempDirs.clear();
+});
+
+test("fresh database creates the v31 authority root and linked operation journal", () => {
+  assert.equal(SCHEMA_VERSION, 31);
+  const dbPath = createDatabasePath();
+  assert.equal(openDatabase(dbPath), true);
+  const db = _getAdapter();
+  assert.ok(db);
+
+  const authority = db.prepare(`
+    SELECT singleton, project_id, project_root_realpath, revision, authority_epoch
+    FROM project_authority
+  `).get();
+  assert.deepEqual(
+    {
+      singleton: authority?.singleton,
+      projectIdLength: String(authority?.project_id ?? "").length,
+      root: authority?.project_root_realpath,
+      revision: authority?.revision,
+      epoch: authority?.authority_epoch,
+    },
+    { singleton: 1, projectIdLength: 32, root: "", revision: 0, epoch: 0 },
+  );
+
+  assert.throws(
+    () => db.exec("INSERT INTO project_authority (singleton, project_id) VALUES (2, 'second')"),
+    /CHECK constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec("UPDATE project_authority SET revision = -1 WHERE singleton = 1"),
+    /CHECK constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec("UPDATE project_authority SET authority_epoch = -1 WHERE singleton = 1"),
+    /CHECK constraint failed/i,
+  );
+
+  db.exec(`
+    INSERT INTO workflow_operations (
+      operation_id, project_id, operation_type, idempotency_key,
+      expected_revision, resulting_revision,
+      expected_authority_epoch, resulting_authority_epoch,
+      actor_type, actor_id, source_transport, request_hash, created_at
+    )
+    SELECT
+      'op-1', project_id, 'test.operation', 'idem-1',
+      0, 1, 0, 0, 'agent', 'test-agent', 'test', 'request-1', '2026-07-12T00:00:01.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_domain_events (
+      event_id, operation_id, event_index, project_id, project_revision,
+      authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+    )
+    SELECT
+      'event-1', 'op-1', 0, project_id, 1,
+      0, 'test.started', 'project', project_id, '{"step":1}', '2026-07-12T00:00:02.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_domain_events (
+      event_id, operation_id, event_index, project_id, project_revision,
+      authority_epoch, event_type, entity_type, entity_id, caused_by_event_id,
+      payload_json, created_at
+    )
+    SELECT
+      'event-2', 'op-1', 1, project_id, 1,
+      0, 'test.finished', 'project', project_id, 'event-1',
+      '{"step":2}', '2026-07-12T00:00:03.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_outbox (event_id, destination, available_at)
+    VALUES ('event-2', 'projection', '2026-07-12T00:00:04.000Z');
+  `);
+
+  const chain = db.prepare(`
+    SELECT
+      p.revision AS authority_revision,
+      o.expected_revision,
+      o.resulting_revision,
+      COUNT(DISTINCT e.event_id) AS event_count,
+      COUNT(DISTINCT x.outbox_id) AS outbox_count
+    FROM project_authority p
+    JOIN workflow_operations o ON o.project_id = p.project_id
+    JOIN workflow_domain_events e ON e.operation_id = o.operation_id
+    LEFT JOIN workflow_outbox x ON x.event_id = e.event_id
+    GROUP BY p.revision, o.expected_revision, o.resulting_revision
+  `).get();
+  assert.deepEqual(chain, {
+    authority_revision: 0,
+    expected_revision: 0,
+    resulting_revision: 1,
+    event_count: 2,
+    outbox_count: 1,
+  });
+
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_operations (
+        operation_id, project_id, operation_type, idempotency_key,
+        expected_revision, resulting_revision,
+        expected_authority_epoch, resulting_authority_epoch,
+        actor_type, source_transport, request_hash, created_at
+      )
+      SELECT 'op-duplicate', project_id, 'test.operation', 'idem-1', 1, 2, 0, 0,
+             'agent', 'test', 'request-2', '2026-07-12T00:00:05.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /UNIQUE constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_operations (
+        operation_id, project_id, operation_type, idempotency_key,
+        expected_revision, resulting_revision,
+        expected_authority_epoch, resulting_authority_epoch,
+        actor_type, source_transport, request_hash, created_at
+      )
+      SELECT 'op-same-revision', project_id, 'test.operation', 'idem-2', 0, 1, 0, 0,
+             'agent', 'test', 'request-2', '2026-07-12T00:00:05.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /UNIQUE constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_domain_events (
+        event_id, operation_id, event_index, project_id, project_revision,
+        authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+      )
+      SELECT 'event-duplicate-index', 'op-1', 1, project_id, 1, 0,
+             'test.duplicate', 'project', project_id, '{}', '2026-07-12T00:00:06.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /UNIQUE constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_domain_events (
+        event_id, operation_id, event_index, project_id, project_revision,
+        authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+      )
+      SELECT 'event-wrong-revision', 'op-1', 2, project_id, 2, 0,
+             'test.wrong-revision', 'project', project_id, '{}', '2026-07-12T00:00:06.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /FOREIGN KEY constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_outbox (event_id, destination, available_at)
+      VALUES ('missing-event', 'projection', '2026-07-12T00:00:07.000Z')
+    `),
+    /FOREIGN KEY constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_outbox (event_id, destination, available_at)
+      VALUES ('event-2', 'projection', '2026-07-12T00:00:08.000Z')
+    `),
+    /UNIQUE constraint failed/i,
+  );
+});
+
+test("operations record the resulting authority epoch used by their events", () => {
+  const dbPath = createDatabasePath();
+  assert.equal(openDatabase(dbPath), true);
+  const db = _getAdapter();
+  assert.ok(db);
+
+  db.exec(`
+    INSERT INTO workflow_operations (
+      operation_id, project_id, operation_type, idempotency_key,
+      expected_revision, resulting_revision,
+      expected_authority_epoch, resulting_authority_epoch,
+      actor_type, source_transport, request_hash, created_at
+    )
+    SELECT 'op-cutover', project_id, 'authority.cutover', 'idem-cutover',
+           0, 1, 0, 1, 'agent', 'test', 'request-cutover', '2026-07-12T00:00:01.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_domain_events (
+      event_id, operation_id, event_index, project_id, project_revision,
+      authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+    )
+    SELECT 'event-cutover', 'op-cutover', 0, project_id, 1, 1,
+           'authority.cutover', 'project', project_id, '{}', '2026-07-12T00:00:02.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_operations (
+      operation_id, project_id, operation_type, idempotency_key,
+      expected_revision, resulting_revision,
+      expected_authority_epoch, resulting_authority_epoch,
+      actor_type, source_transport, request_hash, created_at
+    )
+    SELECT 'op-unchanged-epoch', project_id, 'test.operation', 'idem-unchanged-epoch',
+           1, 2, 1, 1, 'agent', 'test', 'request-unchanged', '2026-07-12T00:00:03.000Z'
+    FROM project_authority WHERE singleton = 1;
+  `);
+
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_domain_events (
+        event_id, operation_id, event_index, project_id, project_revision,
+        authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+      )
+      SELECT 'event-stale-epoch', 'op-cutover', 1, project_id, 1, 0,
+             'authority.stale', 'project', project_id, '{}', '2026-07-12T00:00:04.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /FOREIGN KEY constraint failed/i,
+  );
+  assert.throws(
+    () => db.exec(`
+      INSERT INTO workflow_operations (
+        operation_id, project_id, operation_type, idempotency_key,
+        expected_revision, resulting_revision,
+        expected_authority_epoch, resulting_authority_epoch,
+        actor_type, source_transport, request_hash, created_at
+      )
+      SELECT 'op-epoch-jump', project_id, 'authority.cutover', 'idem-epoch-jump',
+             2, 3, 1, 3, 'agent', 'test', 'request-jump', '2026-07-12T00:00:05.000Z'
+      FROM project_authority WHERE singleton = 1
+    `),
+    /CHECK constraint failed/i,
+  );
+});
+
+test("domain events reject updates and deletes", () => {
+  const dbPath = createDatabasePath();
+  assert.equal(openDatabase(dbPath), true);
+  const db = _getAdapter();
+  assert.ok(db);
+
+  db.exec(`
+    INSERT INTO workflow_operations (
+      operation_id, project_id, operation_type, idempotency_key,
+      expected_revision, resulting_revision,
+      expected_authority_epoch, resulting_authority_epoch,
+      actor_type, source_transport, request_hash, created_at
+    )
+    SELECT 'op-immutable', project_id, 'test.operation', 'idem-immutable',
+           0, 1, 0, 0, 'agent', 'test', 'request-immutable', '2026-07-12T00:00:01.000Z'
+    FROM project_authority WHERE singleton = 1;
+
+    INSERT INTO workflow_domain_events (
+      event_id, operation_id, event_index, project_id, project_revision,
+      authority_epoch, event_type, entity_type, entity_id, payload_json, created_at
+    )
+    SELECT 'event-immutable', 'op-immutable', 0, project_id, 1, 0,
+           'test.recorded', 'project', project_id, '{"original":true}', '2026-07-12T00:00:02.000Z'
+    FROM project_authority WHERE singleton = 1;
+  `);
+
+  assert.throws(
+    () => db.exec(`UPDATE workflow_domain_events SET payload_json = '{}' WHERE event_id = 'event-immutable'`),
+    /workflow domain events are immutable/i,
+  );
+  assert.throws(
+    () => db.exec(`DELETE FROM workflow_domain_events WHERE event_id = 'event-immutable'`),
+    /workflow domain events are immutable/i,
+  );
+});
+
+test("v30 upgrade preserves legacy rows and creates an independently healthy backup", () => {
+  const dbPath = createDatabasePath();
+  rewindToV30(dbPath);
+
+  assert.equal(openDatabase(dbPath), true);
+  closeDatabase();
+
+  let projectId = "";
+  const upgraded = openRawDatabase(dbPath);
+  try {
+    assert.equal(maxSchemaVersion(upgraded), 31);
+    assert.equal(tableExists(upgraded, "project_authority"), true);
+    assert.equal(upgraded.prepare("SELECT title FROM milestones WHERE id = 'M-LEGACY'").get()?.title, "Preserved legacy milestone");
+    assert.equal(upgraded.prepare("SELECT payload_json FROM audit_events WHERE event_id = 'audit-legacy'").get()?.payload_json, '{"kept":true}');
+    assert.equal(upgraded.prepare("PRAGMA quick_check").get()?.quick_check, "ok");
+    projectId = String(upgraded.prepare("SELECT project_id FROM project_authority").get()?.project_id);
+  } finally {
+    upgraded.close();
+  }
+
+  const backup = openRawDatabase(`${dbPath}.backup-v30`);
+  try {
+    assert.equal(maxSchemaVersion(backup), 30);
+    assert.equal(tableExists(backup, "project_authority"), false);
+    assert.equal(backup.prepare("SELECT title FROM milestones WHERE id = 'M-LEGACY'").get()?.title, "Preserved legacy milestone");
+    assert.equal(backup.prepare("PRAGMA quick_check").get()?.quick_check, "ok");
+  } finally {
+    backup.close();
+  }
+
+  const reopened = inspectFromFreshProcess(dbPath);
+  assert.deepEqual(reopened, {
+    version: 31,
+    authority: { project_id: projectId, revision: 0, authority_epoch: 0 },
+    legacy: { title: "Preserved legacy milestone" },
+  });
+
+  const restoredPath = join(dirname(dbPath), "restored.db");
+  copyFileSync(`${dbPath}.backup-v30`, restoredPath);
+  const restored = inspectFromFreshProcess(restoredPath);
+  assert.equal(restored.version, 31);
+  assert.deepEqual(restored.legacy, { title: "Preserved legacy milestone" });
+  assert.deepEqual(
+    Object.fromEntries(
+      Object.entries(restored.authority as Record<string, unknown>).filter(([key]) => key !== "project_id"),
+    ),
+    { revision: 0, authority_epoch: 0 },
+  );
+});
+
+test("faulted v30 migration leaves no v31 state and retries cleanly", () => {
+  const dbPath = createDatabasePath();
+  rewindToV30(dbPath);
+
+  _setMigrationFaultForTest(true);
+  assert.throws(() => openDatabase(dbPath), /migration fault injected/);
+  _setMigrationFaultForTest(false);
+
+  const rolledBack = openRawDatabase(dbPath);
+  try {
+    assert.equal(maxSchemaVersion(rolledBack), 30);
+    assert.equal(tableExists(rolledBack, "project_authority"), false);
+    assert.equal(tableExists(rolledBack, "workflow_operations"), false);
+    assert.equal(tableExists(rolledBack, "workflow_domain_events"), false);
+    assert.equal(tableExists(rolledBack, "workflow_outbox"), false);
+  } finally {
+    rolledBack.close();
+  }
+
+  assert.equal(openDatabase(dbPath), true);
+  closeDatabase();
+  const retried = openRawDatabase(dbPath);
+  try {
+    assert.equal(maxSchemaVersion(retried), 31);
+    assert.equal(retried.prepare("SELECT COUNT(*) AS count FROM project_authority").get()?.count, 1);
+    assert.equal(retried.prepare("SELECT COUNT(*) AS count FROM milestones WHERE id = 'M-LEGACY'").get()?.count, 1);
+  } finally {
+    retried.close();
+  }
+});

package/src/resources/extensions/gsd/tests/db-engine-migrate-guards.test.ts

@@ -101,9 +101,9 @@ describe('db-engine migrate guards', () => {
       assert.ok(openDatabase(dbPath), 'fresh open should succeed');
       closeDatabase();
 
-      // Rewind the DB to v(SCHEMA_VERSION-1): stamp the prior version and drop
-      // the objects the last migration adds, so the re-run has real work to redo.
-      const startVersion = SCHEMA_VERSION - 2;
+      // Rewind to v28 and remove a v29 column so the multi-step migration has
+      // real work to redo even as later schema versions are added.
+      const startVersion = 28;
       const raw = openRawSqliteForTest(dbPath);
       raw.exec('DELETE FROM schema_version');
       raw.exec(`INSERT INTO schema_version (version, applied_at) VALUES (${startVersion}, '2026-01-01T00:00:00Z')`);

package/src/resources/extensions/gsd/tests/single-writer-invariant.test.ts

@@ -51,6 +51,7 @@ const TYPED_DB_WRITER_FILES = new Set([
 ]);
 
 const SCHEMA_DB_WRITER_FILES = new Set([
+  "db-canonical-foundation-schema.ts",
   "db-memory-fts-schema.ts",
   "db-schema-metadata.ts",
   "db-verification-evidence-schema.ts",

package/dist/web/standalone/.next/static/chunks/app/_not-found/page-a6fb1847f67f167c.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[9492],{14040:(e,t,l)=>{(window.__NEXT_P=window.__NEXT_P||[]).push(["/_not-found/page",function(){return l(32910)}])},29999:(e,t)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"styles",{enumerable:!0,get:function(){return l}});let l={error:{fontFamily:'system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',height:"100vh",textAlign:"center",display:"flex",flexDirection:"column",alignItems:"center",justifyContent:"center"},desc:{display:"inline-block"},h1:{display:"inline-block",margin:"0 20px 0 0",padding:"0 23px 0 0",fontSize:24,fontWeight:500,verticalAlign:"top",lineHeight:"49px"},h2:{fontSize:14,fontWeight:400,lineHeight:"49px",margin:0}};("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)},32910:(e,t,l)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"default",{enumerable:!0,get:function(){return o}});let r=l(18870),n=l(48664),o=function(){return(0,r.jsx)("html",{children:(0,r.jsx)("body",{children:(0,r.jsx)(n.HTTPAccessErrorFallback,{status:404,message:"This page could not be found."})})})};("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)},48664:(e,t,l)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"HTTPAccessErrorFallback",{enumerable:!0,get:function(){return o}});let r=l(18870),n=l(29999);function o({status:e,message:t}){return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("title",{children:`${e}: ${t}`}),(0,r.jsx)("div",{style:n.styles.error,children:(0,r.jsxs)("div",{children:[(0,r.jsx)("style",{dangerouslySetInnerHTML:{__html:"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}),(0,r.jsx)("h1",{className:"next-error-h1",style:n.styles.h1,children:e}),(0,r.jsx)("div",{style:n.styles.desc,children:(0,r.jsx)("h2",{style:n.styles.h2,children:t})})]})})]})}("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)}},e=>{e.O(0,[9990,686,7358],()=>e(e.s=14040)),_N_E=e.O()}]);