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

package/src/trails/topo-activation.ts

@@ -0,0 +1,385 @@
+import type {
+  ActivationEntry,
+  ActivationSource,
+  ActivationSourceProjection,
+  AnyTrail,
+  Topo,
+} from '@ontrails/core';
+import {
+  activationSourceKey,
+  projectActivationSourceDeclaration,
+} from '@ontrails/core';
+
+export interface ActivationChainReport {
+  readonly consumer: string;
+  readonly producer: string;
+  readonly signal: string;
+}
+
+type JsonSchemaReport = Readonly<Record<string, unknown>>;
+
+export interface ActivationSourceReport extends ActivationSourceProjection {
+  readonly cron?: string | undefined;
+  readonly hasParse?: true | undefined;
+  readonly hasPayloadSchema?: true | undefined;
+  readonly hasVerify?: true | undefined;
+  readonly id: string;
+  readonly input?: unknown;
+  readonly inputSchema?: JsonSchemaReport | undefined;
+  readonly kind: string;
+  readonly key: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  readonly method?: string | undefined;
+  readonly parseOutputSchema?: JsonSchemaReport | undefined;
+  readonly path?: string | undefined;
+  readonly payloadSchema?: JsonSchemaReport | undefined;
+  readonly timezone?: string | undefined;
+}
+
+export interface ActivationEdgeReport extends Readonly<
+  Record<string, unknown>
+> {
+  readonly hasWhere: boolean;
+  readonly sourceId: string;
+  readonly sourceKey: string;
+  readonly sourceKind: string;
+  readonly trailId: string;
+  readonly where?: { readonly predicate: true } | undefined;
+}
+
+export interface SignalActivationRelations {
+  readonly consumers: readonly string[];
+  readonly producers: readonly string[];
+}
+
+export interface TrailActivationReport {
+  readonly activatedBy: readonly string[];
+  readonly activates: readonly string[];
+  readonly chains: readonly ActivationChainReport[];
+  readonly edges: readonly ActivationEdgeReport[];
+  readonly fires: readonly string[];
+  readonly on: readonly string[];
+  readonly sources: readonly ActivationSourceReport[];
+}
+
+export interface ActivationOverviewReport {
+  readonly chainCount: number;
+  readonly chains: readonly ActivationChainReport[];
+  readonly edgeCount: number;
+  readonly edges: readonly ActivationEdgeReport[];
+  readonly signalIds: readonly string[];
+  readonly sourceCount: number;
+  readonly sourceKeys: readonly string[];
+  readonly trailIds: readonly string[];
+}
+
+export interface ActivationGraphReport {
+  readonly overview: ActivationOverviewReport;
+  readonly signals: ReadonlyMap<string, SignalActivationRelations>;
+  readonly sources: ReadonlyMap<string, ActivationSourceReport>;
+  readonly trails: ReadonlyMap<string, TrailActivationReport>;
+}
+
+interface MutableSignalRelations {
+  readonly consumers: Set<string>;
+  readonly producers: Set<string>;
+}
+
+interface MutableTrailActivation {
+  readonly activatedBy: Set<string>;
+  readonly activates: Set<string>;
+  readonly chains: ActivationChainReport[];
+  readonly fires: readonly string[];
+  readonly on: readonly string[];
+}
+
+const canonicalLeaf = (value: unknown): unknown => {
+  switch (typeof value) {
+    case 'bigint': {
+      return value.toString();
+    }
+    case 'function': {
+      return `[Function:${value.name || 'anonymous'}]`;
+    }
+    case 'symbol': {
+      return `[Symbol:${value.description ?? ''}]`;
+    }
+    case 'undefined': {
+      return '[Undefined]';
+    }
+    default: {
+      return value;
+    }
+  }
+};
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      const next = (value as Record<string, unknown>)[key];
+      sorted[key] = next === undefined ? '[Undefined]' : canonicalize(next);
+    }
+    return sorted;
+  }
+  return canonicalLeaf(value);
+};
+
+const sortKeys = <T extends Record<string, unknown>>(value: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    sorted[key] = value[key];
+  }
+  return sorted as T;
+};
+
+const compareChains = (
+  a: ActivationChainReport,
+  b: ActivationChainReport
+): number =>
+  a.producer.localeCompare(b.producer) ||
+  a.signal.localeCompare(b.signal) ||
+  a.consumer.localeCompare(b.consumer);
+
+const sortedUnique = (values: Iterable<string>): readonly string[] =>
+  [...new Set(values)].toSorted();
+
+const projectActivationSource = (
+  source: ActivationSource
+): ActivationSourceReport =>
+  projectActivationSourceDeclaration(source) as ActivationSourceReport;
+
+const projectActivationEdge = (
+  trailId: string,
+  activation: ActivationEntry
+): ActivationEdgeReport => {
+  const sourceKey = activationSourceKey(activation.source);
+  const edge: Record<string, unknown> = {
+    hasWhere: activation.where !== undefined,
+    sourceId: activation.source.id,
+    sourceKey,
+    sourceKind: activation.source.kind,
+    trailId,
+  };
+
+  if (activation.meta !== undefined) {
+    edge['meta'] = canonicalize(activation.meta);
+  }
+  if (activation.where !== undefined) {
+    edge['where'] = { predicate: true };
+  }
+
+  return sortKeys(edge) as ActivationEdgeReport;
+};
+
+const collectActivationSourceCatalog = (
+  trails: readonly AnyTrail[]
+): readonly ActivationSourceReport[] => {
+  const sources = new Map<string, ActivationSourceReport>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const projected = projectActivationSource(activation.source);
+      sources.set(projected.key, projected);
+    }
+  }
+  return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
+};
+
+const collectActivationEdges = (
+  trails: readonly AnyTrail[]
+): readonly ActivationEdgeReport[] => {
+  const edges = new Map<string, ActivationEdgeReport>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const edge = projectActivationEdge(trail.id, activation);
+      const key = `${edge.sourceKey}\0${edge.trailId}`;
+      const previous = edges.get(key);
+      edges.set(
+        key,
+        previous === undefined || (!previous.hasWhere && edge.hasWhere)
+          ? edge
+          : previous
+      );
+    }
+  }
+
+  return [...edges.values()].toSorted(
+    (a, b) =>
+      a.sourceKey.localeCompare(b.sourceKey) ||
+      a.trailId.localeCompare(b.trailId)
+  );
+};
+
+const getSignalRelations = (
+  relations: Map<string, MutableSignalRelations>,
+  signalId: string
+): MutableSignalRelations => {
+  const existing = relations.get(signalId);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = {
+    consumers: new Set<string>(),
+    producers: new Set<string>(),
+  };
+  relations.set(signalId, created);
+  return created;
+};
+
+const getTrailActivation = (
+  trails: Map<string, MutableTrailActivation>,
+  trail: AnyTrail
+): MutableTrailActivation => {
+  const existing = trails.get(trail.id);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = {
+    activatedBy: new Set<string>(),
+    activates: new Set<string>(),
+    chains: [],
+    fires: sortedUnique(trail.fires),
+    on: sortedUnique(trail.on),
+  };
+  trails.set(trail.id, created);
+  return created;
+};
+
+export const deriveDeclaredTrailActivation = (
+  trail: AnyTrail
+): TrailActivationReport => {
+  const sources = collectActivationSourceCatalog([trail]);
+  return {
+    activatedBy: [],
+    activates: [],
+    chains: [],
+    edges: collectActivationEdges([trail]),
+    fires: sortedUnique(trail.fires),
+    on: sortedUnique(trail.on),
+    sources,
+  };
+};
+
+export const deriveSignalActivationRelations = (
+  app: Topo,
+  signalId: string
+): SignalActivationRelations => {
+  const consumers: string[] = [];
+  const producers: string[] = [];
+
+  for (const trail of app.list()) {
+    if (trail.fires.includes(signalId)) {
+      producers.push(trail.id);
+    }
+    if (trail.on.includes(signalId)) {
+      consumers.push(trail.id);
+    }
+  }
+
+  return {
+    consumers: sortedUnique(consumers),
+    producers: sortedUnique(producers),
+  };
+};
+
+export const deriveActivationGraph = (app: Topo): ActivationGraphReport => {
+  const signalRelations = new Map<string, MutableSignalRelations>();
+  const trailActivations = new Map<string, MutableTrailActivation>();
+  const trails = app.list();
+  const sources = collectActivationSourceCatalog(trails);
+  const edges = collectActivationEdges(trails);
+
+  for (const signal of app.listSignals()) {
+    getSignalRelations(signalRelations, signal.id);
+  }
+
+  for (const trail of trails) {
+    const trailActivation = getTrailActivation(trailActivations, trail);
+    for (const signalId of trailActivation.fires) {
+      getSignalRelations(signalRelations, signalId).producers.add(trail.id);
+    }
+    for (const signalId of trailActivation.on) {
+      getSignalRelations(signalRelations, signalId).consumers.add(trail.id);
+    }
+  }
+
+  const chains: ActivationChainReport[] = [];
+  for (const [signal, related] of signalRelations) {
+    for (const producer of related.producers) {
+      const producerActivation = trailActivations.get(producer);
+      for (const consumer of related.consumers) {
+        const chain = { consumer, producer, signal };
+        chains.push(chain);
+        producerActivation?.activates.add(consumer);
+        producerActivation?.chains.push(chain);
+        const consumerActivation = trailActivations.get(consumer);
+        consumerActivation?.activatedBy.add(producer);
+        if (consumerActivation !== producerActivation) {
+          consumerActivation?.chains.push(chain);
+        }
+      }
+    }
+  }
+
+  chains.sort(compareChains);
+  const activeTrailIds = sortedUnique([
+    ...[...trailActivations.entries()].flatMap(([trailId, trail]) =>
+      trail.fires.length > 0 || trail.on.length > 0
+        ? [trailId, ...trail.activatedBy, ...trail.activates]
+        : []
+    ),
+    ...edges.map((edge) => edge.trailId),
+  ]);
+
+  return {
+    overview: {
+      chainCount: chains.length,
+      chains,
+      edgeCount: edges.length,
+      edges,
+      signalIds: [...signalRelations.keys()].toSorted(),
+      sourceCount: sources.length,
+      sourceKeys: sources.map((source) => source.key),
+      trailIds: activeTrailIds,
+    },
+    signals: new Map(
+      [...signalRelations.entries()].map(([id, relations]) => [
+        id,
+        {
+          consumers: sortedUnique(relations.consumers),
+          producers: sortedUnique(relations.producers),
+        },
+      ])
+    ),
+    sources: new Map(sources.map((source) => [source.key, source])),
+    trails: new Map(
+      [...trailActivations.entries()].map(([id, activation]) => [
+        id,
+        {
+          activatedBy: sortedUnique(activation.activatedBy),
+          activates: sortedUnique(activation.activates),
+          chains: activation.chains.toSorted(compareChains),
+          edges: edges.filter((edge) => edge.trailId === id),
+          fires: activation.fires,
+          on: activation.on,
+          sources: sources.filter((source) =>
+            edges.some(
+              (edge) => edge.trailId === id && edge.sourceKey === source.key
+            )
+          ),
+        },
+      ])
+    ),
+  };
+};

