@ontrails/trails 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trails/topo-store-support.ts

@@ -1,73 +1,105 @@
 /**
  * Stored-export pipeline for topo persistence.
  *
- * Extracted from topo-support.ts so this branch (trl-131) owns its own file,
- * keeping absorb routing clean across the stack.
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
  */
 
+import { Database } from 'bun:sqlite';
+
 import type { Topo } from '@ontrails/core';
-import { InternalError, Result } from '@ontrails/core';
-import type { TopoSaveRecord } from '@ontrails/core/internal/topo-saves';
-import type { StoredTopoExport } from '@ontrails/core/internal/topo-store';
-import {
-  getStoredTopoExport,
-  persistEstablishedTopoSave,
-} from '@ontrails/core/internal/topo-store';
 import {
+  deriveTrailsDir,
+  InternalError,
   openWriteTrailsDb,
-  resolveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
-import type { TrailheadLock, TrailheadMap } from '@ontrails/schema';
-import { writeTrailheadLock, writeTrailheadMap } from '@ontrails/schema';
+  Result,
+} from '@ontrails/core';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoSnapshot,
+} from '@ontrails/topographer';
+import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
+import { writeLockManifest, writeTopoGraph } from '@ontrails/topographer';
+import {
+  createStoredTopoSnapshot,
+  getStoredTopoExport,
+} from '@ontrails/topographer/backend-support';
 
 import type { TopoExportReport } from './topo-support.js';
