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

package/src/topo-store.ts

@@ -1,83 +1,222 @@
 import type { SQLQueryBindings } from 'bun:sqlite';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 
 import { NotFoundError } from './errors.js';
-import { provision } from './provision.js';
+import type { Topo } from './topo.js';
+import { resource } from './resource.js';
 import { Result } from './result.js';
-import type { TopoPinRecord, TopoSaveRecord } from './internal/topo-saves.js';
-import { getTopoPin } from './internal/topo-saves.js';
+import {
+  TOPO_SCHEMA_VERSION,
+  ensureTopoSnapshotSchema,
+  listTopoSnapshots as listStoredTopoSnapshots,
+  pinTopoSnapshot as pinStoredTopoSnapshot,
+  unpinTopoSnapshot as unpinStoredTopoSnapshot,
+} from './internal/topo-snapshots.js';
+import type {
+  CreateTopoSnapshotInput,
+  ListTopoSnapshotsOptions,
+  TopoSnapshot,
+} from './internal/topo-snapshots.js';
 import type {
   TopoStoreExportRecord,
-  TopoStoreProvisionRecord,
+  TopoStoreResourceRecord,
   TopoStoreRef,
   TopoStoreTrailDetailRecord,
   TopoStoreTrailRecord,
 } from './internal/topo-store-read.js';
 import {
   getTopoStoreExport,
-  getTopoStoreProvision,
+  getTopoStoreResource,
   getTopoStoreTrail,
-  listTopoStorePins,
-  listTopoStoreProvisions,
-  listTopoStoreSaves,
+  listTopoStoreResources,
+  listTopoStoreSnapshots,
   listTopoStoreTrails,
   queryTopoStore,
-  resolveTopoStoreSave,
+  readTopoStoreSnapshot,
 } from './internal/topo-store-read.js';
-import { openReadTrailsDb, resolveTrailsDbPath } from './internal/trails-db.js';
+import { createTopoSnapshot as storeTopoSnapshot } from './internal/topo-store.js';
+import {
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  deriveTrailsDbPath,
+} from './internal/trails-db.js';
 import type { TrailsDbLocationOptions } from './internal/trails-db.js';
 
