@ontrails/core 1.0.0-beta.14 → 1.0.0-beta.15

package/src/__tests__/topo-store.test.ts

@@ -5,15 +5,19 @@ import { join } from 'node:path';
 
 import { z } from 'zod';
 
-import { Result, provision, signal, topo, trail } from '../index.js';
+import { NotFoundError } from '../errors.js';
+import { contour, Result, resource, signal, topo, trail } from '../index.js';
+import { __topoStoreMigrationStats, createTopoStore } from '../topo-store.js';
 import {
-  ensureTopoHistorySchema,
-  pinTopoSave,
-  pruneUnpinnedTopoSaves,
-} from '../internal/topo-saves.js';
+  ensureTopoSnapshotSchema,
+  pinTopoSnapshot,
+  pruneUnpinnedSnapshots,
+} from '../internal/topo-snapshots.js';
 import {
+  createTopoSnapshot,
   getStoredTopoExport,
-  persistEstablishedTopoSave,
+  normalizeFiresRows,
+  normalizeOnRows,
 } from '../internal/topo-store.js';
 import { openWriteTrailsDb } from '../internal/trails-db.js';
 
@@ -30,10 +34,10 @@ const unwrap = <T>(result: Result<T, Error>): T => {
 const countRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
   tableName: string,
-  saveId?: string
+  snapshotId?: string
 ): number => {
   const row =
-    saveId === undefined
+    snapshotId === undefined
       ? db
           .query<{ count: number }, []>(
             `SELECT COUNT(*) as count FROM ${tableName}`
@@ -41,9 +45,9 @@ const countRows = (
           .get()
       : db
           .query<{ count: number }, [string]>(
-            `SELECT COUNT(*) as count FROM ${tableName} WHERE save_id = ?`
+            `SELECT COUNT(*) as count FROM ${tableName} WHERE snapshot_id = ?`
           )
-          .get(saveId);
+          .get(snapshotId);
   return row?.count ?? 0;
 };
 
@@ -60,14 +64,23 @@ const tableExists = (
 };
 
 const exampleApp = () => {
-  const dbMain = provision('db.main', {
+  const entityContour = contour(
+    'entity',
+    {
+      id: z.string(),
+      name: z.string(),
+    },
+    { identity: 'id' }
+  );
+
+  const dbMain = resource('db.main', {
     create: () => Result.ok({ source: 'factory' }),
     description: 'Primary database',
     health: () => Result.ok({ ok: true }),
     mock: () => ({ source: 'mock' }),
   });
 
-  const searchIndex = provision('search.index', {
+  const searchIndex = resource('search.index', {
     create: () => Result.ok({ source: 'factory' }),
     mock: () => ({ source: 'mock' }),
   });
@@ -81,6 +94,7 @@ const exampleApp = () => {
   const entityAdd = trail('entity.add', {
     blaze: (input: { readonly name: string }) =>
       Result.ok({ id: input.name.toLowerCase(), ok: true }),
+    contours: [entityContour],
     description: 'Add a new entity',
     examples: [
       {
@@ -97,24 +111,26 @@ const exampleApp = () => {
     input: z.object({ name: z.string() }),
     meta: { owner: 'core', tags: ['write', 'entity'] },
     output: z.object({ id: z.string(), ok: z.boolean() }),
-    provisions: [dbMain, searchIndex],
+    resources: [dbMain, searchIndex],
   });
 
   const entityList = trail('entity.list', {
     blaze: () => Result.ok({ items: ['ada'] }),
+    contours: [entityContour],
     crosses: ['entity.add'],
     description: 'List entities',
     idempotent: true,
     input: z.object({}),
     intent: 'read',
     output: z.object({ items: z.array(z.string()) }),
-    provisions: [dbMain],
+    resources: [dbMain],
   });
 
   return topo('projection-app', {
     dbMain,
     entityAdd,
     entityAdded,
+    entityContour,
     entityList,
     searchIndex,
   });
@@ -122,7 +138,7 @@ const exampleApp = () => {
 
 const readTrailRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) =>
   db
     .query<
@@ -139,39 +155,39 @@ const readTrailRows = (
     >(
       `SELECT id, intent, idempotent, has_output, example_count, description, meta
        FROM topo_trails
-       WHERE save_id = ?
+       WHERE snapshot_id = ?
        ORDER BY id ASC`
     )
-    .all(saveId);
+    .all(snapshotId);
 
 const readTrailSignalRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) =>
   db
     .query<{ signal_id: string; trail_id: string }, [string]>(
       `SELECT trail_id, signal_id
        FROM topo_trail_signals
-       WHERE save_id = ?`
+       WHERE snapshot_id = ?`
     )
-    .all(saveId);
+    .all(snapshotId);
 
-const readTrailheadRows = (
+const readSurfaceRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) =>
   db
     .query<{ derived_name: string; trail_id: string }, [string]>(
       `SELECT trail_id, derived_name
-       FROM topo_trailheads
-       WHERE save_id = ?
+       FROM topo_surfaces
+       WHERE snapshot_id = ?
        ORDER BY trail_id ASC`
     )
-    .all(saveId);
+    .all(snapshotId);
 
 const readExampleRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) =>
   db
     .query<
@@ -186,54 +202,62 @@ const readExampleRows = (
     >(
       `SELECT ordinal, name, input, expected, error
        FROM topo_examples
-       WHERE save_id = ?
+       WHERE snapshot_id = ?
        ORDER BY ordinal ASC`
     )
-    .all(saveId);
+    .all(snapshotId);
 
 const readProjectedTrailIds = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) =>
   db
     .query<{ id: string }, [string]>(
-      'SELECT id FROM topo_trails WHERE save_id = ? ORDER BY id ASC'
+      'SELECT id FROM topo_trails WHERE snapshot_id = ? ORDER BY id ASC'
     )
-    .all(saveId)
+    .all(snapshotId)
     .map((row) => row.id);
 
 const requireStoredExport = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ) => {
-  const stored = getStoredTopoExport(db, saveId);
+  const stored = getStoredTopoExport(db, snapshotId);
   if (stored === undefined) {
-    throw new Error(`Expected stored topo export for save "${saveId}"`);
+    throw new Error(`Expected stored topo export for snapshot "${snapshotId}"`);
   }
   return stored;
 };
 
+const hasContourTrailheadEntry = (entry: unknown, id: string): boolean => {
+  if (typeof entry !== 'object' || entry === null) {
+    return false;
+  }
+  const candidate = entry as { id?: string; kind?: string };
+  return candidate.id === id && candidate.kind === 'contour';
+};
+
 const expectProjectionCounts = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ): void => {
-  expect(countRows(db, 'topo_trails', saveId)).toBe(2);
-  expect(countRows(db, 'topo_crossings', saveId)).toBe(1);
-  expect(countRows(db, 'topo_trail_provisions', saveId)).toBe(3);
-  expect(countRows(db, 'topo_provisions', saveId)).toBe(2);
-  expect(countRows(db, 'topo_signals', saveId)).toBe(1);
-  expect(countRows(db, 'topo_trail_signals', saveId)).toBe(1);
-  expect(countRows(db, 'topo_trailheads', saveId)).toBe(2);
-  expect(countRows(db, 'topo_examples', saveId)).toBe(2);
-  expect(countRows(db, 'topo_schemas', saveId)).toBe(5);
+  expect(countRows(db, 'topo_trails', snapshotId)).toBe(2);
+  expect(countRows(db, 'topo_crossings', snapshotId)).toBe(1);
+  expect(countRows(db, 'topo_trail_resources', snapshotId)).toBe(3);
+  expect(countRows(db, 'topo_resources', snapshotId)).toBe(2);
+  expect(countRows(db, 'topo_signals', snapshotId)).toBe(1);
+  expect(countRows(db, 'topo_trail_signals', snapshotId)).toBe(1);
+  expect(countRows(db, 'topo_surfaces', snapshotId)).toBe(2);
+  expect(countRows(db, 'topo_examples', snapshotId)).toBe(2);
+  expect(countRows(db, 'topo_schemas', snapshotId)).toBe(5);
   expect(countRows(db, 'topo_exports')).toBeGreaterThanOrEqual(1);
 };
 
 const expectProjectedFixtureRows = (
   db: ReturnType<typeof openWriteTrailsDb>,
-  saveId: string
+  snapshotId: string
 ): void => {
-  expect(readTrailRows(db, saveId)).toEqual([
+  expect(readTrailRows(db, snapshotId)).toEqual([
     {
       description: 'Add a new entity',
       example_count: 2,
@@ -256,14 +280,14 @@ const expectProjectedFixtureRows = (
       meta: null,
     },
   ]);
-  expect(readTrailSignalRows(db, saveId)).toEqual([
+  expect(readTrailSignalRows(db, snapshotId)).toEqual([
     { signal_id: 'entity.added', trail_id: 'entity.add' },
   ]);
-  expect(readTrailheadRows(db, saveId)).toEqual([
+  expect(readSurfaceRows(db, snapshotId)).toEqual([
     { derived_name: 'entity add', trail_id: 'entity.add' },
     { derived_name: 'entity list', trail_id: 'entity.list' },
   ]);
-  expect(readExampleRows(db, saveId)).toEqual([
+  expect(readExampleRows(db, snapshotId)).toEqual([
     {
       error: null,
       expected: JSON.stringify({ id: 'ada', ok: true }),
@@ -300,6 +324,99 @@ const simpleProjectionApp = (withList: boolean) =>
       : {}),
   });
 
+const expectDisposableSaveCascaded = (
+  db: ReturnType<typeof openWriteTrailsDb>,
+  disposableId: string
+): void => {
+  expect(countRows(db, 'topo_trails', disposableId)).toBe(0);
+  expect(countRows(db, 'topo_crossings', disposableId)).toBe(0);
+  expect(countRows(db, 'topo_examples', disposableId)).toBe(0);
+  expect(countRows(db, 'topo_schemas', disposableId)).toBe(0);
+  expect(countRows(db, 'topo_trail_fires', disposableId)).toBe(0);
+  expect(countRows(db, 'topo_trail_on', disposableId)).toBe(0);
+};
+
+const expectSignalEdgeCounts = (
+  db: ReturnType<typeof openWriteTrailsDb>,
+  snapshotId: string,
+  count: number
+): void => {
+  expect(countRows(db, 'topo_trail_fires', snapshotId)).toBe(count);
+  expect(countRows(db, 'topo_trail_on', snapshotId)).toBe(count);
+};
+
+const buildSignalPruneApp = () => {
+  const created = signal('entity.created', {
+    from: ['entity.create'],
+    payload: z.object({ id: z.string() }),
+  });
+  const createTrail = trail('entity.create', {
+    blaze: () => Result.ok({ id: 'x' }),
+    fires: ['entity.created'],
+    input: z.object({}),
+    output: z.object({ id: z.string() }),
+  });
+  const indexTrail = trail('entity.index', {
+    blaze: () => Result.ok({ ok: true }),
+    input: z.object({}),
+    on: ['entity.created'],
+    output: z.object({ ok: z.boolean() }),
+  });
+  return topo('prune-signal-app', {
+    createTrail,
+    created,
+    indexTrail,
+  });
+};
+
+const captureReadError = (run: () => unknown): unknown => {
+  try {
+    run();
+    return undefined;
+  } catch (error) {
+    return error;
+  }
+};
+
+const withWriteDb = (
+  rootDir: string,
+  run: (db: ReturnType<typeof openWriteTrailsDb>) => void
+): void => {
+  const db = openWriteTrailsDb({ rootDir });
+  try {
+    run(db);
+  } finally {
+    db.close();
+  }
+};
+
+const seedCurrentSchemaStore = (rootDir: string): void => {
+  const db = openWriteTrailsDb({ rootDir });
+  try {
+    ensureTopoSnapshotSchema(db);
+  } finally {
+    db.close();
+  }
+};
+
+const assertNoWriteEscalationOnReads = (rootDir: string): void => {
+  const baselineEscalations = __topoStoreMigrationStats.writeEscalations;
+  const baselinePeeks = __topoStoreMigrationStats.peekCalls;
+
+  // First read: peek must happen, no write-mode escalation.
+  const caught = captureReadError(() =>
+    createTopoStore({ rootDir }).snapshots.latest()
+  );
+  expect(caught).toBeInstanceOf(NotFoundError);
+  expect(__topoStoreMigrationStats.peekCalls).toBe(baselinePeeks + 1);
+  expect(__topoStoreMigrationStats.writeEscalations).toBe(baselineEscalations);
+
+  // Second read is served entirely from the memoized identity.
+  captureReadError(() => createTopoStore({ rootDir }).snapshots.latest());
+  expect(__topoStoreMigrationStats.peekCalls).toBe(baselinePeeks + 1);
+  expect(__topoStoreMigrationStats.writeEscalations).toBe(baselineEscalations);
+};
+
 const seedHistoryOnlyTopoSchema = (
   db: ReturnType<typeof openWriteTrailsDb>
 ): void => {
@@ -314,7 +431,7 @@ const seedHistoryOnlyTopoSchema = (
     git_dirty INTEGER NOT NULL DEFAULT 0,
     trail_count INTEGER NOT NULL DEFAULT 0,
     signal_count INTEGER NOT NULL DEFAULT 0,
-    provision_count INTEGER NOT NULL DEFAULT 0,
+    resource_count INTEGER NOT NULL DEFAULT 0,
     created_at TEXT NOT NULL
   )`);
   db.run(`CREATE TABLE IF NOT EXISTS topo_pins (
@@ -324,7 +441,7 @@ const seedHistoryOnlyTopoSchema = (
   )`);
   db.run(
     `INSERT INTO topo_saves (
-      id, git_sha, git_dirty, trail_count, signal_count, provision_count, created_at
+      id, git_sha, git_dirty, trail_count, signal_count, resource_count, created_at
     ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
     ['seed-save', 'seed123', 0, 1, 0, 0, '2026-04-03T11:00:00.000Z']
   );
@@ -335,6 +452,52 @@ const seedHistoryOnlyTopoSchema = (
   ]);
 };
 
+/**
+ * Seed a pre-v7 projection store that still uses the `topo_trailheads`
+ * table and the `save_id` foreign-key column. The fresh migration should
+ * ignore this legacy state and create the snapshot-first schema alongside it.
+ */
+const seedLegacyProjectionStore = (
+  db: ReturnType<typeof openWriteTrailsDb>
+): void => {
+  db.run(
+    `INSERT INTO meta_schema_versions (subsystem, version, updated_at)
+     VALUES ('topo', 6, ?)`,
+    ['2026-04-03T11:00:00.000Z']
+  );
+  db.run(`CREATE TABLE IF NOT EXISTS topo_trailheads (
+    trail_id TEXT NOT NULL,
+    trailhead TEXT NOT NULL,
+    derived_name TEXT NOT NULL,
+    method TEXT,
+    save_id TEXT NOT NULL,
+    PRIMARY KEY (trail_id, trailhead, save_id)
+  )`);
+  db.run(
+    `INSERT INTO topo_trailheads (trail_id, trailhead, derived_name, save_id)
+     VALUES (?, ?, ?, ?)`,
+    ['entity.add', 'cli', 'entity add', 'legacy-save']
+  );
+};
+
+const replaceStoreWithHistoryOnlyStore = async (
+  rootDir: string
+): Promise<void> => {
+  // Ensure mtime/size differs so the cached identity is invalidated even on
+  // filesystems with coarse mtime granularity.
+  const dbPath = join(rootDir, '.trails', 'trails.db');
+  rmSync(dbPath, { force: true });
+  rmSync(`${dbPath}-shm`, { force: true });
+  rmSync(`${dbPath}-wal`, { force: true });
+  await Bun.sleep(10);
+  const db = openWriteTrailsDb({ rootDir });
+  try {
+    seedHistoryOnlyTopoSchema(db);
+  } finally {
+    db.close();
+  }
+};
+
 describe('topo store projection', () => {
   let tmpRoot: string | undefined;
 
@@ -361,109 +524,346 @@ describe('topo store projection', () => {
     }
   };
 
-  test('projects a save-scoped relational topo from the established app graph', () => {
+  test('projects a snapshot-scoped relational topo from the established app graph', () => {
     withProjectionDb((db) => {
-      const save = unwrap(
-        persistEstablishedTopoSave(db, exampleApp(), {
+      const snapshot = unwrap(
+        createTopoSnapshot(db, exampleApp(), {
           createdAt: '2026-04-03T12:00:00.000Z',
           gitDirty: false,
           gitSha: 'abc123',
         })
       );
-      expectProjectionCounts(db, save.id);
-      expectProjectedFixtureRows(db, save.id);
+      expectProjectionCounts(db, snapshot.id);
+      expectProjectedFixtureRows(db, snapshot.id);
 
-      const stored = requireStoredExport(db, save.id);
-      expect(JSON.parse(stored.trailheadMapJson)).toMatchObject({
+      const stored = requireStoredExport(db, snapshot.id);
+      const surfaceMap = JSON.parse(stored.surfaceMapJson);
+      const { entries } = surfaceMap as { entries?: unknown[] };
+      expect(surfaceMap).toMatchObject({
         entries: expect.any(Array),
         generatedAt: '2026-04-03T12:00:00.000Z',
         version: '1.0',
       });
+      expect(Array.isArray(entries)).toBe(true);
+      expect(
+        entries?.some((entry) => hasContourTrailheadEntry(entry, 'entity'))
+      ).toBe(true);
+
       expect(JSON.parse(stored.lockContent)).toMatchObject({
         apps: {
           'projection-app': {
-            provisions: expect.any(Object),
+            contours: {
+              entity: expect.objectContaining({
+                identity: 'id',
+              }),
+            },
+            resources: expect.any(Object),
             signals: expect.any(Object),
             trails: expect.any(Object),
           },
         },
         generatedAt: '2026-04-03T12:00:00.000Z',
-        hash: stored.trailheadHash,
+        hash: stored.surfaceHash,
         version: 1,
       });
     });
   });
 
-  test('keeps projected rows isolated across successive saves', () => {
+  test('keeps projected rows isolated across successive snapshots', () => {
     withProjectionDb((db) => {
-      const firstSave = unwrap(
-        persistEstablishedTopoSave(db, simpleProjectionApp(false), {
+      const firstSnapshot = unwrap(
+        createTopoSnapshot(db, simpleProjectionApp(false), {
           createdAt: '2026-04-03T12:00:00.000Z',
         })
       );
-      const secondSave = unwrap(
-        persistEstablishedTopoSave(db, simpleProjectionApp(true), {
+      const secondSnapshot = unwrap(
+        createTopoSnapshot(db, simpleProjectionApp(true), {
           createdAt: '2026-04-03T12:05:00.000Z',
         })
       );
 
-      expect(firstSave.id).not.toBe(secondSave.id);
-      expect(countRows(db, 'topo_trails', firstSave.id)).toBe(1);
-      expect(countRows(db, 'topo_trails', secondSave.id)).toBe(2);
-      expect(readProjectedTrailIds(db, firstSave.id)).toEqual(['entity.add']);
-      expect(readProjectedTrailIds(db, secondSave.id)).toEqual([
+      expect(firstSnapshot.id).not.toBe(secondSnapshot.id);
+      expect(countRows(db, 'topo_trails', firstSnapshot.id)).toBe(1);
+      expect(countRows(db, 'topo_trails', secondSnapshot.id)).toBe(2);
+      expect(readProjectedTrailIds(db, firstSnapshot.id)).toEqual([
+        'entity.add',
+      ]);
+      expect(readProjectedTrailIds(db, secondSnapshot.id)).toEqual([
         'entity.add',
         'entity.list',
       ]);
-      expect(requireStoredExport(db, firstSave.id).trailheadHash).not.toBe(
-        requireStoredExport(db, secondSave.id).trailheadHash
+      expect(requireStoredExport(db, firstSnapshot.id).surfaceHash).not.toBe(
+        requireStoredExport(db, secondSnapshot.id).surfaceHash
       );
     });
   });
 
-  test("pruning an unpinned save removes only that save's projected rows", () => {
+  test("pruning an unpinned snapshot removes only that snapshot's projected rows", () => {
     withProjectionDb((db) => {
-      const app = exampleApp();
       const pinned = unwrap(
-        persistEstablishedTopoSave(db, app, {
+        createTopoSnapshot(db, buildSignalPruneApp(), {
           createdAt: '2026-04-03T12:00:00.000Z',
         })
       );
-      pinTopoSave(db, { name: 'before-auth', saveId: pinned.id });
+      pinTopoSnapshot(db, { id: pinned.id, name: 'before-auth' });
 
       const disposable = unwrap(
-        persistEstablishedTopoSave(db, app, {
+        createTopoSnapshot(db, buildSignalPruneApp(), {
           createdAt: '2026-04-03T12:05:00.000Z',
         })
       );
 
-      expect(pruneUnpinnedTopoSaves(db, { keep: 0 })).toBe(1);
-      expectProjectionCounts(db, pinned.id);
-      expect(countRows(db, 'topo_trails', disposable.id)).toBe(0);
-      expect(countRows(db, 'topo_crossings', disposable.id)).toBe(0);
-      expect(countRows(db, 'topo_examples', disposable.id)).toBe(0);
-      expect(countRows(db, 'topo_schemas', disposable.id)).toBe(0);
+      // Pre-prune: both snapshots have fires/on rows so the cascade is non-vacuous.
+      expectSignalEdgeCounts(db, pinned.id, 1);
+      expectSignalEdgeCounts(db, disposable.id, 1);
+
+      expect(pruneUnpinnedSnapshots(db, { keep: 0 })).toBe(1);
+
+      // Pinned snapshot retains its projected rows, including fires/on edges.
+      expect(countRows(db, 'topo_trails', pinned.id)).toBe(2);
+      expectSignalEdgeCounts(db, pinned.id, 1);
+
+      expectDisposableSaveCascaded(db, disposable.id);
     });
   });
 
-  test('upgrades a history-only topo schema to the projected topo schema', () => {
+  test('persists fires and on edges for signal-declaring trails', () => {
+    withProjectionDb((db) => {
+      const created = signal('entity.created', {
+        from: ['entity.create'],
+        payload: z.object({ id: z.string() }),
+      });
+      const updated = signal('entity.updated', {
+        from: ['entity.create'],
+        payload: z.object({ id: z.string() }),
+      });
+
+      const createTrail = trail('entity.create', {
+        blaze: () => Result.ok({ id: 'x' }),
+        fires: ['entity.created', 'entity.updated'],
+        input: z.object({}),
+        output: z.object({ id: z.string() }),
+      });
+      const indexTrail = trail('entity.index', {
+        blaze: () => Result.ok({ ok: true }),
+        input: z.object({}),
+        on: ['entity.created'],
+        output: z.object({ ok: z.boolean() }),
+      });
+      const auditTrail = trail('entity.audit', {
+        blaze: () => Result.ok({ ok: true }),
+        input: z.object({}),
+        on: ['entity.created', 'entity.updated'],
+        output: z.object({ ok: z.boolean() }),
+      });
+
+      const snapshot = unwrap(
+        createTopoSnapshot(
+          db,
+          topo('signal-edges-app', {
+            auditTrail,
+            createTrail,
+            created,
+            indexTrail,
+            updated,
+          })
+        )
+      );
+
+      const fires = db
+        .query<{ signal_id: string; trail_id: string }, [string]>(
+          `SELECT trail_id, signal_id
+           FROM topo_trail_fires
+           WHERE snapshot_id = ?
+           ORDER BY trail_id ASC, signal_id ASC`
+        )
+        .all(snapshot.id);
+      expect(fires).toEqual([
+        { signal_id: 'entity.created', trail_id: 'entity.create' },
+        { signal_id: 'entity.updated', trail_id: 'entity.create' },
+      ]);
+
+      const on = db
+        .query<{ signal_id: string; trail_id: string }, [string]>(
+          `SELECT trail_id, signal_id
+           FROM topo_trail_on
+           WHERE snapshot_id = ?
+           ORDER BY trail_id ASC, signal_id ASC`
+        )
+        .all(snapshot.id);
+      expect(on).toEqual([
+        { signal_id: 'entity.created', trail_id: 'entity.audit' },
+        { signal_id: 'entity.updated', trail_id: 'entity.audit' },
+        { signal_id: 'entity.created', trail_id: 'entity.index' },
+      ]);
+    });
+  });
+
+  describe('snapshot schema migration guardrails', () => {
+    test('createTopoStore skips write-mode escalation when schema is current', () => {
+      const rootDir = makeRoot();
+      seedCurrentSchemaStore(rootDir);
+      assertNoWriteEscalationOnReads(rootDir);
+    });
+
+    test('createTopoStore ignores a legacy history-only store during cutover', () => {
+      const rootDir = makeRoot();
+      withWriteDb(rootDir, (db) => {
+        seedHistoryOnlyTopoSchema(db);
+      });
+
+      const caught = captureReadError(() =>
+        createTopoStore({ rootDir }).snapshots.latest()
+      );
+      expect(caught).toBeInstanceOf(NotFoundError);
+
+      withWriteDb(rootDir, (db) => {
+        expect(tableExists(db, 'topo_snapshots')).toBe(true);
+        expect(tableExists(db, 'topo_trails')).toBe(true);
+        expect(tableExists(db, 'topo_resources')).toBe(true);
+        expect(tableExists(db, 'topo_surfaces')).toBe(true);
+        expect(tableExists(db, 'topo_saves')).toBe(true);
+        expect(tableExists(db, 'topo_pins')).toBe(true);
+        expect(tableExists(db, 'topo_trailheads')).toBe(false);
+        expect(
+          db
+            .query<{ version: number }, []>(
+              "SELECT version FROM meta_schema_versions WHERE subsystem = 'topo'"
+            )
+            .get()?.version
+        ).toBe(8);
+        expect(countRows(db, 'topo_snapshots')).toBe(0);
+      });
+    });
+
+    test('createTopoSnapshot succeeds alongside a legacy projection store', () => {
+      withProjectionDb((db) => {
+        seedLegacyProjectionStore(db);
+
+        const snapshot = unwrap(
+          createTopoSnapshot(db, exampleApp(), {
+            createdAt: '2026-04-03T12:00:00.000Z',
+          })
+        );
+
+        expect(tableExists(db, 'topo_trailheads')).toBe(true);
+        expect(countRows(db, 'topo_snapshots')).toBe(1);
+        expectProjectionCounts(db, snapshot.id);
+      });
+    });
+
+    test('createTopoStore re-migrates after trails.db is replaced at the same path', async () => {
+      const rootDir = makeRoot();
+
+      // Round 1: seed a current-schema store and read through createTopoStore
+      // to prime the migration cache.
+      seedCurrentSchemaStore(rootDir);
+      captureReadError(() => createTopoStore({ rootDir }).snapshots.latest());
+      const baselineEscalations = __topoStoreMigrationStats.writeEscalations;
+
+      await replaceStoreWithHistoryOnlyStore(rootDir);
+
+      // Round 2: a fresh createTopoStore call must detect the file swap,
+      // re-run the migration, and keep surfacing the empty-store NotFound.
+      const caught = captureReadError(() =>
+        createTopoStore({ rootDir }).snapshots.latest()
+      );
+      expect(caught).toBeInstanceOf(NotFoundError);
+      expect(__topoStoreMigrationStats.writeEscalations).toBe(
+        baselineEscalations + 1
+      );
+      withWriteDb(rootDir, (db) => {
+        expect(tableExists(db, 'topo_snapshots')).toBe(true);
+        expect(countRows(db, 'topo_snapshots')).toBe(0);
+      });
+    });
+  });
+
+  test('history-only topo stores are ignored instead of translated into snapshots', () => {
     withProjectionDb((db) => {
       seedHistoryOnlyTopoSchema(db);
-      ensureTopoHistorySchema(db);
+      ensureTopoSnapshotSchema(db);
       expect(
         db
           .query<{ version: number }, []>(
             "SELECT version FROM meta_schema_versions WHERE subsystem = 'topo'"
           )
           .get()?.version
-      ).toBe(3);
-      expect(tableExists(db, 'topo_trails')).toBe(true);
-      expect(tableExists(db, 'topo_crossings')).toBe(true);
-      expect(tableExists(db, 'topo_examples')).toBe(true);
-      expect(tableExists(db, 'topo_exports')).toBe(true);
-      expect(tableExists(db, 'topo_schemas')).toBe(true);
-      expect(countRows(db, 'topo_saves')).toBe(1);
-      expect(countRows(db, 'topo_pins')).toBe(1);
+      ).toBe(8);
+      for (const table of [
+        'topo_snapshots',
+        'topo_trails',
+        'topo_crossings',
+        'topo_examples',
+        'topo_exports',
+        'topo_schemas',
+        'topo_surfaces',
+        'topo_trail_fires',
+        'topo_trail_on',
+      ]) {
+        expect(tableExists(db, table)).toBe(true);
+      }
+      expect(countRows(db, 'topo_snapshots')).toBe(0);
+      // Legacy history tables are left untouched during the migration and are
+      // simply ignored by the snapshot-first readers.
+      expect(tableExists(db, 'topo_saves')).toBe(true);
+      expect(tableExists(db, 'topo_pins')).toBe(true);
+      expect(tableExists(db, 'topo_trailheads')).toBe(false);
     });
   });
 });
+
+describe('signal edge normalizers', () => {
+  const makeTrail = (
+    id: string,
+    opts: {
+      readonly fires?: readonly string[];
+      readonly on?: readonly string[];
+    }
+  ) =>
+    trail(id, {
+      blaze: () => Result.ok({ ok: true }),
+      ...(opts.fires ? { fires: opts.fires } : {}),
+      input: z.object({}),
+      ...(opts.on ? { on: opts.on } : {}),
+      output: z.object({ ok: z.boolean() }),
+    });
+
+  test('normalizeFiresRows produces one row per (trail, signal) pair', () => {
+    const trails = [
+      makeTrail('t.one', { fires: ['s.a', 's.b'] }),
+      makeTrail('t.two', { fires: ['s.a'] }),
+    ];
+    expect(normalizeFiresRows(trails, 'snap-1')).toEqual([
+      { signalId: 's.a', snapshotId: 'snap-1', trailId: 't.one' },
+      { signalId: 's.b', snapshotId: 'snap-1', trailId: 't.one' },
+      { signalId: 's.a', snapshotId: 'snap-1', trailId: 't.two' },
+    ]);
+  });
+
+  test('normalizeOnRows produces one row per (trail, signal) pair', () => {
+    const trails = [
+      makeTrail('t.one', { on: ['s.a', 's.b'] }),
+      makeTrail('t.two', { on: ['s.b'] }),
+    ];
+    expect(normalizeOnRows(trails, 'snap-1')).toEqual([
+      { signalId: 's.a', snapshotId: 'snap-1', trailId: 't.one' },
+      { signalId: 's.b', snapshotId: 'snap-1', trailId: 't.one' },
+      { signalId: 's.b', snapshotId: 'snap-1', trailId: 't.two' },
+    ]);
+  });
+
+  test('trails without fires/on produce no rows', () => {
+    const trails = [makeTrail('t.plain', {})];
+    expect(normalizeFiresRows(trails, 'snap-1')).toEqual([]);
+    expect(normalizeOnRows(trails, 'snap-1')).toEqual([]);
+  });
+
+  test('deduplicates and sorts signal ids', () => {
+    const trails = [makeTrail('t.one', { fires: ['s.b', 's.a', 's.b'] })];
+    expect(normalizeFiresRows(trails, 'snap-1')).toEqual([
+      { signalId: 's.a', snapshotId: 'snap-1', trailId: 't.one' },
+      { signalId: 's.b', snapshotId: 'snap-1', trailId: 't.one' },
+    ]);
+  });
+});