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

package/src/trails/topo-pin.ts

@@ -1,42 +1,51 @@
 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 {
-  DEFAULT_APP_MODULE,
-  isolatedExampleInput,
-  pinCurrentTopo,
-  topoPinOutput,
-  topoSaveOutput,
+  createIsolatedExampleInput,
+  pinCurrentTopoSnapshot,
+  topoSnapshotOutput,
 } from './topo-support.js';
 
 export const topoPinTrail = trail('topo.pin', {
   blaze: async (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    const app = await loadApp(input.module, rootDir);
-    return Result.ok(pinCurrentTopo(app, { name: input.name, 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 Result.ok(
+        pinCurrentTopoSnapshot(lease.app, { name: input.name, rootDir })
+      );
+    } finally {
+      lease.release();
+    }
   },
   description: 'Pin the current topo under a durable name',
   examples: [
     {
       input: {
-        ...isolatedExampleInput('topo-pin'),
+        ...createIsolatedExampleInput('topo-pin'),
         name: 'before-auth-refactor',
       },
       name: 'Pin 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'),
     name: z.string().describe('Pin name'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'write',
   output: z.object({
-    pin: topoPinOutput,
-    save: topoSaveOutput,
+    snapshot: topoSnapshotOutput,
   }),
 });

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

@@ -1,212 +1,91 @@
 /**
- * Read-only topo store consumer helpers.
+ * Read-only live topo consumer helpers.
  *
- * Extracted from topo-support.ts so this branch (trl-132) owns its own file,
- * keeping absorb routing clean across the stack.
+ * Extracted from topo-support.ts to isolate read-only topo consumer helpers,
+ * keeping module boundaries clean.
  */
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import type { Topo } from '@ontrails/core';
+import type { Topo, TrailContext } from '@ontrails/core';
 import {
   ConflictError,
-  createTopoStore,
-  InternalError,
+  deriveTrailsDbPath,
+  deriveTrailsDir,
   NotFoundError,
   Result,
+  SURFACE_LAYER_NAMES_KEY,
+  ValidationError,
 } from '@ontrails/core';
-import type { TopoSaveRecord } from '@ontrails/core/internal/topo-saves';
-import { listTopoSaves } from '@ontrails/core/internal/topo-saves';
+import { deriveTopoGraph, readLockManifest } from '@ontrails/topographer';
+
+import type {
+  BriefReport,
+  SignalDetailReport,
+  SurfaceLayerNames,
+  SurveyListReport,
+  TrailDetailReport,
+} from './topo-reports.js';
 import {
-  openReadTrailsDb,
-  resolveTrailsDbPath,
-  resolveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
-import { readTrailheadLockData } from '@ontrails/schema';
-
-import type { BriefReport, SurveyListReport } from './topo-reports.js';
+  deriveBriefReport,
+  deriveResourceDetail,
+  deriveSignalDetail,
+  deriveSurveyList,
+  deriveTrailDetail,
+} from './topo-reports.js';
+import type { ActivationGraphReport } from './topo-activation.js';
+import { deriveActivationGraph } from './topo-activation.js';
 import type { TopoSummaryReport, TopoVerifyReport } from './topo-support.js';
-import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
-import {
-  createCurrentTopoSave,
-  LOCK_PATH,
-  resolveRootDir,
-} from './topo-support.js';
-
-// ---------------------------------------------------------------------------
-// Internal types
-// ---------------------------------------------------------------------------
+import { deriveRootDir, LOCK_PATH } from './topo-support.js';
+import { deriveCurrentTopoExport } from './topo-store-support.js';
 
-interface StoredTrailheadMapEntry {
-  readonly detours?: Readonly<Record<string, readonly string[]>>;
-  readonly kind: 'provision' | 'signal' | 'trail';
-}
-
-interface CurrentTrailDetail {
-  readonly crosses: string[];
-  readonly description: string | null;
-  readonly detours: Readonly<Record<string, readonly string[]>> | null;
-  readonly examples: unknown[];
-  readonly id: string;
-  readonly intent: 'destroy' | 'read' | 'write';
-  readonly kind: string;
-  readonly provisions: string[];
-  readonly safety: string;
-}
+export type CurrentTrailDetail = TrailDetailReport;
 
-interface CurrentProvisionDetail {
+export interface CurrentResourceDetail {
   readonly description: string | null;
   readonly health: 'available' | 'none';
   readonly id: string;
-  readonly kind: 'provision';
+  readonly kind: 'resource';
   readonly lifetime: 'singleton';
-  readonly usedBy: string[];
+  readonly usedBy: readonly string[];
 }
 
-// ---------------------------------------------------------------------------
-// Store helpers
-// ---------------------------------------------------------------------------
-
-const topoStoreRef = (saveId: string) => ({ saveId }) as const;
-
-const hasCommittedLock = (trailsDir: string): boolean =>
-  existsSync(join(trailsDir, 'trails.lock')) ||
-  existsSync(join(trailsDir, 'trailhead.lock'));
+export type CurrentTopoDetail =
+  | CurrentResourceDetail
+  | CurrentTrailDetail
+  | SignalDetailReport;
 
-const readTrailheadEntries = (
-  trailheadMapJson: string
-): readonly StoredTrailheadMapEntry[] =>
-  (
-    JSON.parse(trailheadMapJson) as {
-      readonly entries: readonly StoredTrailheadMapEntry[];
-    }
-  ).entries;
-
-const buildBriefReportFromStore = (
-  app: Topo,
-  store: ReturnType<typeof createTopoStore>,
-  ref: ReturnType<typeof topoStoreRef>,
-  save: TopoSaveRecord
-): BriefReport => {
-  const trails = store.trails.list({ save: ref });
-  const exportRecord = store.exports.get(ref);
-  const trailEntries =
-    exportRecord === undefined
-      ? []
-      : readTrailheadEntries(exportRecord.trailheadMapJson).filter(
-          (entry) => entry.kind === 'trail'
-        );
+export interface CurrentTopoMatch {
+  readonly kind: CurrentTopoDetail['kind'];
+  readonly detail: CurrentTopoDetail;
+}
 
-  return {
-    contractVersion: REPORT_CONTRACT_VERSION,
-    features: {
-      detours: trailEntries.some(
-        (entry) => (Object.keys(entry.detours ?? {}).length ?? 0) > 0
-      ),
-      examples: trails.some((trail) => trail.hasExamples),
-      outputSchemas: trails.some((trail) => trail.hasOutput),
-      provisions: save.provisionCount > 0,
-      signals: save.signalCount > 0,
-    },
-    name: app.name,
-    provisions: save.provisionCount,
-    signals: save.signalCount,
-    trails: save.trailCount,
-    version: REPORT_VERSION,
-  };
-};
+export interface CurrentTopoReadOptions {
+  readonly rootDir?: string | undefined;
+  readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
+}
 
-const buildSurveyListFromStore = (
-  store: ReturnType<typeof createTopoStore>,
-  ref: ReturnType<typeof topoStoreRef>
-): SurveyListReport => {
-  const trails = store.trails.list({ save: ref });
-  const provisions = store.provisions.list({ save: ref });
+const isStringArray = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
 
+export const readSurfaceLayerNamesFromContext = (
+  ctx: TrailContext
+): Partial<SurfaceLayerNames> => {
+  const value = ctx.extensions?.[SURFACE_LAYER_NAMES_KEY];
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  const raw = value as Record<string, unknown>;
   return {
-    count: trails.length,
-    entries: trails.map((trail) => ({
-      examples: trail.exampleCount,
-      id: trail.id,
-      kind: trail.kind,
-      safety: trail.safety,
-    })),
-    provisionCount: provisions.length,
-    provisions: provisions.map((provision) => ({
-      description: provision.description,
-      health: provision.health,
-      id: provision.id,
-      kind: provision.kind,
-      lifetime: provision.lifetime,
-      usedBy: provision.usedBy,
-    })),
+    ...(isStringArray(raw['cli']) ? { cli: raw['cli'] } : {}),
+    ...(isStringArray(raw['http']) ? { http: raw['http'] } : {}),
+    ...(isStringArray(raw['mcp']) ? { mcp: raw['mcp'] } : {}),
   };
 };
 
-const buildTrailDetailFromStore = (
-  detail: ReturnType<ReturnType<typeof createTopoStore>['trails']['get']>
-): CurrentTrailDetail => ({
-  crosses: [...(detail?.crosses ?? [])],
-  description: detail?.description ?? null,
-  detours: detail?.detours ?? null,
-  examples: [...(detail?.examples ?? [])],
-  id: detail?.id ?? '',
-  intent: detail?.intent ?? 'write',
-  kind: detail?.kind ?? 'trail',
-  provisions: [...(detail?.provisions ?? [])],
-  safety: detail?.safety ?? '-',
-});
-
-const buildProvisionDetailFromStore = (
-  provision: NonNullable<
-    ReturnType<ReturnType<typeof createTopoStore>['provisions']['get']>
-  >
-): CurrentProvisionDetail => ({
-  description: provision.description,
-  health: provision.health,
-  id: provision.id,
-  kind: provision.kind,
-  lifetime: provision.lifetime,
-  usedBy: [...provision.usedBy],
-});
-
-// ---------------------------------------------------------------------------
-// withCurrentTopoStore
-// ---------------------------------------------------------------------------
-
-/**
- * Run a read callback against the latest topo store state.
- *
- * Uses the most recent existing save when available, only creating a new save
- * when no prior save exists. This avoids unbounded save accumulation from
- * read-only operations like survey, guide, and show.
- */
-const withCurrentTopoStore = <T>(
-  app: Topo,
-  rootDir: string,
-  read: (
-    store: ReturnType<typeof createTopoStore>,
-    ref: ReturnType<typeof topoStoreRef>,
-    save: TopoSaveRecord
-  ) => T
-): T => {
-  const dbPath = resolveTrailsDbPath({ rootDir });
-  const existingSave = existsSync(dbPath)
-    ? (() => {
-        const db = openReadTrailsDb({ rootDir });
-        try {
-          return listTopoSaves(db)[0];
-        } finally {
-          db.close();
-        }
-      })()
-    : undefined;
-
-  const save = existingSave ?? createCurrentTopoSave(app, { rootDir });
-  const store = createTopoStore({ rootDir });
-  return read(store, topoStoreRef(save.id), save);
-};
+const hasCommittedLock = (trailsDir: string): boolean =>
+  existsSync(join(trailsDir, 'trails.lock'));
 
 // ---------------------------------------------------------------------------
 // Public read-only consumers
@@ -216,115 +95,176 @@ export const buildTopoSummary = (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): TopoSummaryReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const trailsDir = resolveTrailsDir({ rootDir });
-  return withCurrentTopoStore(app, rootDir, (store, ref, save) => ({
-    app: buildBriefReportFromStore(app, store, ref, save),
-    dbPath: resolveTrailsDbPath({ rootDir }),
-    list: buildSurveyListFromStore(store, ref),
+  const rootDir = deriveRootDir(options?.rootDir);
+  const trailsDir = deriveTrailsDir({ rootDir });
+  return {
+    app: deriveBriefReport(app),
+    dbPath: deriveTrailsDbPath({ rootDir }),
+    list: deriveSurveyList(app),
     lockExists: hasCommittedLock(trailsDir),
     lockPath: LOCK_PATH,
-  }));
+  };
 };
 
 export const buildCurrentTopoBrief = (
   app: Topo,
-  options?: { readonly rootDir?: string }
-): BriefReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref, save) =>
-    buildBriefReportFromStore(app, store, ref, save)
-  );
-};
+  _options?: { readonly rootDir?: string }
+): BriefReport => deriveBriefReport(app);
 
 export const buildCurrentTopoList = (
   app: Topo,
-  options?: { readonly rootDir?: string }
-): SurveyListReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref) =>
-    buildSurveyListFromStore(store, ref)
-  );
-};
+  _options?: { readonly rootDir?: string }
+): SurveyListReport => deriveSurveyList(app);
 
 export const buildCurrentGuideEntries = (
   app: Topo,
-  options?: { readonly rootDir?: string }
+  _options?: { readonly rootDir?: string }
 ): readonly {
   readonly description: string;
   readonly exampleCount: number;
   readonly id: string;
-  readonly kind: string;
-}[] => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref) =>
-    store.trails.list({ save: ref }).map((trail) => ({
+  readonly kind: 'trail';
+}[] =>
+  app
+    .list()
+    .map((trail) => ({
       description: trail.description ?? '(no description)',
-      exampleCount: trail.exampleCount,
+      exampleCount: trail.examples?.length ?? 0,
       id: trail.id,
-      kind: trail.kind,
+      kind: 'trail' as const,
     }))
-  );
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+
+export const buildCurrentTrailDetail = (
+  app: Topo,
+  id: string,
+  options?: CurrentTopoReadOptions
+): CurrentTrailDetail | undefined => {
+  const trail = app.get(id);
+  return trail === undefined
+    ? undefined
+    : deriveTrailDetail(trail, app, undefined, {
+        surfaceLayerNames: options?.surfaceLayerNames,
+      });
 };
 
+export const buildCurrentResourceDetail = (
+  app: Topo,
+  id: string,
+  _options?: { readonly rootDir?: string }
+): CurrentResourceDetail | undefined =>
+  app.getResource(id) === undefined
+    ? undefined
+    : (deriveResourceDetail(app, id) as CurrentResourceDetail);
+
+export const buildCurrentSignalDetail = (
+  app: Topo,
+  id: string,
+  _options?: { readonly rootDir?: string }
+): SignalDetailReport | undefined => deriveSignalDetail(app, id);
+
 export const buildCurrentTopoDetail = (
   app: Topo,
   id: string,
-  options?: { readonly rootDir?: string }
-): CurrentProvisionDetail | CurrentTrailDetail | undefined => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref) => {
-    const trail = store.trails.get(id, { save: ref });
-    if (trail !== undefined) {
-      return buildTrailDetailFromStore(trail);
-    }
+  options?: CurrentTopoReadOptions
+): CurrentTopoDetail | undefined =>
+  buildCurrentTrailDetail(app, id, options) ??
+  buildCurrentResourceDetail(app, id) ??
+  buildCurrentSignalDetail(app, id);
 