-import { currentGitState, resolveRootDir, topoCounts } from './topo-support.js';
+import {
+  deriveRootDir,
+  deriveTopoCounts,
+  readGitState,
+} from './topo-support.js';
 
 const persistAndReadStoredExport = (
   app: Topo,
   db: ReturnType<typeof openWriteTrailsDb>,
   rootDir: string
-): Result<{ save: TopoSaveRecord; storedExport: StoredTopoExport }, Error> => {
-  const saveResult = persistEstablishedTopoSave(db, app, {
-    ...currentGitState(rootDir),
-    ...topoCounts(app),
+): Result<
+  { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
+  Error
+> => {
+  const snapshotResult = createStoredTopoSnapshot(db, app, {
+    ...readGitState(rootDir),
+    ...deriveTopoCounts(app),
   });
-  if (saveResult.isErr()) {
-    return saveResult;
+  if (snapshotResult.isErr()) {
+    return snapshotResult;
   }
 
-  const save = saveResult.value;
-  const storedExport = getStoredTopoExport(db, save.id);
+  const snapshot = snapshotResult.value;
+  const storedExport = getStoredTopoExport(db, snapshot.id);
 
   if (storedExport === undefined) {
     return Result.err(
-      new InternalError(`Missing stored topo export for save "${save.id}"`)
+      new InternalError(
+        `Missing stored topo export for snapshot "${snapshot.id}"`
+      )
     );
   }
 
   return Result.ok({
-    save,
+    snapshot,
     storedExport,
   });
 };
 
+export const deriveCurrentTopoExport = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Result<StoredTopoExport, Error> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const db = new Database(':memory:');
+
+  try {
+    const projected = persistAndReadStoredExport(app, db, rootDir);
+    return projected.isErr()
+      ? projected
+      : Result.ok(projected.value.storedExport);
+  } finally {
+    db.close();
+  }
+};
+
 const writeStoredExportArtifacts = async (
   storedExport: StoredTopoExport,
   trailsDir: string
-): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'mapPath'>> => {
-  const mapPath = await writeTrailheadMap(
-    JSON.parse(storedExport.trailheadMapJson) as TrailheadMap,
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
+  const topoPath = await writeTopoGraph(
+    JSON.parse(storedExport.topoGraphJson) as TopoGraph,
     { dir: trailsDir }
   );
-  const lockPath = await writeTrailheadLock(
-    JSON.parse(storedExport.lockContent) as TrailheadLock,
+  const lockPath = await writeLockManifest(
+    JSON.parse(storedExport.lockManifestJson) as LockManifest,
     { dir: trailsDir }
   );
 
   return {
-    hash: storedExport.trailheadHash,
+    hash: storedExport.topoGraphHash,
     lockPath,
-    mapPath,
+    topoPath,
   };
 };
 
@@ -75,7 +107,7 @@ export const exportCurrentTopo = async (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): Promise<Result<TopoExportReport, Error>> => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const db = openWriteTrailsDb({ rootDir });
 
   try {
@@ -84,12 +116,12 @@ export const exportCurrentTopo = async (
       return persisted;
     }
 
-    const { save, storedExport } = persisted.value;
+    const { snapshot, storedExport } = persisted.value;
     const artifacts = await writeStoredExportArtifacts(
       storedExport,
-      resolveTrailsDir({ rootDir })
+      deriveTrailsDir({ rootDir })
     );
-    return Result.ok({ ...artifacts, save });
+    return Result.ok({ ...artifacts, snapshot });
   } finally {
     db.close();
   }

package/src/trails/topo-support.ts

@@ -1,64 +1,44 @@
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
+import { deriveTrailsDbPath } from '@ontrails/core';
 import type { Topo } from '@ontrails/core';
-import type {
-  TopoPinRecord,
-  TopoSaveRecord,
-} from '@ontrails/core/internal/topo-saves';
 import {
-  getTopoPin,
-  listTopoPins,
-  listTopoSaves,
-  pinTopoSave,
-  unpinTopoSave,
-} from '@ontrails/core/internal/topo-saves';
-import { persistEstablishedTopoSave } from '@ontrails/core/internal/topo-store';
-import {
-  openReadTrailsDb,
-  openWriteTrailsDb,
-  resolveTrailsDbPath,
-} from '@ontrails/core/internal/trails-db';
+  createTopoSnapshot as persistTopoSnapshot,
+  listTopoSnapshots as readTopoSnapshots,
+  pinTopoSnapshot,
+  unpinTopoSnapshot,
+} from '@ontrails/topographer';
+import type { TopoSnapshot } from '@ontrails/topographer';
 import { z } from 'zod';
 
+import {
+  createIsolatedExampleRoot,
+  writeIsolatedExampleAppModule,
+} from '../local-state-io.js';
+
+import { requireTrailRootDir } from './root-dir.js';
 import type { BriefReport, SurveyListReport } from './topo-reports.js';
 
-/** Output schema for a topo save record. Shared across topo trails. */
-export const topoSaveOutput = z.object({
+/** Output schema for a topo snapshot record. Shared across topo trails. */
+export const topoSnapshotOutput = z.object({
   createdAt: z.string(),
   gitDirty: z.boolean(),
   gitSha: z.string().optional(),
   id: z.string(),
-  provisionCount: z.number(),
+  pinnedAs: z.string().optional(),
+  resourceCount: z.number(),
   signalCount: z.number(),
   trailCount: z.number(),
 });
 
-/** Output schema for a topo pin record. Shared across topo trails. */
-export const topoPinOutput = z.object({
-  createdAt: z.string(),
-  name: z.string(),
-  saveId: z.string(),
-});
-
-export const DEFAULT_APP_MODULE = './src/app.ts';
 export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
 export const LOCK_PATH = '.trails/trails.lock';
-export const LEGACY_LOCK_PATH = '.trails/trailhead.lock';
-
-/** Resolve the lockfile path, preferring the current name with legacy fallback. */
-export const resolveLockPath = (trailsDir: string): string => {
-  const primary = join(trailsDir, 'trails.lock');
-  if (existsSync(primary)) {
-    return primary;
-  }
-  const legacy = join(trailsDir, 'trailhead.lock');
-  return existsSync(legacy) ? legacy : primary;
-};
 const EXAMPLE_APP_MODULE = fileURLToPath(new URL('../app.ts', import.meta.url));
 
+const uniqueExampleRootName = (name: string): string =>
+  `${name}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
 export interface TopoSummaryReport {
   readonly app: BriefReport;
   readonly dbPath: string;
@@ -70,17 +50,16 @@ export interface TopoSummaryReport {
 export interface TopoHistoryReport {
   readonly dbPath: string;
   readonly limit: number;
-  readonly pinCount: number;
-  readonly pins: TopoPinRecord[];
-  readonly saveCount: number;
-  readonly saves: TopoSaveRecord[];
+  readonly pinnedCount: number;
+  readonly snapshotCount: number;
+  readonly snapshots: TopoSnapshot[];
 }
 
 export interface TopoExportReport {
   readonly hash: string;
   readonly lockPath: string;
-  readonly mapPath: string;
-  readonly save: TopoSaveRecord;
+  readonly snapshot: TopoSnapshot;
+  readonly topoPath: string;
 }
 
 export interface TopoVerifyReport {
@@ -90,7 +69,7 @@ export interface TopoVerifyReport {
   readonly stale: false;
 }
 
-export const resolveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+export const deriveRootDir = (cwd?: string): string => requireTrailRootDir(cwd);
 
 const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
   const proc = Bun.spawnSync({
@@ -105,7 +84,7 @@ const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
   return text.length === 0 ? undefined : text;
 };
 
-export const currentGitState = (
+export const readGitState = (
   rootDir: string
 ): { readonly gitDirty: boolean; readonly gitSha?: string } => {
   const gitSha = safeGit(rootDir, ['rev-parse', 'HEAD']);
@@ -116,10 +95,10 @@ export const currentGitState = (
   };
 };
 
-export const topoCounts = (
+export const deriveTopoCounts = (
   app: Topo
-): Pick<TopoSaveRecord, 'provisionCount' | 'signalCount' | 'trailCount'> => ({
-  provisionCount: app.provisions.size,
+): Pick<TopoSnapshot, 'resourceCount' | 'signalCount' | 'trailCount'> => ({
+  resourceCount: app.resources.size,
   signalCount: app.signals.size,
   trailCount: app.trails.size,
 });
@@ -130,145 +109,112 @@ const emptyTopoHistory = (
 ): TopoHistoryReport => ({
   dbPath,
   limit,
-  pinCount: 0,
-  pins: [],
-  saveCount: 0,
-  saves: [],
+  pinnedCount: 0,
+  snapshotCount: 0,
+  snapshots: [],
 });
 
-const collectedTopoHistory = (
+const collectTopoHistory = (
   dbPath: string,
   limit: number,
-  pins: readonly TopoPinRecord[],
-  allSaves: readonly TopoSaveRecord[]
+  snapshots: readonly TopoSnapshot[]
 ): TopoHistoryReport => ({
   dbPath,
   limit,
-  pinCount: pins.length,
-  pins: [...pins],
-  saveCount: allSaves.length,
-  saves: allSaves.slice(0, limit),
+  pinnedCount: snapshots.filter((snapshot) => snapshot.pinnedAs !== undefined)
+    .length,
+  snapshotCount: snapshots.length,
+  snapshots: snapshots.slice(0, limit),
 });
 
-const removeTopoPinWithDb = (
-  input: { readonly dryRun: boolean; readonly name: string },
-  pin: TopoPinRecord,
-  db: Parameters<typeof unpinTopoSave>[0]
+const buildSnapshotInput = (
+  app: Topo,
+  rootDir: string
 ): {
-  readonly dryRun: boolean;
-  readonly pin?: TopoPinRecord;
-  readonly removed: boolean;
-} =>
-  input.dryRun
-    ? { dryRun: true, pin, removed: false }
-    : { dryRun: false, pin, removed: unpinTopoSave(db, input.name) };
+  readonly gitDirty: boolean;
+  readonly gitSha?: string;
+  readonly resourceCount: number;
+  readonly signalCount: number;
+  readonly trailCount: number;
+} => ({
+  ...readGitState(rootDir),
+  ...deriveTopoCounts(app),
+});
 
-export const isolatedExampleInput = (
+export const createIsolatedExampleInput = (
   name: string
 ): { readonly module: string; readonly rootDir: string } => {
-  const rootDir = join(tmpdir(), 'ontrails-trails-examples', name);
-  rmSync(rootDir, { force: true, recursive: true });
-  mkdirSync(rootDir, { recursive: true });
+  const rootDir = createIsolatedExampleRoot(uniqueExampleRootName(name));
   return {
-    module: EXAMPLE_APP_MODULE,
+    module: writeIsolatedExampleAppModule(rootDir, EXAMPLE_APP_MODULE),
     rootDir,
   };
 };
 
-export const createCurrentTopoSave = (
-  app: Topo,
-  options?: { readonly rootDir?: string }
-): TopoSaveRecord => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const db = openWriteTrailsDb({ rootDir });
-
-  try {
-    const result = persistEstablishedTopoSave(db, app, {
-      ...currentGitState(rootDir),
-      ...topoCounts(app),
-    });
-    if (result.isErr()) {
-      throw result.error;
-    }
-    return result.value;
-  } finally {
-    db.close();
-  }
-};
-
 export const listTopoHistory = (options?: {
   readonly limit?: number;
   readonly rootDir?: string;
 }): TopoHistoryReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const limit = options?.limit ?? DEFAULT_TOPO_HISTORY_LIMIT;
-  const dbPath = resolveTrailsDbPath({ rootDir });
+  const dbPath = deriveTrailsDbPath({ rootDir });
   if (!existsSync(dbPath)) {
     return emptyTopoHistory(dbPath, limit);
   }
-  const db = openReadTrailsDb({ rootDir });
 
-  try {
-    return collectedTopoHistory(
-      dbPath,
-      limit,
-      listTopoPins(db),
-      listTopoSaves(db)
-    );
-  } finally {
-    db.close();
-  }
+  return collectTopoHistory(dbPath, limit, readTopoSnapshots({ rootDir }));
 };
 
-export const pinCurrentTopo = (
+export const pinCurrentTopoSnapshot = (
   app: Topo,
   input: { readonly name: string; readonly rootDir?: string }
-): { readonly pin: TopoPinRecord; readonly save: TopoSaveRecord } => {
-  const rootDir = resolveRootDir(input.rootDir);
-  const db = openWriteTrailsDb({ rootDir });
+): { readonly snapshot: TopoSnapshot } => {
+  const rootDir = deriveRootDir(input.rootDir);
+  const created = persistTopoSnapshot(app, {
+    rootDir,
+    ...buildSnapshotInput(app, rootDir),
+  });
+  if (created.isErr()) {
+    throw created.error;
+  }
 
-  try {
-    const result = persistEstablishedTopoSave(db, app, {
-      ...currentGitState(rootDir),
-      ...topoCounts(app),
-    });
-    if (result.isErr()) {
-      throw result.error;
-    }
-    const pin = pinTopoSave(db, {
-      name: input.name,
-      saveId: result.value.id,
-    });
-    return { pin, save: result.value };
-  } finally {
-    db.close();
+  const snapshot = pinTopoSnapshot(created.value.id, input.name, {
+    rootDir,
+  });
+  if (snapshot === undefined) {
+    throw new Error(`Missing topo snapshot "${created.value.id}" to pin`);
   }
+
+  return { snapshot };
 };
 
-export const removeTopoPin = (input: {
+export const removePinnedTopoSnapshot = (input: {
   readonly dryRun: boolean;
   readonly name: string;
   readonly rootDir?: string;
 }): {
   readonly dryRun: boolean;
-  readonly pin?: TopoPinRecord;
   readonly removed: boolean;
+  readonly snapshot?: TopoSnapshot;
 } => {
-  const rootDir = resolveRootDir(input.rootDir);
-  if (!existsSync(resolveTrailsDbPath({ rootDir }))) {
+  const rootDir = deriveRootDir(input.rootDir);
+  if (!existsSync(deriveTrailsDbPath({ rootDir }))) {
     return { dryRun: input.dryRun, removed: false };
   }
-  const db = input.dryRun
-    ? openReadTrailsDb({ rootDir })
-    : openWriteTrailsDb({ rootDir });
 
-  try {
-    const pin = getTopoPin(db, input.name);
-    if (pin === undefined) {
-      return { dryRun: input.dryRun, removed: false };
-    }
-    return removeTopoPinWithDb(input, pin, db);
-  } finally {
-    db.close();
+  if (input.dryRun) {
+    const snapshot = readTopoSnapshots({ pinned: true, rootDir }).find(
+      (candidate) => candidate.pinnedAs === input.name
+    );
+    return snapshot === undefined
+      ? { dryRun: true, removed: false }
+      : { dryRun: true, removed: false, snapshot };
   }
+
+  const snapshot = unpinTopoSnapshot(input.name, { rootDir });
+  return {
+    dryRun: false,
+    removed: snapshot !== undefined,
+    ...(snapshot === undefined ? {} : { snapshot }),
+  };
 };

package/src/trails/topo-unpin.ts

@@ -2,10 +2,11 @@ import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
-  isolatedExampleInput,
-  removeTopoPin,
-  topoPinOutput,
+  createIsolatedExampleInput,
+  removePinnedTopoSnapshot,
+  topoSnapshotOutput,
 } from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 export const topoUnpinTrail = trail('topo.unpin', {
   blaze: (input, ctx) => {
@@ -17,16 +18,24 @@ export const topoUnpinTrail = trail('topo.unpin', {
       );
     }
 
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     return Result.ok(
-      removeTopoPin({ dryRun: input.dryRun, name: input.name, rootDir })
+      removePinnedTopoSnapshot({
+        dryRun: input.dryRun,
+        name: input.name,
+        rootDir,
+      })
     );
   },
   description: 'Remove a named topo pin',
   examples: [
     {
       input: {
-        ...isolatedExampleInput('topo-unpin'),
+        ...createIsolatedExampleInput('topo-unpin'),
         dryRun: true,
         name: 'before-auth-refactor',
       },
@@ -45,7 +54,8 @@ export const topoUnpinTrail = trail('topo.unpin', {
   intent: 'destroy',
   output: z.object({
     dryRun: z.boolean(),
-    pin: topoPinOutput.optional(),
     removed: z.boolean(),
+    snapshot: topoSnapshotOutput.optional(),
   }),
+  permit: { scopes: ['topo:delete'] },
 });

package/src/trails/topo-verify.ts

@@ -1,22 +1,31 @@
-import { trail } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
 import { verifyCurrentTopo } from './topo-read-support.js';
-import { DEFAULT_APP_MODULE } from './topo-support.js';
 
 export const topoVerifyTrail = trail('topo.verify', {
   blaze: async (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    const app = await loadApp(input.module, rootDir);
-    return verifyCurrentTopo(app, { rootDir });
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return Result.err(leaseResult.error);
+    }
+    const lease = leaseResult.value;
+    try {
+      return await verifyCurrentTopo(lease.app, { rootDir });
+    } finally {
+      lease.release();
+    }
   },
   description: 'Verify that the committed lockfile matches the current topo',
   input: z.object({
-    module: z
-      .string()
-      .default(DEFAULT_APP_MODULE)
-      .describe('Path to the app module'),
+    module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',