package/src/trails/topo-compile.ts

@@ -0,0 +1,55 @@
+import { Result, trail } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+import type { TopoExportReport } from './topo-support.js';
+import {
+  createIsolatedExampleInput,
+  topoSnapshotOutput,
+} from './topo-support.js';
+
+export const compileCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
+
+export const topoCompileTrail = trail('topo.compile', {
+  blaze: async (input, ctx) => {
+    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 await compileCurrentTopo(lease.app, { rootDir });
+    } finally {
+      lease.release();
+    }
+  },
+  description: 'Compile the current topo to .trails artifacts',
+  examples: [
+    {
+      input: createIsolatedExampleInput('topo-compile'),
+      name: 'Compile the current topo artifacts',
+    },
+  ],
+  input: z.object({
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'write',
+  output: z.object({
+    hash: z.string(),
+    lockPath: z.string(),
+    snapshot: topoSnapshotOutput,
+    topoPath: z.string(),
+  }),
+});

package/src/trails/topo-history.ts

@@ -3,21 +3,25 @@ import { z } from 'zod';
 
 import {
   DEFAULT_TOPO_HISTORY_LIMIT,
-  isolatedExampleInput,
+  createIsolatedExampleInput,
   listTopoHistory,
-  topoPinOutput,
-  topoSaveOutput,
+  topoSnapshotOutput,
 } from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 export const topoHistoryTrail = trail('topo.history', {
   blaze: (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     return Result.ok(listTopoHistory({ limit: input.limit, rootDir }));
   },
-  description: 'List saved topo metadata, including pins and recent autosaves',
+  description: 'List saved topo snapshots, including pinned references',
   examples: [
     {
-      input: isolatedExampleInput('topo-history'),
+      input: createIsolatedExampleInput('topo-history'),
       name: 'Show topo history',
     },
   ],
@@ -25,16 +29,15 @@ export const topoHistoryTrail = trail('topo.history', {
     limit: z
       .number()
       .default(DEFAULT_TOPO_HISTORY_LIMIT)
-      .describe('Maximum number of autosaves to return'),
+      .describe('Maximum number of snapshots to return'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',
   output: z.object({
     dbPath: z.string(),
     limit: z.number(),
-    pinCount: z.number(),
-    pins: z.array(topoPinOutput),
-    saveCount: z.number(),
-    saves: z.array(topoSaveOutput),
+    pinnedCount: z.number(),
+    snapshotCount: z.number(),
+    snapshots: z.array(topoSnapshotOutput),
   }),
 });

package/src/trails/topo-output-schemas.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+
+const jsonSchemaOutput = z.record(z.string(), z.unknown());
+
+export const activationChainOutput = z.object({
+  consumer: z.string(),
+  producer: z.string(),
+  signal: z.string(),
+});
+
+export const activationSourceOutput = z
+  .object({
+    cron: z.string().optional(),
+    hasParse: z.literal(true).optional(),
+    hasPayloadSchema: z.literal(true).optional(),
+    hasVerify: z.literal(true).optional(),
+    id: z.string(),
+    input: z.unknown().optional(),
+    inputSchema: jsonSchemaOutput.optional(),
+    key: z.string(),
+    kind: z.string(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+    method: z.string().optional(),
+    parseOutputSchema: jsonSchemaOutput.optional(),
+    path: z.string().optional(),
+    payloadSchema: jsonSchemaOutput.optional(),
+    timezone: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+export const activationEdgeOutput = z
+  .object({
+    hasWhere: z.boolean(),
+    sourceId: z.string(),
+    sourceKey: z.string(),
+    sourceKind: z.string(),
+    trailId: z.string(),
+    where: z.object({ predicate: z.literal(true) }).optional(),
+  })
+  .catchall(z.unknown());
+
+export const activationOverviewOutput = z.object({
+  chainCount: z.number(),
+  chains: z.array(activationChainOutput).readonly(),
+  edgeCount: z.number(),
+  edges: z.array(activationEdgeOutput).readonly(),
+  signalIds: z.array(z.string()).readonly(),
+  sourceCount: z.number(),
+  sourceKeys: z.array(z.string()).readonly(),
+  trailIds: z.array(z.string()).readonly(),
+});
+
+const topoGraphLayerOutput = z.object({
+  input: jsonSchemaOutput.optional(),
+  name: z.string(),
+  scope: z.enum(['topo', 'trail']),
+});
+
+const fieldOverrideOutput = z.object({
+  field: z.string(),
+  overrides: z
+    .array(z.enum(['hint', 'label', 'message', 'options']))
+    .readonly(),
+  provenance: z.object({
+    source: z.literal('trail.fields'),
+  }),
+});
+
+const contourDetailOutput = z.object({
+  description: z.string().optional(),
+  exampleCount: z.number(),
+  id: z.string(),
+  identity: z.string().optional(),
+  kind: z.literal('contour'),
+  references: z
+    .array(
+      z.object({
+        contour: z.string(),
+        field: z.string(),
+        identity: z.string(),
+      })
+    )
+    .readonly()
+    .optional(),
+  schema: jsonSchemaOutput.optional(),
+  surfaces: z.array(z.string()).readonly(),
+});
+
+const surfaceProjectionOutput = z.object({
+  derivedName: z.string(),
+  method: z.string().nullable(),
+  surface: z.string(),
+  trailId: z.string(),
+});
+
+export const trailDetailOutput = z.object({
+  activatedBy: z.array(z.string()).readonly(),
+  activates: z.array(z.string()).readonly(),
+  activationChains: z.array(activationChainOutput).readonly(),
+  activationContext: z.object({
+    edgeCount: z.number(),
+    sourceCount: z.number(),
+    sourceKeys: z.array(z.string()).readonly(),
+    trailIds: z.array(z.string()).readonly(),
+  }),
+  activationEdges: z.array(activationEdgeOutput).readonly(),
+  activationSources: z.array(activationSourceOutput).readonly(),
+  cli: z
+    .object({
+      path: z.array(z.string()).readonly(),
+    })
+    .nullable(),
+  composedLayers: z.object({
+    surface: z.object({
+      cli: z.array(z.string()).readonly(),
+      http: z.array(z.string()).readonly(),
+      mcp: z.array(z.string()).readonly(),
+    }),
+    topo: z.array(z.string()).readonly(),
+    trail: z.array(z.string()).readonly(),
+  }),
+  contourDetails: z.array(contourDetailOutput).readonly(),
+  contours: z.array(z.string()).readonly(),
+  crosses: z.array(z.string()).readonly(),
+  description: z.string().nullable(),
+  detours: z
+    .array(
+      z.object({
+        maxAttempts: z.number(),
+        on: z.string(),
+      })
+    )
+    .readonly()
+    .nullable(),
+  examples: z.array(z.unknown()).readonly(),
+  fieldOverrides: z.array(fieldOverrideOutput).readonly(),
+  fires: z.array(z.string()).readonly(),
+  governance: z.record(z.string(), z.unknown()).nullable(),
+  id: z.string(),
+  input: jsonSchemaOutput.nullable(),
+  intent: z.enum(['read', 'write', 'destroy']),
+  kind: z.literal('trail'),
+  layers: z.array(topoGraphLayerOutput).readonly(),
+  on: z.array(z.string()).readonly(),
+  output: jsonSchemaOutput.nullable(),
+  pattern: z.string().nullable(),
+  resources: z.array(z.string()).readonly(),
+  safety: z.string(),
+  surfaceProjections: z.array(surfaceProjectionOutput).readonly(),
+  surfaces: z.array(z.string()).readonly(),
+});
+
+export const resourceDetailOutput = z.object({
+  description: z.string().nullable(),
+  health: z.enum(['available', 'none']),
+  id: z.string(),
+  kind: z.literal('resource'),
+  lifetime: z.literal('singleton'),
+  usedBy: z.array(z.string()).readonly(),
+});
+
+export const signalDetailOutput = z.object({
+  consumers: z.array(z.string()).readonly(),
+  description: z.string().nullable(),
+  examples: z.array(z.unknown()).readonly(),
+  from: z.array(z.string()).readonly(),
+  id: z.string(),
+  kind: z.literal('signal'),
+  // null when the surface-map entry is missing for this signal (e.g. partial
+  // import or schema migration). Coherent with the list view's
+  // `payloadSchema: false` flag — distinguishes "schema not found" from
+  // "schema accepts any value" (the latter would be `{}`).
+  payload: z.record(z.string(), z.unknown()).nullable(),
+  producers: z.array(z.string()).readonly(),
+});