+interface MigratedDbIdentity {
+  readonly mtimeMs: number;
+  readonly size: number;
+}
+
+const migratedTopoDbPaths = new Map<string, MigratedDbIdentity>();
+
+/**
+ * Test-only instrumentation counters. Incremented by the read-path migration
+ * check to let tests assert that a current-schema store does not escalate to
+ * a write-mode open, and that cache invalidation re-runs the check when the
+ * underlying file is replaced.
+ *
+ * @internal
+ */
+export const __topoStoreMigrationStats = {
+  peekCalls: 0,
+  writeEscalations: 0,
+};
+
+const peekTopoSchemaVersion = (
+  options: TrailsDbLocationOptions | undefined
+): number | undefined => {
+  let db: ReturnType<typeof openReadTrailsDb> | undefined;
+  try {
+    db = openReadTrailsDb(options);
+    const row = db
+      .query<{ version: number }, [string]>(
+        'SELECT version FROM meta_schema_versions WHERE subsystem = ?'
+      )
+      .get('topo');
+    return row?.version ?? 0;
+  } catch {
+    // Table missing or unexpected shape: caller will escalate to a write-mode
+    // open and run the migration, which rebuilds the schema.
+    return undefined;
+  } finally {
+    db?.close();
+  }
+};
+
+const statIdentity = (dbPath: string): MigratedDbIdentity | undefined => {
+  try {
+    const info = statSync(dbPath);
+    return { mtimeMs: info.mtimeMs, size: info.size };
+  } catch {
+    return undefined;
+  }
+};
+
+const identitiesEqual = (
+  a: MigratedDbIdentity,
+  b: MigratedDbIdentity
+): boolean => a.mtimeMs === b.mtimeMs && a.size === b.size;
+
+const runTopoMigrationEscalation = (
+  options: TrailsDbLocationOptions | undefined,
+  dbPath: string,
+  fallbackIdentity: MigratedDbIdentity
+): void => {
+  __topoStoreMigrationStats.writeEscalations += 1;
+  const db = openWriteTrailsDb(options);
+  try {
+    ensureTopoSnapshotSchema(db);
+  } finally {
+    db.close();
+  }
+  // Re-stat after the migration so the cached identity matches the file we
+  // just touched, avoiding a spurious second escalation on the next read.
+  const postIdentity = statIdentity(dbPath) ?? fallbackIdentity;
+  migratedTopoDbPaths.set(dbPath, postIdentity);
+};
+
+const resolveIdentityIfFresh = (
+  dbPath: string
+): MigratedDbIdentity | undefined => {
+  if (!existsSync(dbPath)) {
+    return undefined;
+  }
+  const identity = statIdentity(dbPath);
+  if (identity === undefined) {
+    return undefined;
+  }
+  const cached = migratedTopoDbPaths.get(dbPath);
+  if (cached !== undefined && identitiesEqual(cached, identity)) {
+    return undefined;
+  }
+  return identity;
+};
+
+/**
+ * Ensure the topo snapshot schema is at the current version before any
+ * read-only access. Peeks the version through a read-only handle first and
+ * only escalates to a write-mode open + migration when the store is stale.
+ *
+ * Memoized per resolved DB path keyed on file identity (mtime + size) so a
+ * long-running process that deletes and recreates `trails.db` re-runs the
+ * migration check against the fresh file.
+ *
+ * If the DB file does not yet exist, this is a no-op — the downstream read
+ * path will surface its own NotFoundError.
+ */
+const ensureTopoMigratedIfExists = (
+  options?: TrailsDbLocationOptions
+): void => {
+  const dbPath = deriveTrailsDbPath(options);
+  const identity = resolveIdentityIfFresh(dbPath);
+  if (identity === undefined) {
+    return;
+  }
+
+  __topoStoreMigrationStats.peekCalls += 1;
+  const version = peekTopoSchemaVersion(options);
+  if (version !== undefined && version >= TOPO_SCHEMA_VERSION) {
+    // Already current — record identity and skip the write-mode open entirely,
+    // preserving the read-only contract for callers whose filesystem mounts
+    // `trails.db` read-only.
+    migratedTopoDbPaths.set(dbPath, identity);
+    return;
+  }
+
+  runTopoMigrationEscalation(options, dbPath, identity);
+};
+
 export type {
   TopoStoreExportRecord,
-  TopoStoreProvisionRecord,
+  TopoStoreResourceRecord,
   TopoStoreRef,
   TopoStoreTrailDetailRecord,
   TopoStoreTrailRecord,
 } from './internal/topo-store-read.js';
+export type {
+  CreateTopoSnapshotInput,
+  ListTopoSnapshotsOptions,
+  TopoSnapshot,
+} from './internal/topo-snapshots.js';
 
 export interface ReadOnlyTopoStore {
   readonly exports: {
     get(ref?: TopoStoreRef): TopoStoreExportRecord | undefined;
   };
-  readonly pins: {
-    get(name: string): TopoPinRecord | undefined;
-    list(): readonly TopoPinRecord[];
-  };
   query<TRow extends Record<string, unknown>>(
     sql: string,
     bindings?: readonly SQLQueryBindings[]
   ): readonly TRow[];
-  readonly provisions: {
+  readonly resources: {
     get(
       id: string,
-      options?: { readonly save?: TopoStoreRef }
-    ): TopoStoreProvisionRecord | undefined;
+      options?: { readonly snapshot?: TopoStoreRef }
+    ): TopoStoreResourceRecord | undefined;
     list(options?: {
-      readonly save?: TopoStoreRef;
-    }): readonly TopoStoreProvisionRecord[];
+      readonly snapshot?: TopoStoreRef;
+    }): readonly TopoStoreResourceRecord[];
   };
