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

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

@@ -1,207 +1,91 @@
 /**
- * Read-only topo store consumer helpers.
+ * Read-only live topo consumer helpers.
  *
- * Extracted from topo-support.ts to isolate read-only store consumer helpers,
+ * 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, TrailContext } from '@ontrails/core';
 import {
   ConflictError,
-  createTopoStore,
-  InternalError,
-  listTopoSnapshots,
+  deriveTrailsDbPath,
+  deriveTrailsDir,
   NotFoundError,
   Result,
+  SURFACE_LAYER_NAMES_KEY,
+  ValidationError,
 } from '@ontrails/core';
-import type { Topo, TopoSnapshot } from '@ontrails/core';
+import { deriveTopoGraph, readLockManifest } from '@ontrails/topographer';
+
+import type {
+  BriefReport,
+  SignalDetailReport,
+  SurfaceLayerNames,
+  SurveyListReport,
+  TrailDetailReport,
+} from './topo-reports.js';
 import {
-  deriveTrailsDbPath,
-  deriveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
-import { readSurfaceLockData } 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 {
-  createCurrentTopoSnapshot,
-  deriveRootDir,
-  LOCK_PATH,
-} from './topo-support.js';
+import { deriveRootDir, LOCK_PATH } from './topo-support.js';
+import { deriveCurrentTopoExport } from './topo-store-support.js';
 
-// ---------------------------------------------------------------------------
-// Internal types
-// ---------------------------------------------------------------------------
+export type CurrentTrailDetail = TrailDetailReport;
 
-interface StoredSurfaceMapEntry {
-  readonly detours?: readonly {
-    readonly on: string;
-    readonly maxAttempts: number;
-  }[];
-  readonly kind: 'resource' | 'signal' | 'trail';
-}
-
-interface CurrentTrailDetail {
-  readonly crosses: string[];
-  readonly description: string | null;
-  readonly detours:
-    | readonly { readonly on: string; readonly maxAttempts: number }[]
-    | null;
-  readonly examples: unknown[];
-  readonly id: string;
-  readonly intent: 'destroy' | 'read' | 'write';
-  readonly kind: string;
-  readonly pattern: string | null;
-  readonly resources: string[];
-  readonly safety: string;
-}
-
-interface CurrentResourceDetail {
+export interface CurrentResourceDetail {
   readonly description: string | null;
   readonly health: 'available' | 'none';
   readonly id: string;
   readonly kind: 'resource';
   readonly lifetime: 'singleton';
-  readonly usedBy: string[];
+  readonly usedBy: readonly string[];
 }
 
-// ---------------------------------------------------------------------------
-// Store helpers
-// ---------------------------------------------------------------------------
-
-const topoStoreRef = (snapshotId: string) => ({ snapshotId }) as const;
-
-const hasCommittedLock = (trailsDir: string): boolean =>
-  existsSync(join(trailsDir, 'trails.lock'));
-
-const readSurfaceEntries = (
-  surfaceMapJson: string
-): readonly StoredSurfaceMapEntry[] =>
-  (
-    JSON.parse(surfaceMapJson) as {
-      readonly entries: readonly StoredSurfaceMapEntry[];
-    }
-  ).entries;
+export type CurrentTopoDetail =
+  | CurrentResourceDetail
+  | CurrentTrailDetail
+  | SignalDetailReport;
 
-const buildBriefReportFromStore = (
-  app: Topo,
-  store: ReturnType<typeof createTopoStore>,
-  ref: ReturnType<typeof topoStoreRef>,
-  snapshot: TopoSnapshot
-): BriefReport => {
-  const trails = store.trails.list({ snapshot: ref });
-  const exportRecord = store.exports.get(ref);
-  const trailEntries =
-    exportRecord === undefined
-      ? []
-      : readSurfaceEntries(exportRecord.surfaceMapJson).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) => (entry.detours ?? []).length > 0),
-      examples: trails.some((trail) => trail.hasExamples),
-      outputSchemas: trails.some((trail) => trail.hasOutput),
-      resources: snapshot.resourceCount > 0,
-      signals: snapshot.signalCount > 0,
-    },
-    name: app.name,
-    resources: snapshot.resourceCount,
-    signals: snapshot.signalCount,
-    trails: snapshot.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({ snapshot: ref });
-  const resources = store.resources.list({ snapshot: 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,
-    })),
-    resourceCount: resources.length,
-    resources: resources.map((resource) => ({
-      description: resource.description,
-      health: resource.health,
-      id: resource.id,
-      kind: resource.kind,
-      lifetime: resource.lifetime,
-      usedBy: resource.usedBy,
-    })),
+    ...(isStringArray(raw['cli']) ? { cli: raw['cli'] } : {}),
+    ...(isStringArray(raw['http']) ? { http: raw['http'] } : {}),
+    ...(isStringArray(raw['mcp']) ? { mcp: raw['mcp'] } : {}),
   };
 };
 
-const buildTrailDetailFromStore = (
-  detail: NonNullable<
-    ReturnType<ReturnType<typeof createTopoStore>['trails']['get']>
-  >
-): CurrentTrailDetail => ({
-  crosses: [...detail.crosses],
-  description: detail.description,
-  detours: detail.detours,
-  examples: [...detail.examples],
-  id: detail.id,
-  intent: detail.intent,
-  kind: detail.kind,
-  pattern: detail.pattern,
-  resources: [...detail.resources],
-  safety: detail.safety,
-});
-
-const buildResourceDetailFromStore = (
-  resource: NonNullable<
-    ReturnType<ReturnType<typeof createTopoStore>['resources']['get']>
-  >
-): CurrentResourceDetail => ({
-  description: resource.description,
-  health: resource.health,
-  id: resource.id,
-  kind: resource.kind,
-  lifetime: resource.lifetime,
-  usedBy: [...resource.usedBy],
-});
-
-// ---------------------------------------------------------------------------
-// withCurrentTopoStore
-// ---------------------------------------------------------------------------
-
-/**
- * Run a read callback against the latest topo store state.
- *
- * Uses the most recent existing snapshot when available, only creating a new
- * snapshot when no prior snapshot exists. This avoids unbounded snapshot
- * 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>,
-    snapshot: TopoSnapshot
-  ) => T
-): T => {
-  const [existingSnapshot] = listTopoSnapshots({ limit: 1, rootDir });
-  const snapshot =
-    existingSnapshot ?? createCurrentTopoSnapshot(app, { rootDir });
-  const store = createTopoStore({ rootDir });
-  return read(store, topoStoreRef(snapshot.id), snapshot);
-};
+const hasCommittedLock = (trailsDir: string): boolean =>
+  existsSync(join(trailsDir, 'trails.lock'));
 
 // ---------------------------------------------------------------------------
 // Public read-only consumers
@@ -213,72 +97,116 @@ export const buildTopoSummary = (
 ): TopoSummaryReport => {
   const rootDir = deriveRootDir(options?.rootDir);
   const trailsDir = deriveTrailsDir({ rootDir });
-  return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) => ({
-    app: buildBriefReportFromStore(app, store, ref, snapshot),
+  return {
+    app: deriveBriefReport(app),
     dbPath: deriveTrailsDbPath({ rootDir }),
-    list: buildSurveyListFromStore(store, ref),
+    list: deriveSurveyList(app),
     lockExists: hasCommittedLock(trailsDir),
     lockPath: LOCK_PATH,
-  }));
+  };
 };
 
 export const buildCurrentTopoBrief = (
   app: Topo,
-  options?: { readonly rootDir?: string }
-): BriefReport => {
-  const rootDir = deriveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) =>
-    buildBriefReportFromStore(app, store, ref, snapshot)
-  );
-};
+  _options?: { readonly rootDir?: string }
+): BriefReport => deriveBriefReport(app);
 
 export const buildCurrentTopoList = (
   app: Topo,
-  options?: { readonly rootDir?: string }
-): SurveyListReport => {
-  const rootDir = deriveRootDir(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 = deriveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref) =>
-    store.trails.list({ snapshot: 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 }
-): CurrentResourceDetail | CurrentTrailDetail | undefined => {
-  const rootDir = deriveRootDir(options?.rootDir);
-  return withCurrentTopoStore(app, rootDir, (store, ref) => {
-    const trail = store.trails.get(id, { snapshot: ref });
-    if (trail !== undefined) {
-      return buildTrailDetailFromStore(trail);
-    }
+  options?: CurrentTopoReadOptions
+): CurrentTopoDetail | undefined =>
+  buildCurrentTrailDetail(app, id, options) ??
+  buildCurrentResourceDetail(app, id) ??
+  buildCurrentSignalDetail(app, id);
 
-    const resource = store.resources.get(id, { snapshot: ref });
-    return resource === undefined
-      ? undefined
-      : buildResourceDetailFromStore(resource);
-  });
+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 (
@@ -286,42 +214,57 @@ export const verifyCurrentTopo = async (
   options?: { readonly rootDir?: string }
 ): Promise<Result<TopoVerifyReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
-  const committedLock = await readSurfaceLockData({
-    dir: deriveTrailsDir({ 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)?.surfaceHash
+  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 snapshot'
+      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,