-    const provision = store.provisions.get(id, { save: ref });
-    return provision === undefined
-      ? undefined
-      : buildProvisionDetailFromStore(provision);
-  });
+export const buildCurrentTopoMatches = (
+  app: Topo,
+  id: string,
+  options?: CurrentTopoReadOptions
+): readonly CurrentTopoMatch[] => {
+  const matches: CurrentTopoMatch[] = [];
+  let activationGraph: ActivationGraphReport | undefined;
+  const getActivationGraph = (): ActivationGraphReport =>
+    (activationGraph ??= deriveActivationGraph(app));
+  let topoGraph: ReturnType<typeof deriveTopoGraph> | undefined;
+  const getTopoGraph = (): ReturnType<typeof deriveTopoGraph> =>
+    (topoGraph ??= deriveTopoGraph(app));
+
+  const trail = app.get(id);
+  if (trail !== undefined) {
+    matches.push({
+      detail: deriveTrailDetail(trail, app, getActivationGraph(), {
+        surfaceLayerNames: options?.surfaceLayerNames,
+        topoGraph: getTopoGraph(),
+      }),
+      kind: 'trail',
+    });
+  }
+
+  const resource = buildCurrentResourceDetail(app, id);
+  if (resource !== undefined) {
+    matches.push({ detail: resource, kind: 'resource' });
+  }
+
+  const signal = deriveSignalDetail(app, id, activationGraph);
+  if (signal !== undefined) {
+    matches.push({ detail: signal, kind: 'signal' });
+  }
+
+  return matches;
 };
 
 export const verifyCurrentTopo = async (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): Promise<Result<TopoVerifyReport, Error>> => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const committedLock = await readTrailheadLockData({
-    dir: resolveTrailsDir({ rootDir }),
-  });
+  const rootDir = deriveRootDir(options?.rootDir);
+  let lockManifest: Awaited<ReturnType<typeof readLockManifest>>;
+  try {
+    lockManifest = await readLockManifest({
+      dir: deriveTrailsDir({ rootDir }),
+    });
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : 'Unable to read committed trails.lock manifest.';
+    return Result.err(
+      error instanceof Error
+        ? new ValidationError(message, { cause: error })
+        : new ValidationError(message)
+    );
+  }
 