-  readonly saves: {
-    get(ref?: TopoStoreRef): TopoSaveRecord | undefined;
-    latest(): TopoSaveRecord | undefined;
-    list(): readonly TopoSaveRecord[];
+  readonly snapshots: {
+    get(ref?: TopoStoreRef): TopoSnapshot | undefined;
+    latest(): TopoSnapshot | undefined;
+    list(options?: ListTopoSnapshotsOptions): readonly TopoSnapshot[];
   };
   readonly trails: {
     get(
       id: string,
-      options?: { readonly save?: TopoStoreRef }
+      options?: { readonly snapshot?: TopoStoreRef }
     ): TopoStoreTrailDetailRecord | undefined;
     list(options?: {
       readonly intent?: TopoStoreTrailRecord['intent'];
-      readonly save?: TopoStoreRef;
+      readonly snapshot?: TopoStoreRef;
     }): readonly TopoStoreTrailRecord[];
   };
 }
 
 export interface MockTopoStoreSeed {
   readonly exports?: readonly TopoStoreExportRecord[];
-  readonly pins?: readonly TopoPinRecord[];
-  readonly provisions?: readonly TopoStoreProvisionRecord[];
-  readonly saves?: readonly TopoSaveRecord[];
+  readonly resources?: readonly TopoStoreResourceRecord[];
+  readonly snapshots?: readonly TopoSnapshot[];
   readonly trails?: readonly TopoStoreTrailDetailRecord[];
 }
 
