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

package/src/trails/dev-reset.ts

@@ -2,7 +2,7 @@ import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { resetDevState } from './dev-support.js';
-import { isolatedExampleInput } from './topo-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devResetTrail = trail('dev.reset', {
   blaze: (input, ctx) => {
@@ -22,7 +22,7 @@ export const devResetTrail = trail('dev.reset', {
     {
       input: {
         dryRun: true,
-        rootDir: isolatedExampleInput('dev-reset').rootDir,
+        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
       },
       name: 'Preview local reset',
     },
@@ -41,4 +41,5 @@ export const devResetTrail = trail('dev.reset', {
     removedCount: z.number(),
     removedFiles: z.array(z.string()),
   }),
+  permit: { scopes: ['dev:reset'] },
 });

package/src/trails/dev-stats.ts

@@ -1,39 +1,42 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { buildDevStats, DEFAULT_TOPO_SAVE_RETENTION } from './dev-support.js';
-import { isolatedExampleInput } from './topo-support.js';
+import {
+  buildDevStats,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devStatsTrail = trail('dev.stats', {
   blaze: (input, ctx) => {
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
     return Result.ok(
       buildDevStats({
-        maxAge: input.trackAgeMs,
-        maxRecords: input.tracks,
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
         rootDir,
-        saveRetention: input.saves,
+        snapshotRetention: input.snapshots,
       })
     );
   },
   description: 'Show local Trails workspace state and retention',
   examples: [
     {
-      input: { rootDir: isolatedExampleInput('dev-stats').rootDir },
+      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
       name: 'Show local dev state',
     },
   ],
   input: z.object({
     rootDir: z.string().optional().describe('Workspace root directory'),
-    saves: z
+    snapshots: z
       .number()
-      .default(DEFAULT_TOPO_SAVE_RETENTION)
-      .describe('Unpinned topo saves to retain'),
-    trackAgeMs: z
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
       .number()
       .default(7 * 24 * 60 * 60 * 1000)
-      .describe('Maximum retained track age in milliseconds'),
-    tracks: z.number().default(10_000).describe('Maximum retained track count'),
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
   }),
   intent: 'read',
   output: z.object({
@@ -48,16 +51,16 @@ export const devStatsTrail = trail('dev.stats', {
       path: z.string(),
     }),
     retention: z.object({
-      saves: z.number(),
-      trackAgeMs: z.number(),
-      tracks: z.number(),
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
     }),
     topo: z.object({
-      pinCount: z.number(),
-      prunableSaveCount: z.number(),
-      saveCount: z.number(),
+      pinnedCount: z.number(),
+      prunableSnapshotCount: z.number(),
+      snapshotCount: z.number(),
     }),
-    tracker: z.object({
+    tracing: z.object({
       recordCount: z.number(),
     }),
   }),

package/src/trails/dev-support.ts

@@ -2,30 +2,28 @@ import { existsSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
-  countPrunableTopoSaves,
-  countTopoPins,
-  countTopoSaves,
-  pruneUnpinnedTopoSaves,
-} from '@ontrails/core/internal/topo-saves';
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  pruneUnpinnedSnapshots,
+} from '@ontrails/core/internal/topo-snapshots';
 import {
   openReadTrailsDb,
   openWriteTrailsDb,
-  resolveTrailsDbPath,
-  resolveTrailsDir,
+  deriveTrailsDbPath,
+  deriveTrailsDir,
 } from '@ontrails/core/internal/trails-db';
 import {
   DEFAULT_MAX_AGE,
   DEFAULT_MAX_RECORDS,
-  applyTrackCleanup,
-  countTrackRecords,
-  previewTrackCleanup,
-} from '@ontrails/tracker/internal/dev-state';
+  applyTraceCleanup,
+  countTraceRecords,
+  previewTraceCleanup,
+} from '@ontrails/tracing/internal/dev-state';
 
-import { resolveLockPath } from './topo-support.js';
+export const DEFAULT_TOPO_SNAPSHOT_RETENTION = 50;
 
-export const DEFAULT_TOPO_SAVE_RETENTION = 50;
-
-const resolveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+const deriveRootDir = (cwd?: string): string => cwd ?? process.cwd();
 
 const removeIfPresent = (filePath: string): boolean => {
   if (!existsSync(filePath)) {
@@ -47,16 +45,16 @@ export interface DevStatsReport {
     readonly path: string;
   };
   readonly retention: {
-    readonly saves: number;
-    readonly trackAgeMs: number;
-    readonly tracks: number;
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
   };
   readonly topo: {
-    readonly pinCount: number;
-    readonly prunableSaveCount: number;
-    readonly saveCount: number;
+    readonly pinnedCount: number;
+    readonly prunableSnapshotCount: number;
+    readonly snapshotCount: number;
   };
-  readonly tracker: {
+  readonly tracing: {
     readonly recordCount: number;
   };
 }
@@ -64,18 +62,18 @@ export interface DevStatsReport {
 export interface DevCleanReport {
   readonly dryRun: boolean;
   readonly remaining: {
-    readonly pinCount: number;
-    readonly saveCount: number;
-    readonly trackCount: number;
+    readonly pinnedCount: number;
+    readonly snapshotCount: number;
+    readonly traceCount: number;
   };
   readonly removed: {
-    readonly topoSaves: number;
-    readonly trackRecords: number;
+    readonly topoSnapshots: number;
+    readonly traceRecords: number;
   };
   readonly retention: {
-    readonly saves: number;
-    readonly trackAgeMs: number;
-    readonly tracks: number;
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
   };
 }
 
@@ -89,7 +87,7 @@ interface DevRetentionOptions {
   readonly maxAge?: number;
   readonly maxRecords?: number;
   readonly rootDir?: string;
-  readonly saveRetention?: number;
+  readonly snapshotRetention?: number;
 }
 
 interface DevCleanupContext {
@@ -100,9 +98,9 @@ interface DevCleanupContext {
 }
 
 const buildRetention = (options?: DevRetentionOptions) => ({
-  saves: options?.saveRetention ?? DEFAULT_TOPO_SAVE_RETENTION,
-  trackAgeMs: options?.maxAge ?? DEFAULT_MAX_AGE,
-  tracks: options?.maxRecords ?? DEFAULT_MAX_RECORDS,
+  snapshots: options?.snapshotRetention ?? DEFAULT_TOPO_SNAPSHOT_RETENTION,
+  traceAgeMs: options?.maxAge ?? DEFAULT_MAX_AGE,
+  traces: options?.maxRecords ?? DEFAULT_MAX_RECORDS,
 });
 
 const emptyDevClean = (
@@ -111,13 +109,13 @@ const emptyDevClean = (
 ): DevCleanReport => ({
   dryRun,
   remaining: {
-    pinCount: 0,
-    saveCount: 0,
-    trackCount: 0,
+    pinnedCount: 0,
+    snapshotCount: 0,
+    traceCount: 0,
   },
   removed: {
-    topoSaves: 0,
-    trackRecords: 0,
+    topoSnapshots: 0,
+    traceRecords: 0,
   },
   retention,
 });
@@ -146,17 +144,17 @@ const emptyDevStats = (
   lock: buildLockStats(lockPath),
   retention,
   topo: {
-    pinCount: 0,
-    prunableSaveCount: 0,
-    saveCount: 0,
+    pinnedCount: 0,
+    prunableSnapshotCount: 0,
+    snapshotCount: 0,
   },
-  tracker: {
+  tracing: {
     recordCount: 0,
   },
 });
 
 const liveDevStats = (
-  db: Parameters<typeof countTopoPins>[0],
+  db: Parameters<typeof countPinnedSnapshots>[0],
   dbPath: string,
   lockPath: string,
   retention: DevStatsReport['retention']
@@ -165,20 +163,22 @@ const liveDevStats = (
   lock: buildLockStats(lockPath),
   retention,
   topo: {
-    pinCount: countTopoPins(db),
-    prunableSaveCount: countPrunableTopoSaves(db, { keep: retention.saves }),
-    saveCount: countTopoSaves(db),
+    pinnedCount: countPinnedSnapshots(db),
+    prunableSnapshotCount: countPrunableSnapshots(db, {
+      keep: retention.snapshots,
+    }),
+    snapshotCount: countTopoSnapshots(db),
   },
-  tracker: {
-    recordCount: countTrackRecords(db),
+  tracing: {
+    recordCount: countTraceRecords(db),
   },
 });
 
-const resolveDevStatsContext = (options?: DevRetentionOptions) => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const dbPath = resolveTrailsDbPath({ rootDir });
-  const trailsDir = resolveTrailsDir({ rootDir });
-  const lockPath = resolveLockPath(trailsDir);
+const deriveDevStatsContext = (options?: DevRetentionOptions) => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const dbPath = deriveTrailsDbPath({ rootDir });
+  const trailsDir = deriveTrailsDir({ rootDir });
+  const lockPath = join(trailsDir, 'trails.lock');
   return {
     dbExists: existsSync(dbPath),
     dbPath,
@@ -188,60 +188,62 @@ const resolveDevStatsContext = (options?: DevRetentionOptions) => {
   };
 };
 
-const resolveDevCleanupContext = (
+const deriveDevCleanupContext = (
   options?: DevRetentionOptions & { readonly dryRun?: boolean }
 ): DevCleanupContext => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   return {
-    dbPath: resolveTrailsDbPath({ rootDir }),
+    dbPath: deriveTrailsDbPath({ rootDir }),
     dryRun: options?.dryRun ?? false,
     retention: buildRetention(options),
     rootDir,
   };
 };
 
-const cleanupTracks = (
-  db: Parameters<typeof countTopoPins>[0],
+const cleanupTraces = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ) =>
   context.dryRun
-    ? previewTrackCleanup(db, {
-        maxAge: context.retention.trackAgeMs,
-        maxRecords: context.retention.tracks,
+    ? previewTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
       })
-    : applyTrackCleanup(db, {
-        maxAge: context.retention.trackAgeMs,
-        maxRecords: context.retention.tracks,
+    : applyTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
       });
 
-const cleanupTopoSaves = (
-  db: Parameters<typeof countTopoPins>[0],
+const cleanupTopoSnapshots = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ): number =>
   context.dryRun
-    ? countPrunableTopoSaves(db, { keep: context.retention.saves })
-    : pruneUnpinnedTopoSaves(db, { keep: context.retention.saves });
+    ? countPrunableSnapshots(db, { keep: context.retention.snapshots })
+    : pruneUnpinnedSnapshots(db, { keep: context.retention.snapshots });
 
 const buildCleanReport = (
-  db: Parameters<typeof countTopoPins>[0],
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ): DevCleanReport => {
-  const trackReport = cleanupTracks(db, context);
-  const topoRemoved = cleanupTopoSaves(db, context);
-  const saveCount = countTopoSaves(db);
+  const traceReport = cleanupTraces(db, context);
+  const topoRemoved = cleanupTopoSnapshots(db, context);
+  const snapshotCount = countTopoSnapshots(db);
 
   return {
     dryRun: context.dryRun,
     remaining: {
-      pinCount: countTopoPins(db),
-      saveCount: context.dryRun ? saveCount - topoRemoved : saveCount,
-      trackCount: context.dryRun
-        ? trackReport.remaining - trackReport.removedTotal
-        : trackReport.remaining,
+      pinnedCount: countPinnedSnapshots(db),
+      snapshotCount: context.dryRun
+        ? snapshotCount - topoRemoved
+        : snapshotCount,
+      traceCount: context.dryRun
+        ? traceReport.remaining - traceReport.removedTotal
+        : traceReport.remaining,
     },
     removed: {
-      topoSaves: topoRemoved,
-      trackRecords: trackReport.removedTotal,
+      topoSnapshots: topoRemoved,
+      traceRecords: traceReport.removedTotal,
     },
     retention: context.retention,
   };
@@ -251,9 +253,9 @@ const RESET_FILES = [
   '.trails/trails.db',
   '.trails/trails.db-shm',
   '.trails/trails.db-wal',
-  '.trails/dev/tracker.db',
-  '.trails/dev/tracker.db-shm',
-  '.trails/dev/tracker.db-wal',
+  '.trails/dev/tracing.db',
+  '.trails/dev/tracing.db-shm',
+  '.trails/dev/tracing.db-wal',
 ] as const;
 
 const presentResetFiles = (
@@ -265,7 +267,7 @@ export const buildDevStats = (
   options?: DevRetentionOptions
 ): DevStatsReport => {
   const { dbExists, dbPath, lockPath, retention, rootDir } =
-    resolveDevStatsContext(options);
+    deriveDevStatsContext(options);
 
   if (!dbExists) {
     return emptyDevStats(dbPath, lockPath, retention);
@@ -283,7 +285,7 @@ export const buildDevStats = (
 export const cleanDevState = (
   options?: DevRetentionOptions & { readonly dryRun?: boolean }
 ): DevCleanReport => {
-  const context = resolveDevCleanupContext(options);
+  const context = deriveDevCleanupContext(options);
   if (!existsSync(context.dbPath)) {
     return emptyDevClean(context.retention, context.dryRun);
   }
@@ -303,7 +305,7 @@ export const resetDevState = (options?: {
   readonly dryRun?: boolean;
   readonly rootDir?: string;
 }): DevResetReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const files = presentResetFiles(rootDir);
 
   if (options?.dryRun === true) {

package/src/trails/draft-promote.ts

@@ -4,10 +4,11 @@ import { basename, dirname, join, relative } from 'node:path';
 import {
   Result,
   ValidationError,
-  analyzeDraftState,
+  deriveDraftReport,
   isDraftId,
   trail,
 } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import {
   DRAFT_FILE_PREFIX,
   findStringLiterals,
@@ -17,7 +18,7 @@ import {
 } from '@ontrails/warden';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { loadFreshAppLease } from './load-app.js';
 import { findTopoPath } from './project.js';
 
 interface PromotionEdit {
@@ -164,10 +165,8 @@ const replaceLiteralValue = (
   };
 };
 
-const collectOutputId = (
-  app: Awaited<ReturnType<typeof loadApp>>,
-  id: string
-) => app.get(id) ?? app.signals.get(id) ?? app.getProvision(id);
+const collectOutputId = (app: Topo, id: string) =>
+  app.get(id) ?? app.signals.get(id) ?? app.getResource(id);
 
 const toRelativeOutputPath = (rootDir: string, filePath: string): string =>
   relative(rootDir, filePath).replaceAll('\\', '/');
@@ -185,7 +184,6 @@ interface PromotionRewriteState {
 interface PromotionLoadState {
   readonly appModule: string | null;
   readonly loadError: string | null;
-  readonly loadedApp: Awaited<ReturnType<typeof loadApp>> | undefined;
 }
 
 const validatePromotionInput = (input: {
@@ -511,23 +509,56 @@ const resolvePromotionAppModule = async (
   );
 };
 
-const loadVerifiedApp = async (
-  appModule: string | null,
+/**
+ * Run `consume` while holding a fresh-load lease on `appModule`.
+ *
+ * @remarks
+ * The lease deletes its on-disk mirror on release. Any Topo consumption that
+ * may trigger deferred filesystem imports (for example inside a trail's
+ * `blaze` or a lazy relative `import()`) must run before the lease is
+ * released, otherwise those resolutions race the mirror teardown. Collapsing
+ * consumption into the leased critical section keeps that contract
+ * structural rather than relying on the caller to discover it.
+ */
+type LeaseAttempt =
+  | {
+      readonly ok: true;
+      readonly lease: Awaited<ReturnType<typeof loadFreshAppLease>>;
+    }
+  | { readonly ok: false; readonly loadError: string };
+
+const tryAcquireLease = async (
+  appModule: string,
   rootDir: string
-): Promise<PromotionLoadState> => {
+): Promise<LeaseAttempt> => {
+  try {
+    return { lease: await loadFreshAppLease(appModule, rootDir), ok: true };
+  } catch (error) {
+    const loadError = error instanceof Error ? error.message : String(error);
+    return { loadError, ok: false };
+  }
+};
+
+const withVerifiedApp = async <T>(
+  appModule: string | null,
+  rootDir: string,
+  consume: (app: Topo) => T | Promise<T>
+): Promise<{ readonly load: PromotionLoadState; readonly value: T | null }> => {
   if (appModule === null) {
-    return { appModule, loadError: null, loadedApp: undefined };
+    return { load: { appModule, loadError: null }, value: null };
   }
 
-  let loadError: string | null = null;
-  const loadedApp = await loadApp(appModule, rootDir, { fresh: true }).catch(
-    (error: unknown): undefined => {
-      loadError = error instanceof Error ? error.message : String(error);
-      return undefined;
-    }
-  );
+  const attempt = await tryAcquireLease(appModule, rootDir);
+  if (!attempt.ok) {
+    return { load: { appModule, loadError: attempt.loadError }, value: null };
+  }
 
-  return { appModule, loadError, loadedApp };
+  try {
+    const value = await consume(attempt.lease.app);
+    return { load: { appModule, loadError: null }, value };
+  } finally {
+    attempt.lease.release();
+  }
 };
 
 const toRenamedFiles = (rootDir: string, renames: readonly FileRename[]) =>
@@ -562,7 +593,7 @@ const buildUnverifiedPromotionResult = (
 
 const buildVerifiedPromotionResult = (
   rootDir: string,
-  analysis: ReturnType<typeof analyzeDraftState>,
+  analysis: ReturnType<typeof deriveDraftReport>,
   promotedEstablished: boolean,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
@@ -589,13 +620,13 @@ const buildVerifiedPromotionResult = (
 
 const buildVerifiedPromotionResultFromApp = (
   rootDir: string,
-  loadedApp: Awaited<ReturnType<typeof loadApp>>,
+  loadedApp: Topo,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
   appModule: string | null,
   toId: string
 ) => {
-  const analysis = analyzeDraftState(loadedApp);
+  const analysis = deriveDraftReport(loadedApp);
   const promotedNode = collectOutputId(loadedApp, toId);
   const promotedEstablished =
     promotedNode !== undefined && !analysis.contaminatedIds.has(toId);
@@ -633,13 +664,11 @@ const promoteDraftState = async (
 
   const { renames, updatedSourceFiles } = rewriteResult.value;
   const appModule = await resolvePromotionAppModule(input, rootDirResult.value);
-  const { loadError, loadedApp } = await loadVerifiedApp(
+  const { load, value } = await withVerifiedApp(
     appModule,
-    rootDirResult.value
-  );
-
-  return loadedApp
-    ? buildVerifiedPromotionResultFromApp(
+    rootDirResult.value,
+    (loadedApp) =>
+      buildVerifiedPromotionResultFromApp(
         rootDirResult.value,
         loadedApp,
         renames,
@@ -647,13 +676,18 @@ const promoteDraftState = async (
         appModule,
         input.toId
       )
-    : buildUnverifiedPromotionResult(
-        rootDirResult.value,
-        loadError,
-        renames,
-        updatedSourceFiles,
-        appModule
-      );
+  );
+
+  return (
+    value ??
+    buildUnverifiedPromotionResult(
+      rootDirResult.value,
+      load.loadError,
+      renames,
+      updatedSourceFiles,
+      appModule
+    )
+  );
 };
 
 export const draftPromoteTrail = trail('draft.promote', {
@@ -664,6 +698,7 @@ export const draftPromoteTrail = trail('draft.promote', {
     {
       error: 'ValidationError',
       input: {
+        // warden-ignore-next-line
         fromId: '_draft.entity.prepare',
         renameFiles: true,
         rootDir: './__does_not_exist__/draft-promote-example',

package/src/trails/guide.ts

@@ -62,10 +62,7 @@ export const guideTrail = trail('guide', {
     },
   ],
   input: z.object({
-    module: z
-      .string()
-      .default('./src/app.ts')
-      .describe('Path to the app module'),
+    module: z.string().optional().describe('Path to the app module'),
     trailId: z.string().optional().describe('Trail ID for detailed guidance'),
   }),
   intent: 'read',