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

package/src/trails/topo-reports.ts

@@ -1,26 +1,84 @@
-import type { Topo, Trail } from '@ontrails/core';
+import { DETOUR_MAX_ATTEMPTS_CAP, zodToJsonSchema } from '@ontrails/core';
+import type { AnyTrail, Signal, Topo } from '@ontrails/core';
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type {
+  JsonSchema,
+  TopoGraph,
+  TopoGraphActivationEdge,
+  TopoGraphEntry,
+  TopoGraphFieldOverride,
+  TopoGraphLayerReference,
+} from '@ontrails/topographer';
+import { z } from 'zod';
 
+import type {
+  ActivationChainReport,
+  ActivationEdgeReport,
+  ActivationGraphReport,
+  ActivationOverviewReport,
+  ActivationSourceReport,
+  SignalActivationRelations,
+} from './topo-activation.js';
+import {
+  deriveActivationGraph,
+  deriveDeclaredTrailActivation,
+  deriveSignalActivationRelations,
+} from './topo-activation.js';
 import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
 
-export interface BriefReport {
-  readonly name: string;
-  readonly version: string;
-  readonly contractVersion: string;
-  readonly features: {
-    readonly resources: boolean;
-    readonly outputSchemas: boolean;
-    readonly examples: boolean;
-    readonly detours: boolean;
-    readonly signals: boolean;
-  };
-  readonly trails: number;
-  readonly signals: number;
-  readonly resources: number;
+export type {
+  ActivationChainReport,
+  ActivationEdgeReport,
+  ActivationGraphReport,
+  ActivationOverviewReport,
+  ActivationSourceReport,
+  SignalActivationRelations,
+  TrailActivationReport,
+} from './topo-activation.js';
+
+export const briefReportSchema = z.object({
+  contractVersion: z.string(),
+  features: z.object({
+    detours: z.boolean(),
+    examples: z.boolean(),
+    outputSchemas: z.boolean(),
+    resources: z.boolean(),
+    signals: z.boolean(),
+  }),
+  name: z.string(),
+  resources: z.number(),
+  signals: z.number(),
+  trails: z.number(),
+  version: z.string(),
+});
+
+type BriefReportShape = z.infer<typeof briefReportSchema>;
+
+export type BriefReport = Readonly<
+  Omit<BriefReportShape, 'features'> & {
+    readonly features: Readonly<BriefReportShape['features']>;
+  }
+>;
+
+export type SurfaceLayerKey = 'cli' | 'http' | 'mcp';
+
+export type SurfaceLayerNames = Readonly<
+  Record<SurfaceLayerKey, readonly string[]>
+>;
+
+type TopoGraphContourEntry = TopoGraphEntry & { readonly kind: 'contour' };
+
+export interface TrailDetailOptions {
+  readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
+  readonly topoGraph?: TopoGraph | undefined;
 }
 
 export interface SurveyListReport {
+  readonly activation: ActivationOverviewReport;
   readonly count: number;
   readonly entries: readonly {
+    readonly activatedBy: readonly string[];
+    readonly activates: readonly string[];
     readonly examples: number;
     readonly id: string;
     readonly kind: string;
@@ -35,21 +93,93 @@ export interface SurveyListReport {
     readonly lifetime: 'singleton';
     readonly usedBy: readonly string[];
   }[];
+  readonly signalCount: number;
+  readonly signals: readonly {
+    readonly consumers: readonly string[];
+    readonly description: string | null;
+    readonly examples: number;
+    readonly from: readonly string[];
+    readonly id: string;
+    readonly kind: 'signal';
+    readonly payloadSchema: boolean;
+    readonly producers: readonly string[];
+  }[];
 }
 
 export interface TrailDetailReport {
+  readonly activatedBy: readonly string[];
+  readonly activates: readonly string[];
+  readonly activationChains: readonly ActivationChainReport[];
+  readonly activationContext: {
+    readonly edgeCount: number;
+    readonly sourceCount: number;
+    readonly sourceKeys: readonly string[];
+    readonly trailIds: readonly string[];
+  };
+  readonly activationEdges: readonly ActivationEdgeReport[];
+  readonly activationSources: readonly ActivationSourceReport[];
+  readonly cli: {
+    readonly path: readonly string[];
+  } | null;
+  /**
+   * Composed layer names visible at the survey boundary.
+   *
+   * Reports the names of typed layers that wrap this trail at execution time,
+   * in the framework's composition order: `topo → surface → trail`
+   * (outermost-first). Surface-scope layers are keyed by surface because
+   * each surface owns its own attachment set.
+   */
+  readonly composedLayers: {
+    readonly topo: readonly string[];
+    readonly surface: SurfaceLayerNames;
+    readonly trail: readonly string[];
+  };
+  readonly contourDetails: readonly TopoGraphContourEntry[];
+  readonly contours: readonly string[];
   readonly description: string | null;
   readonly detours:
     | readonly { readonly on: string; readonly maxAttempts: number }[]
     | null;
   readonly examples: readonly unknown[];
+  readonly fieldOverrides: readonly TopoGraphFieldOverride[];
   readonly crosses: readonly string[];
+  readonly fires: readonly string[];
+  readonly governance: Readonly<Record<string, unknown>> | null;
   readonly id: string;
+  readonly input: JsonSchema | null;
   readonly intent: 'read' | 'write' | 'destroy';
-  readonly kind: string;
+  readonly kind: 'trail';
+  readonly layers: readonly TopoGraphLayerReference[];
+  readonly on: readonly string[];
+  readonly output: JsonSchema | null;
   readonly pattern: string | null;
   readonly safety: string;
   readonly resources: readonly string[];
+  readonly surfaceProjections: readonly {
+    readonly derivedName: string;
+    readonly method: string | null;
+    readonly surface: string;
+    readonly trailId: string;
+  }[];
+  readonly surfaces: readonly string[];
+}
+
+export interface SignalDetailReport {
+  readonly consumers: readonly string[];
+  readonly description: string | null;
+  readonly examples: readonly unknown[];
+  readonly from: readonly string[];
+  readonly id: string;
+  readonly kind: 'signal';
+  /**
+   * The signal's payload schema (JSON Schema object), or `null` when the
+   * surface-map entry is missing for this signal. `null` is meaningful:
+   * it matches the list view's `payloadSchema: false` flag and lets
+   * consumers distinguish "schema not found" from "schema accepts any
+   * value" (the latter would be an empty object `{}`).
+   */
+  readonly payload: Readonly<Record<string, unknown>> | null;
+  readonly producers: readonly string[];
 }
 
 const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
@@ -170,9 +300,40 @@ const formatResourceList = (app: Topo): SurveyListReport['resources'] => {
     .toSorted((a, b) => a.id.localeCompare(b.id));
 };
 
+const formatSignalList = (
+  app: Topo,
+  relations: ReadonlyMap<string, SignalActivationRelations>
+): SurveyListReport['signals'] =>
+  app
+    .listSignals()
+    .map((signalDef) => {
+      const related = relations.get(signalDef.id);
+      const consumers = related?.consumers ?? [];
+      const producers = related?.producers ?? [];
+      return {
+        consumers,
+        description: signalDef.description ?? null,
+        examples: signalDef.examples?.length ?? 0,
+        from: signalDef.from?.toSorted() ?? [],
+        id: signalDef.id,
+        kind: signalDef.kind,
+        // Mirror the store path (`mapSignalRow` in `topo-store-read.ts`) which
+        // derives this from the surface-map entry. SignalSpec<T> requires
+        // `payload` so this is `true` in practice today; the explicit check
+        // keeps the in-memory and store reports self-consistent if a future
+        // SignalSpec variant ever omits `payload`.
+        payloadSchema: signalDef.payload !== undefined,
+        producers,
+      };
+    })
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+
 export const deriveSurveyList = (app: Topo): SurveyListReport => {
   const items = app.list();
+  const activation = deriveActivationGraph(app);
   const entries = items.map((item) => {
+    const trailActivation =
+      activation.trails.get(item.id) ?? deriveDeclaredTrailActivation(item);
     const safety = safetyLabel(
       item as unknown as { intent?: 'read' | 'write' | 'destroy' }
     );
@@ -183,6 +344,8 @@ export const deriveSurveyList = (app: Topo): SurveyListReport => {
       : 0;
 
     return {
+      activatedBy: trailActivation.activatedBy,
+      activates: trailActivation.activates,
       examples,
       id: item.id,
       kind: item.kind,
@@ -191,38 +354,250 @@ export const deriveSurveyList = (app: Topo): SurveyListReport => {
   });
 
   const resources = formatResourceList(app);
+  const signals = formatSignalList(app, activation.signals);
 
   return {
+    activation: activation.overview,
     count: items.length,
     entries,
     resourceCount: resources.length,
     resources,
+    signalCount: signals.length,
+    signals,
   };
 };
 
+export const deriveSignalDetail = (
+  app: Topo,
+  signalId: string,
+  activationGraph?: ActivationGraphReport | undefined
+): SignalDetailReport | undefined => {
+  const signalDef = app.signals.get(signalId) as Signal<unknown> | undefined;
+  if (signalDef === undefined) {
+    return undefined;
+  }
+  const related =
+    activationGraph?.signals.get(signalId) ??
+    deriveSignalActivationRelations(app, signalId);
+
+  return {
+    consumers: [...related.consumers],
+    description: signalDef.description ?? null,
+    examples: [...(signalDef.examples ?? [])],
+    from: signalDef.from?.toSorted() ?? [],
+    id: signalDef.id,
+    kind: 'signal',
+    payload: zodToJsonSchema(signalDef.payload),
+    producers: [...related.producers],
+  };
+};
+
+const emptySurfaceLayerNames = (): SurfaceLayerNames => ({
+  cli: [],
+  http: [],
+  mcp: [],
+});
+
+const normalizeSurfaceLayerNames = (
+  names?: Partial<SurfaceLayerNames> | undefined
+): SurfaceLayerNames => {
+  const base = emptySurfaceLayerNames();
+  if (names === undefined) {
+    return base;
+  }
+  return {
+    cli: names.cli ?? base.cli,
+    http: names.http ?? base.http,
+    mcp: names.mcp ?? base.mcp,
+  };
+};
+
+const emptyActivationContext = (): TrailDetailReport['activationContext'] => ({
+  edgeCount: 0,
+  sourceCount: 0,
+  sourceKeys: [],
+  trailIds: [],
+});
+
+const activationContextFromTopoGraph = (
+  topoGraph: TopoGraph | undefined,
+  trailId: string,
+  fallbackEdges: readonly TopoGraphActivationEdge[]
+): TrailDetailReport['activationContext'] => {
+  const edges =
+    topoGraph?.activationGraph.edges.filter(
+      (edge) => edge.trailId === trailId
+    ) ?? fallbackEdges;
+  if (edges.length === 0) {
+    return emptyActivationContext();
+  }
+  return {
+    edgeCount: edges.length,
+    sourceCount: new Set(edges.map((edge) => edge.sourceKey)).size,
+    sourceKeys: [...new Set(edges.map((edge) => edge.sourceKey))].toSorted(),
+    trailIds: [...new Set(edges.map((edge) => edge.trailId))].toSorted(),
+  };
+};
+
+const findTopoEntry = (
+  topoGraph: TopoGraph | undefined,
+  id: string,
+  kind: TopoGraphEntry['kind']
+): TopoGraphEntry | undefined =>
+  topoGraph?.entries.find((entry) => entry.id === id && entry.kind === kind);
+
+const trailActivationEdgesFromTopoGraph = (
+  topoGraph: TopoGraph | undefined,
+  trailId: string,
+  fallback: readonly TopoGraphActivationEdge[]
+): readonly TopoGraphActivationEdge[] =>
+  topoGraph?.activationGraph.edges.filter((edge) => edge.trailId === trailId) ??
+  fallback;
+
+const deriveSurfaceProjections = (
+  entry: TopoGraphEntry | undefined
+): TrailDetailReport['surfaceProjections'] => {
+  if (entry === undefined) {
+    return [];
+  }
+
+  const cliProjection =
+    entry.cli === undefined
+      ? []
+      : [
+          {
+            derivedName: entry.cli.path.join(' '),
+            method: null,
+            surface: 'cli',
+            trailId: entry.id,
+          },
+        ];
+  return cliProjection.toSorted((a, b) => a.surface.localeCompare(b.surface));
+};
+
+const deriveResolvedTrailGraphDetail = (
+  app: Topo | undefined,
+  trailId: string,
+  fallbackActivationEdges: readonly TopoGraphActivationEdge[],
+  topoGraphOverride?: TopoGraph | undefined
+): Pick<
+  TrailDetailReport,
+  | 'activationContext'
+  | 'activationEdges'
+  | 'cli'
+  | 'contourDetails'
+  | 'contours'
+  | 'fieldOverrides'
+  | 'governance'
+  | 'input'
+  | 'layers'
+  | 'output'
+  | 'surfaceProjections'
+  | 'surfaces'
+> => {
+  const topoGraph =
+    topoGraphOverride ?? (app === undefined ? undefined : deriveTopoGraph(app));
+  const topoEntry = findTopoEntry(topoGraph, trailId, 'trail');
+  const contours = topoEntry?.contours ?? [];
+  const contourDetails = contours
+    .map((contourId) => findTopoEntry(topoGraph, contourId, 'contour'))
+    .filter(
+      (entry): entry is TopoGraphContourEntry =>
+        entry !== undefined && entry.kind === 'contour'
+    );
+
+  return {
+    activationContext: activationContextFromTopoGraph(
+      topoGraph,
+      trailId,
+      fallbackActivationEdges
+    ),
+    activationEdges: trailActivationEdgesFromTopoGraph(
+      topoGraph,
+      trailId,
+      fallbackActivationEdges
+    ),
+    cli: topoEntry?.cli ?? null,
+    contourDetails,
+    contours,
+    fieldOverrides: topoEntry?.fieldOverrides ?? [],
+    governance: topoEntry?.governance ?? null,
+    input: topoEntry?.input ?? null,
+    layers: topoEntry?.layers ?? [],
+    output: topoEntry?.output ?? null,
+    surfaceProjections: deriveSurfaceProjections(topoEntry),
+    surfaces: topoEntry?.surfaces ?? [],
+  };
+};
+
+const formatTrailDetours = (item: AnyTrail): TrailDetailReport['detours'] =>
+  item.detours.length > 0
+    ? item.detours.map((d) => ({
+        maxAttempts: Math.max(
+          1,
+          Math.min(d.maxAttempts ?? 1, DETOUR_MAX_ATTEMPTS_CAP)
+        ),
+        on: d.on.name,
+      }))
+    : null;
+
 export const deriveTrailDetail = (
-  item: Trail<unknown, unknown>
+  item: AnyTrail,
+  app?: Topo | undefined,
+  activationGraph?: ActivationGraphReport | undefined,
+  options: TrailDetailOptions = {}
 ): TrailDetailReport => {
+  const activation =
+    app === undefined
+      ? deriveDeclaredTrailActivation(item)
+      : ((activationGraph ?? deriveActivationGraph(app)).trails.get(item.id) ??
+        deriveDeclaredTrailActivation(item));
   const safety = safetyLabel(
     item as unknown as { intent?: 'read' | 'write' | 'destroy' }
   );
 
+  const trailLayerNames = item.layers.map((layer) => layer.name);
+  const topoLayerNames = (app?.layers ?? []).map((layer) => layer.name);
+  const graphDetail = deriveResolvedTrailGraphDetail(
+    app,
+    item.id,
+    activation.edges,
+    options.topoGraph
+  );
+
   return {
+    activatedBy: activation.activatedBy,
+    activates: activation.activates,
+    activationChains: activation.chains,
+    activationContext: graphDetail.activationContext,
+    activationEdges: graphDetail.activationEdges,
+    activationSources: activation.sources,
+    cli: graphDetail.cli,
+    composedLayers: {
+      surface: normalizeSurfaceLayerNames(options.surfaceLayerNames),
+      topo: topoLayerNames,
+      trail: trailLayerNames,
+    },
+    contourDetails: graphDetail.contourDetails,
+    contours: graphDetail.contours,
     crosses: item.crosses.toSorted(),
     description: item.description ?? null,
-    detours:
-      item.detours.length > 0
-        ? item.detours.map((d) => ({
-            maxAttempts: d.maxAttempts ?? 1,
-            on: d.on.name,
-          }))
-        : null,
+    detours: formatTrailDetours(item),
     examples: item.examples ?? [],
+    fieldOverrides: graphDetail.fieldOverrides,
+    fires: activation.fires,
+    governance: graphDetail.governance,
     id: item.id,
+    input: graphDetail.input,
     intent: item.intent,
-    kind: item.kind,
+    kind: 'trail',
+    layers: graphDetail.layers,
+    on: activation.on,
+    output: graphDetail.output,
     pattern: item.pattern ?? null,
     resources: item.resources.map((resource) => resource.id).toSorted(),
     safety,
+    surfaceProjections: graphDetail.surfaceProjections,
+    surfaces: graphDetail.surfaces,
   };
 };

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

@@ -5,19 +5,26 @@
  * keeping module boundaries clean.
  */
 
-import type { Topo, TopoSnapshot } from '@ontrails/core';
-import { InternalError, Result } from '@ontrails/core';
-import type { StoredTopoExport } from '@ontrails/core/internal/topo-store';
-import {
-  createTopoSnapshot,
-  getStoredTopoExport,
-} from '@ontrails/core/internal/topo-store';
+import { Database } from 'bun:sqlite';
+
+import type { Topo } from '@ontrails/core';
 import {
-  openWriteTrailsDb,
   deriveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
-import type { SurfaceLock, SurfaceMap } from '@ontrails/schema';
-import { writeSurfaceLock, writeSurfaceMap } from '@ontrails/schema';
+  InternalError,
+  openWriteTrailsDb,
+  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 {
@@ -34,7 +41,7 @@ const persistAndReadStoredExport = (
   { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
   Error
 > => {
-  const snapshotResult = createTopoSnapshot(db, app, {
+  const snapshotResult = createStoredTopoSnapshot(db, app, {
     ...readGitState(rootDir),
     ...deriveTopoCounts(app),
   });
@@ -59,23 +66,40 @@ const persistAndReadStoredExport = (
   });
 };
 
+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 writeSurfaceMap(
-    JSON.parse(storedExport.surfaceMapJson) as SurfaceMap,
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
+  const topoPath = await writeTopoGraph(
+    JSON.parse(storedExport.topoGraphJson) as TopoGraph,
     { dir: trailsDir }
   );
-  const lockPath = await writeSurfaceLock(
-    JSON.parse(storedExport.lockContent) as SurfaceLock,
+  const lockPath = await writeLockManifest(
+    JSON.parse(storedExport.lockManifestJson) as LockManifest,
     { dir: trailsDir }
   );
 
   return {
-    hash: storedExport.surfaceHash,
+    hash: storedExport.topoGraphHash,
     lockPath,
-    mapPath,
+    topoPath,
   };
 };
 

package/src/trails/topo-support.ts

@@ -1,18 +1,23 @@
-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 {
   createTopoSnapshot as persistTopoSnapshot,
   listTopoSnapshots as readTopoSnapshots,
   pinTopoSnapshot,
   unpinTopoSnapshot,
-} from '@ontrails/core';
-import type { Topo, TopoSnapshot } from '@ontrails/core';
-import { deriveTrailsDbPath } from '@ontrails/core/internal/trails-db';
+} 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 snapshot record. Shared across topo trails. */
@@ -27,11 +32,13 @@ export const topoSnapshotOutput = z.object({
   trailCount: z.number(),
 });
 
-export const DEFAULT_APP_MODULE = './src/app.ts';
 export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
 export const LOCK_PATH = '.trails/trails.lock';
 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;
@@ -51,8 +58,8 @@ export interface TopoHistoryReport {
 export interface TopoExportReport {
   readonly hash: string;
   readonly lockPath: string;
-  readonly mapPath: string;
   readonly snapshot: TopoSnapshot;
+  readonly topoPath: string;
 }
 
 export interface TopoVerifyReport {
@@ -62,7 +69,7 @@ export interface TopoVerifyReport {
   readonly stale: false;
 }
 
-export const deriveRootDir = (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({
@@ -137,30 +144,13 @@ const buildSnapshotInput = (
 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 createCurrentTopoSnapshot = (
-  app: Topo,
-  options?: { readonly rootDir?: string }
-): TopoSnapshot => {
-  const rootDir = deriveRootDir(options?.rootDir);
-  const result = persistTopoSnapshot(app, {
-    rootDir,
-    ...buildSnapshotInput(app, rootDir),
-  });
-  if (result.isErr()) {
-    throw result.error;
-  }
-  return result.value;
-};
-
 export const listTopoHistory = (options?: {
   readonly limit?: number;
   readonly rootDir?: string;