@@ -90,17 +229,18 @@ const resolveStoreRootDir = (options?: TrailsDbLocationOptions): string =>
 const requireReadDb = (
   options?: TrailsDbLocationOptions
 ): ReturnType<typeof openReadTrailsDb> => {
-  const dbPath = resolveTrailsDbPath(options);
+  const dbPath = deriveTrailsDbPath(options);
   if (!existsSync(dbPath)) {
     throw new NotFoundError(missingStoreMessage);
   }
+  ensureTopoMigratedIfExists(options);
   return openReadTrailsDb(options);
 };
 
 const requireSavedTopoState = (
   db: ReturnType<typeof openReadTrailsDb>
 ): void => {
-  if (resolveTopoStoreSave(db) === undefined) {
+  if (readTopoStoreSnapshot(db) === undefined) {
     throw new NotFoundError(missingStoreMessage);
   }
 };
@@ -119,31 +259,26 @@ const withStoredTopoState = <T>(
 };
 
 const createSeedResolver = (seed?: MockTopoStoreSeed) => {
-  const saves = [...(seed?.saves ?? [])];
-  const pins = [...(seed?.pins ?? [])];
+  const snapshots = [...(seed?.snapshots ?? [])];
   const trails = [...(seed?.trails ?? [])];
-  const provisions = [...(seed?.provisions ?? [])];
+  const resources = [...(seed?.resources ?? [])];
   const exports = [...(seed?.exports ?? [])];
 
-  const resolveSave = (ref?: TopoStoreRef): TopoSaveRecord | undefined => {
-    if (ref?.saveId !== undefined) {
-      return saves.find((save) => save.id === ref.saveId);
+  const resolveSnapshot = (ref?: TopoStoreRef): TopoSnapshot | undefined => {
+    if (ref?.snapshotId !== undefined) {
+      return snapshots.find((snapshot) => snapshot.id === ref.snapshotId);
     }
     if (ref?.pin !== undefined) {
-      const pin = pins.find((candidate) => candidate.name === ref.pin);
-      return pin === undefined
-        ? undefined
-        : saves.find((save) => save.id === pin.saveId);
+      return snapshots.find((snapshot) => snapshot.pinnedAs === ref.pin);
     }
-    return saves[0];
+    return snapshots[0];
   };
 
   return {
     exports,
-    pins,
-    provisions,
-    resolveSave,
-    saves,
+    resolveSnapshot,
+    resources,
+    snapshots,
     trails,
   };
 };
@@ -156,69 +291,85 @@ export const createMockTopoStore = (
   return {
     exports: {
       get(ref?: TopoStoreRef) {
-        const save = resolved.resolveSave(ref);
-        return save === undefined
+        const snapshot = resolved.resolveSnapshot(ref);
+        return snapshot === undefined
           ? undefined
-          : resolved.exports.find((entry) => entry.save.id === save.id);
+          : resolved.exports.find((entry) => entry.snapshot.id === snapshot.id);
       },
     },
-    pins: {
-      get(name: string) {
-        return resolved.pins.find((pin) => pin.name === name);
-      },
-      list() {
-        return resolved.pins;
-      },
+    query() {
+      throw new NotFoundError(
+        'Mock topoStore.query() is unsupported. Seed typed accessors instead.'
+      );
     },
-    provisions: {
+    resources: {
       get(id, options) {
-        const save = resolved.resolveSave(options?.save);
-        return resolved.provisions.find(
+        const snapshot = resolved.resolveSnapshot(options?.snapshot);
+        return resolved.resources.find(
           (item) =>
-            item.id === id && (save === undefined || item.saveId === save.id)
+            item.id === id &&
+            (snapshot === undefined || item.snapshotId === snapshot.id)
         );
       },
       list(options) {
-        const save = resolved.resolveSave(options?.save);
-        return save === undefined
+        const snapshot = resolved.resolveSnapshot(options?.snapshot);
+        return snapshot === undefined
           ? []
-          : resolved.provisions.filter((item) => item.saveId === save.id);
+          : resolved.resources.filter(
+              (item) => item.snapshotId === snapshot.id
+            );
       },
     },
-    query() {
-      throw new NotFoundError(
-        'Mock topoStore.query() is unsupported. Seed typed accessors instead.'
-      );
-    },
-    saves: {
+    snapshots: {
       get(ref?: TopoStoreRef) {
-        return resolved.resolveSave(ref);
+        return resolved.resolveSnapshot(ref);
       },
       latest() {
-        return resolved.saves[0];
+        return resolved.snapshots[0];
       },
-      list() {
-        return resolved.saves;
+      list(options) {
+        let snapshots =
+          options?.pinned === undefined
+            ? resolved.snapshots
+            : resolved.snapshots.filter((snapshot) =>
+                options.pinned
+                  ? snapshot.pinnedAs !== undefined
+                  : snapshot.pinnedAs === undefined
+              );
+        if (options?.before !== undefined) {
+          const target = snapshots.find((s) => s.id === options.before);
+          if (target !== undefined) {
+            snapshots = snapshots.filter(
+              (s) =>
+                s.createdAt < target.createdAt ||
+                (s.createdAt === target.createdAt && s.id < target.id)
+            );
+          }
+        }
+        if (options?.limit !== undefined) {
+          snapshots = snapshots.slice(0, options.limit);
+        }
+        return snapshots;
       },
     },
     trails: {
       get(id, options) {
-        const save = resolved.resolveSave(options?.save);
-        if (save === undefined) {
+        const snapshot = resolved.resolveSnapshot(options?.snapshot);
+        if (snapshot === undefined) {
           return;
         }
         return resolved.trails.find(
-          (trail) => trail.id === id && trail.saveId === save.id
+          (trail) => trail.id === id && trail.snapshotId === snapshot.id
         );
       },
       list(options) {
-        const save = resolved.resolveSave(options?.save);
-        if (save === undefined) {
+        const snapshot = resolved.resolveSnapshot(options?.snapshot);
+        if (snapshot === undefined) {
           return [];
         }
         return resolved.trails.filter(
           (trail) =>
-            trail.saveId === save.id &&
+            trail.snapshotId === snapshot.id &&
             (options?.intent === undefined || trail.intent === options.intent)
         );
       },
@@ -234,45 +385,39 @@ export const createTopoStore = (
       return withStoredTopoState(options, (db) => getTopoStoreExport(db, ref));
     },
   },
-  pins: {
-    get(name: string) {
-      return withStoredTopoState(options, (db) => getTopoPin(db, name));
-    },
-    list() {
-      return withStoredTopoState(options, (db) => listTopoStorePins(db));
-    },
+  query<TRow extends Record<string, unknown>>(
+    sql: string,
+    bindings?: readonly SQLQueryBindings[]
+  ) {
+    return withStoredTopoState(options, (db) =>
+      queryTopoStore<TRow>(db, sql, bindings)
+    );
   },
-  provisions: {
+  resources: {
     get(id, queryOptions) {
       return withStoredTopoState(options, (db) =>
-        getTopoStoreProvision(db, id, queryOptions)
+        getTopoStoreResource(db, id, queryOptions)
       );
     },
     list(queryOptions) {
       return withStoredTopoState(options, (db) =>
-        listTopoStoreProvisions(db, queryOptions)
+        listTopoStoreResources(db, queryOptions)
       );
     },
   },
-  query<TRow extends Record<string, unknown>>(
-    sql: string,
-    bindings?: readonly SQLQueryBindings[]
-  ) {
-    return withStoredTopoState(options, (db) =>
-      queryTopoStore<TRow>(db, sql, bindings)
-    );
-  },
-  saves: {
+  snapshots: {
     get(ref?: TopoStoreRef) {
       return withStoredTopoState(options, (db) =>
-        resolveTopoStoreSave(db, ref)
+        readTopoStoreSnapshot(db, ref)
       );
     },
     latest() {
-      return withStoredTopoState(options, (db) => resolveTopoStoreSave(db));
+      return withStoredTopoState(options, (db) => readTopoStoreSnapshot(db));
     },
-    list() {
-      return withStoredTopoState(options, (db) => listTopoStoreSaves(db));
+    list(snapshotOptions) {
+      return withStoredTopoState(options, (db) =>
+        listTopoStoreSnapshots(db, snapshotOptions)
+      );
     },
   },
   trails: {
@@ -289,7 +434,71 @@ export const createTopoStore = (
   },
 });
 
-export const topoStore = provision('topo.store', {
+export const createTopoSnapshot = (
+  topo: Topo,
+  options?: TrailsDbLocationOptions & CreateTopoSnapshotInput
+): Result<TopoSnapshot, Error> => {
+  const db = openWriteTrailsDb(options);
+  try {
+    return storeTopoSnapshot(db, topo, options);
+  } finally {
+    db.close();
+  }
+};
+
+export const listTopoSnapshots = (
+  options?: TrailsDbLocationOptions & ListTopoSnapshotsOptions
+): readonly TopoSnapshot[] => {
+  const dbPath = deriveTrailsDbPath(options);
+  if (!existsSync(dbPath)) {
+    return [];
+  }
+
+  ensureTopoMigratedIfExists(options);
+  const db = openReadTrailsDb(options);
+  try {
+    return listStoredTopoSnapshots(db, options);
+  } finally {
+    db.close();
+  }
+};
+
+export const pinTopoSnapshot = (
+  id: string,
+  name: string,
+  options?: TrailsDbLocationOptions
+): TopoSnapshot | undefined => {
+  const dbPath = deriveTrailsDbPath(options);
+  if (!existsSync(dbPath)) {
+    return undefined;
+  }
+
+  const db = openWriteTrailsDb(options);
+  try {
+    return pinStoredTopoSnapshot(db, { id, name });
+  } finally {
+    db.close();
+  }
+};
+
+export const unpinTopoSnapshot = (
+  nameOrId: string,
+  options?: TrailsDbLocationOptions
+): TopoSnapshot | undefined => {
+  const dbPath = deriveTrailsDbPath(options);
+  if (!existsSync(dbPath)) {
+    return undefined;
+  }
+
+  const db = openWriteTrailsDb(options);
+  try {
+    return unpinStoredTopoSnapshot(db, nameOrId);
+  } finally {
+    db.close();
+  }
+};
+
+export const topoStore = resource('topo.store', {
   create: (svc) =>
     Result.ok(
       createTopoStore({