@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.39

package/src/trails/release-smoke.ts

@@ -14,7 +14,8 @@ const releaseSmokeInputSchema = z.object({
 });
 
 const releaseSmokeCheckResultSchema = z.object({
-  check: z.enum(['packed-artifacts', 'wayfinder-dogfood']),
+  check: z.enum(['lock-roundtrip', 'packed-artifacts', 'wayfinder-dogfood']),
+  lockCount: z.number().optional(),
   message: z.string(),
   packageCount: z.number().optional(),
   passed: z.literal(true),

package/src/trails/revise.ts

@@ -44,7 +44,7 @@ export const reviseTrail = trail('revise', {
   }),
   intent: 'write',
   output: z.object({
-    file: z.string(),
+    filePath: z.string(),
     trailId: z.string(),
     updated: z.boolean(),
     warnings: z.array(z.string()).optional(),

package/src/trails/survey.ts

@@ -7,7 +7,7 @@
 
 import { basename, extname, join } from 'node:path';
 
-import type { CliCommandAliasInput, Topo } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import {
   deriveSafePath,
   NotFoundError,
@@ -15,7 +15,12 @@ import {
   trail,
   ValidationError,
 } from '@ontrails/core';
-import type { DiffEntry, DiffResult, TopoGraph } from '@ontrails/topographer';
+import type {
+  DiffEntry,
+  DiffResult,
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+} from '@ontrails/topographer';
 import {
   createTopoStore,
   deriveTopoGraphDiff,
@@ -30,12 +35,12 @@ import { writeIsolatedExampleJsonFile } from '../local-state-io.js';
 
 import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import {
-  buildCurrentTopoBrief,
-  buildCurrentTopoList,
-  buildCurrentTopoMatches,
-  buildCurrentTrailDetail,
-  buildCurrentResourceDetail,
-  buildCurrentSignalDetail,
+  deriveCurrentTopoBrief,
+  deriveCurrentTopoList,
+  deriveCurrentTopoMatches,
+  deriveCurrentTrailDetail,
+  deriveCurrentResourceDetail,
+  deriveCurrentSignalDetail,
   readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
 import {
@@ -506,13 +511,11 @@ const buildSurveyLookup = (
   app: Topo,
   entityId: string,
   rootDir: string,
-  cliAliases:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
-  const matches = buildCurrentTopoMatches(app, entityId, {
-    cliAliases,
+  const matches = deriveCurrentTopoMatches(app, entityId, {
+    overlays,
     rootDir,
     surfaceLayerNames,
   });
@@ -523,13 +526,11 @@ const buildSurveyTrailDetail = (
   app: Topo,
   id: string,
   rootDir: string,
-  cliAliases:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
-  const detail = buildCurrentTrailDetail(app, id, {
-    cliAliases,
+  const detail = deriveCurrentTrailDetail(app, id, {
+    overlays,
     rootDir,
     surfaceLayerNames,
   });
@@ -543,7 +544,7 @@ const buildSurveyResourceDetail = (
   id: string,
   rootDir: string
 ): Result<object, Error> => {
-  const detail = buildCurrentResourceDetail(app, id, { rootDir });
+  const detail = deriveCurrentResourceDetail(app, id, { rootDir });
   return detail === undefined
     ? Result.err(new NotFoundError(`Resource not found: ${id}`))
     : Result.ok(detail);
@@ -554,7 +555,7 @@ const buildSurveySignalDetail = (
   id: string,
   rootDir: string
 ): Result<object, Error> => {
-  const detail = buildCurrentSignalDetail(app, id, { rootDir });
+  const detail = deriveCurrentSignalDetail(app, id, { rootDir });
   return detail === undefined
     ? Result.err(new NotFoundError(`Signal not found: ${id}`))
     : Result.ok(detail);
@@ -581,26 +582,18 @@ type SurveyHandler = (
   app: Topo,
   input: SurveyInput,
   rootDir: string,
-  cliAliases:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ) => Result<object, Error> | Promise<Result<object, Error>>;
 
 /** Handlers keyed by survey mode. */
 const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
-  lookup: (app, input, rootDir, cliAliases, surfaceLayerNames) =>
+  lookup: (app, input, rootDir, overlays, surfaceLayerNames) =>
     input.id === undefined || input.id === ''
       ? Result.err(new ValidationError('Survey lookup requires an id'))
-      : buildSurveyLookup(
-          app,
-          input.id,
-          rootDir,
-          cliAliases,
-          surfaceLayerNames
-        ),
+      : buildSurveyLookup(app, input.id, rootDir, overlays, surfaceLayerNames),
   overview: (app, _input, rootDir) =>
-    Result.ok(buildCurrentTopoList(app, { rootDir })),
+    Result.ok(deriveCurrentTopoList(app, { rootDir })),
 };
 
 const envelopeSurveyValue = (
@@ -613,9 +606,7 @@ const dispatchSurvey = async (
   app: Topo,
   input: SurveyInput,
   rootDir: string,
-  cliAliases:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Promise<Result<SurveyEnvelope, Error>> => {
   const mode = deriveSurveyMode(input);
@@ -624,7 +615,7 @@ const dispatchSurvey = async (
     app,
     input,
     rootDir,
-    cliAliases,
+    overlays,
     surfaceLayerNames
   );
   if (result.isErr()) {
@@ -644,13 +635,11 @@ const withFreshSurveyApp = async <T>(
   rootDir: string,
   consume: (
     app: Topo,
-    cliAliases:
-      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-      | undefined
+    overlays: readonly TopoGraphOverlayRegistration[] | undefined
   ) => Promise<Result<T, Error>> | Result<T, Error>
 ): Promise<Result<T, Error>> =>
   withFreshAppLease(input.module, rootDir, (lease) =>
-    consume(lease.app, lease.cliAliases)
+    consume(lease.app, lease.overlays)
   );
 
 const withResolvedSurveyApp = async <T>(
@@ -662,14 +651,12 @@ const withResolvedSurveyApp = async <T>(
   consume: (
     app: Topo,
     rootDir: string,
-    cliAliases:
-      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-      | undefined
+    overlays: readonly TopoGraphOverlayRegistration[] | undefined
   ) => Promise<Result<T, Error>> | Result<T, Error>
 ): Promise<Result<T, Error>> =>
   withOperatorRootDir(input, { cwd }, (rootDir) =>
-    withFreshSurveyApp(input, rootDir, (app, cliAliases) =>
-      consume(app, rootDir, cliAliases)
+    withFreshSurveyApp(input, rootDir, (app, overlays) =>
+      consume(app, rootDir, overlays)
     )
   );
 
@@ -743,12 +730,12 @@ const surveyMatchOutput = z.discriminatedUnion('kind', [
 export const surveyTrail = trail('survey', {
   args: ['id'],
   blaze: async (input, ctx) =>
-    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, cliAliases) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, overlays) =>
       dispatchSurvey(
         app,
         input,
         rootDir,
-        cliAliases,
+        overlays,
         readSurfaceLayerNamesFromContext(ctx)
       )
     ),
@@ -824,7 +811,7 @@ export const surveyTrail = trail('survey', {
 export const surveyBriefTrail = trail('survey.brief', {
   blaze: async (input, ctx) =>
     withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
-      Result.ok(buildCurrentTopoBrief(app, { rootDir }))
+      Result.ok(deriveCurrentTopoBrief(app, { rootDir }))
     ),
   description: 'Summarize topo capabilities',
   examples: [
@@ -904,12 +891,12 @@ export const surveyDiffTrail = trail('survey.diff', {
 export const surveyTrailDetailTrail = trail('survey.trail', {
   args: ['id'],
   blaze: async (input, ctx) =>
-    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, cliAliases) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, overlays) =>
       buildSurveyTrailDetail(
         app,
         input.id,
         rootDir,
-        cliAliases,
+        overlays,
         readSurfaceLayerNamesFromContext(ctx)
       )
     ),

package/src/trails/topo-activation.ts

@@ -1,385 +1,14 @@
-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
-            )
-          ),
-        },
-      ])
-    ),
-  };
-};
+export {
+  deriveActivationGraph,
+  deriveDeclaredTrailActivation,
+  deriveSignalActivationRelations,
+} from '@ontrails/topographer';
+export type {
+  ActivationChainReport,
+  ActivationEdgeReport,
+  ActivationGraphReport,
+  ActivationOverviewReport,
+  ActivationSourceReport,
+  SignalActivationRelations,
+  TrailActivationReport,
+} from '@ontrails/topographer';