-  if (committedLock === null) {
+  if (lockManifest === null) {
     return Result.err(
       new NotFoundError(
-        'No committed trails.lock found. Run `trails topo export` first.'
+        'No committed trails.lock found. Run `trails topo compile` first.'
       )
     );
   }
 
-  const currentHash = withCurrentTopoStore(
-    app,
-    rootDir,
-    (store, ref) => store.exports.get(ref)?.trailheadHash
+  const currentExport = deriveCurrentTopoExport(app, { rootDir });
+  if (currentExport.isErr()) {
+    return currentExport;
+  }
+  const currentHash = currentExport.value.topoGraphHash;
+  const topoArtifact = lockManifest.artifacts.find(
+    (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
   );
-
-  if (currentHash === undefined) {
+  if (topoArtifact === undefined) {
     return Result.err(
-      new InternalError('No stored topo export found for the current topo save')
+      new NotFoundError(
+        'No topo.lock artifact found in trails.lock. Run `trails topo compile` first.'
+      )
     );
   }
 
-  if (committedLock.hash !== currentHash) {
+  if (topoArtifact.sha256 !== currentHash) {
     return Result.err(
       new ConflictError(
-        'trails.lock is stale. Run `trails topo export` to refresh it.'
+        'trails.lock is stale. Run `trails topo compile` to refresh it.'
       )
     );
   }
 
   return Result.ok({
-    committedHash: committedLock.hash,
+    committedHash: topoArtifact.sha256,
     currentHash,
     lockPath: LOCK_PATH,
     stale: false,