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

package/src/trails/topo-reports.ts

@@ -1,56 +1,189 @@
-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 provisions: boolean;
-    readonly outputSchemas: boolean;
-    readonly examples: boolean;
-    readonly detours: boolean;
-    readonly signals: boolean;
-  };
-  readonly trails: number;
-  readonly signals: number;
-  readonly provisions: 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;
     readonly safety: string;
   }[];
-  readonly provisionCount: number;
-  readonly provisions: readonly {
+  readonly resourceCount: number;
+  readonly resources: readonly {
     readonly description: string | null;
     readonly health: 'available' | 'none';
     readonly id: string;
-    readonly kind: 'provision';
+    readonly kind: 'resource';
     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: Trail<unknown, unknown>['detours'] | 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 provisions: readonly 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 => {
-  if (key === 'examples') {
+  if (key === 'examples' || key === 'detours') {
     return Array.isArray(raw[key]) && (raw[key] as unknown[]).length > 0;
   }
   return Boolean(raw[key]);
@@ -62,7 +195,7 @@ const detectFeatures = (
   hasDetours: boolean;
   hasExamples: boolean;
   hasOutputSchemas: boolean;
-  hasProvisions: boolean;
+  hasResources: boolean;
 } => {
   const trails = [...app.trails.values()].map(
     (item) => item as unknown as Record<string, unknown>
@@ -71,16 +204,16 @@ const detectFeatures = (
     hasDetours: trails.some((r) => trailHas(r, 'detours')),
     hasExamples: trails.some((r) => trailHas(r, 'examples')),
     hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
-    hasProvisions: trails.some(
+    hasResources: trails.some(
       (r) =>
-        Array.isArray(r['provisions']) &&
-        (r['provisions'] as unknown[]).length > 0
+        Array.isArray(r['resources']) &&
+        (r['resources'] as unknown[]).length > 0
     ),
   };
 };
 
-export const generateBriefReport = (app: Topo): BriefReport => {
-  const { hasDetours, hasExamples, hasOutputSchemas, hasProvisions } =
+export const deriveBriefReport = (app: Topo): BriefReport => {
+  const { hasDetours, hasExamples, hasOutputSchemas, hasResources } =
     detectFeatures(app);
 
   return {
@@ -89,11 +222,11 @@ export const generateBriefReport = (app: Topo): BriefReport => {
       detours: hasDetours,
       examples: hasExamples,
       outputSchemas: hasOutputSchemas,
-      provisions: hasProvisions,
+      resources: hasResources,
       signals: app.signals.size > 0,
     },
     name: app.name,
-    provisions: app.provisions.size,
+    resources: app.resources.size,
     signals: app.signals.size,
     trails: app.trails.size,
     version: REPORT_VERSION,
@@ -115,16 +248,16 @@ const safetyLabel = (entry: {
   return '-';
 };
 
-const buildProvisionUsage = (
+const buildResourceUsage = (
   app: Topo
 ): ReadonlyMap<string, readonly string[]> => {
   const usage = new Map<string, string[]>();
 
   for (const trailDef of app.list()) {
-    for (const declaredProvision of trailDef.provisions) {
-      const users = usage.get(declaredProvision.id) ?? [];
+    for (const declaredResource of trailDef.resources) {
+      const users = usage.get(declaredResource.id) ?? [];
       users.push(trailDef.id);
-      usage.set(declaredProvision.id, users);
+      usage.set(declaredResource.id, users);
     }
   }
 
@@ -133,46 +266,74 @@ const buildProvisionUsage = (
   );
 };
 
-const provisionHealthStatus = (provision: {
+const resourceHealthStatus = (resource: {
   health?: unknown;
 }): 'available' | 'none' =>
-  provision.health === undefined ? 'none' : 'available';
+  resource.health === undefined ? 'none' : 'available';
 
-export const formatProvisionDetail = (
-  app: Topo,
-  provisionId: string
-): object => {
-  const item = app.getProvision(provisionId);
-  const usedBy = buildProvisionUsage(app).get(provisionId) ?? [];
+export const deriveResourceDetail = (app: Topo, resourceId: string): object => {
+  const item = app.getResource(resourceId);
+  const usedBy = buildResourceUsage(app).get(resourceId) ?? [];
 
   return {
     description: item?.description ?? null,
-    health: item ? provisionHealthStatus(item) : 'none',
-    id: provisionId,
-    kind: 'provision',
+    health: item ? resourceHealthStatus(item) : 'none',
+    id: resourceId,
+    kind: 'resource',
     lifetime: 'singleton',
     usedBy,
   };
 };
 
-const formatProvisionList = (app: Topo): SurveyListReport['provisions'] => {
-  const usage = buildProvisionUsage(app);
+const formatResourceList = (app: Topo): SurveyListReport['resources'] => {
+  const usage = buildResourceUsage(app);
   return app
-    .listProvisions()
-    .map((provision) => ({
-      description: provision.description ?? null,
-      health: provisionHealthStatus(provision),
-      id: provision.id,
-      kind: provision.kind,
+    .listResources()
+    .map((resource) => ({
+      description: resource.description ?? null,
+      health: resourceHealthStatus(resource),
+      id: resource.id,
+      kind: resource.kind,
       lifetime: 'singleton' as const,
-      usedBy: usage.get(provision.id) ?? [],
+      usedBy: usage.get(resource.id) ?? [],
     }))
     .toSorted((a, b) => a.id.localeCompare(b.id));
 };
 
-export const generateSurveyList = (app: Topo): SurveyListReport => {
+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 generateSurveyList = (app: Topo): SurveyListReport => {
       : 0;
 
     return {
+      activatedBy: trailActivation.activatedBy,
+      activates: trailActivation.activates,
       examples,
       id: item.id,
       kind: item.kind,
@@ -190,32 +353,251 @@ export const generateSurveyList = (app: Topo): SurveyListReport => {
     };
   });
 
-  const provisions = formatProvisionList(app);
+  const resources = formatResourceList(app);
+  const signals = formatSignalList(app, activation.signals);
 
   return {
+    activation: activation.overview,
     count: items.length,
     entries,
-    provisionCount: provisions.length,
-    provisions,
+    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(),
   };
 };
 
-export const generateTrailDetail = (
-  item: Trail<unknown, unknown>
+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: 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 ?? 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,
-    provisions: item.provisions.map((provision) => provision.id).toSorted(),
+    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,
   };
 };