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

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

@@ -66,16 +66,16 @@ const fieldOverrideOutput = z.object({
   }),
 });
 
-const contourDetailOutput = z.object({
+const entityDetailOutput = z.object({
   description: z.string().optional(),
   exampleCount: z.number(),
   id: z.string(),
   identity: z.string().optional(),
-  kind: z.literal('contour'),
+  kind: z.literal('entity'),
   references: z
     .array(
       z.object({
-        contour: z.string(),
+        entity: z.string(),
         field: z.string(),
         identity: z.string(),
       })
@@ -201,8 +201,6 @@ export const trailDetailOutput = z.object({
     trail: z.array(z.string()).readonly(),
   }),
   composes: z.array(z.string()).readonly(),
-  contourDetails: z.array(contourDetailOutput).readonly(),
-  contours: z.array(z.string()).readonly(),
   description: z.string().nullable(),
   detours: z
     .array(
@@ -213,6 +211,8 @@ export const trailDetailOutput = z.object({
     )
     .readonly()
     .nullable(),
+  entities: z.array(z.string()).readonly(),
+  entityDetails: z.array(entityDetailOutput).readonly(),
   examples: z.array(z.unknown()).readonly(),
   fieldOverrides: z.array(fieldOverrideOutput).readonly(),
   fires: z.array(z.string()).readonly(),

package/src/trails/topo-pin.ts

@@ -9,12 +9,6 @@ import {
 } from './topo-support.js';
 
 export const topoPinTrail = trail('topo.pin', {
-  blaze: async (input, ctx) =>
-    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
-      Result.ok(
-        pinCurrentTopoSnapshot(lease.app, { name: input.name, rootDir })
-      )
-    ),
   description: 'Pin the current topo under a durable name',
   examples: [
     {
@@ -25,6 +19,12 @@ export const topoPinTrail = trail('topo.pin', {
       name: 'Pin the current topo',
     },
   ],
+  implementation: async (input, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      Result.ok(
+        pinCurrentTopoSnapshot(lease.app, { name: input.name, rootDir })
+      )
+    ),
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     name: z.string().describe('Pin name'),

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

@@ -22,16 +22,17 @@ import {
   deriveTopoGraph,
   deriveTopoGraphDiff,
   deriveTopoGraphHash,
+  LOCK_MANIFEST_SCHEMA_VERSION,
   readLockManifest,
   readTopoGraph,
   readTrailsLock,
   stripTopoGraphForces,
-} from '@ontrails/topographer';
+} from '@ontrails/topography';
 import type {
   LockManifest,
   TopoGraph,
   TopoGraphOverlayRegistration,
-} from '@ontrails/topographer';
+} from '@ontrails/topography';
 
 import type {
   BriefReport,
@@ -121,7 +122,7 @@ const readCommittedLock = async (
         ],
         scope: trailsLock.scope,
         summary: trailsLock.summary,
-        version: 3,
+        version: LOCK_MANIFEST_SCHEMA_VERSION,
       },
       topoGraph: trailsLock.topoGraph as TopoGraph,
     };

package/src/trails/topo-reports.ts

@@ -9,7 +9,7 @@ import type { AnyTrail, Signal, Topo } from '@ontrails/core';
 import { deriveHttpMethod } from '@ontrails/http';
 import type { HttpMethod } from '@ontrails/http';
 import { deriveToolName } from '@ontrails/mcp';
-import { deriveTopoGraph } from '@ontrails/topographer';
+import { deriveTopoGraph } from '@ontrails/topography';
 import type {
   JsonSchema,
   TopoGraph,
@@ -18,7 +18,7 @@ import type {
   TopoGraphFieldOverride,
   TopoGraphLayerReference,
   TopoGraphVersionEntry,
-} from '@ontrails/topographer';
+} from '@ontrails/topography';
 import { z } from 'zod';
 
 import type {
@@ -122,7 +122,7 @@ export interface ShippedSurfaceInventoryReport {
   }[];
 }
 
-type TopoGraphContourEntry = TopoGraphEntry & { readonly kind: 'contour' };
+type TopoGraphEntityEntry = TopoGraphEntry & { readonly kind: 'entity' };
 
 export interface TrailDetailOptions {
   readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
@@ -191,8 +191,8 @@ export interface TrailDetailReport {
     readonly surface: SurfaceLayerNames;
     readonly trail: readonly string[];
   };
-  readonly contourDetails: readonly TopoGraphContourEntry[];
-  readonly contours: readonly string[];
+  readonly entityDetails: readonly TopoGraphEntityEntry[];
+  readonly entities: readonly string[];
   readonly description: string | null;
   readonly detours:
     | readonly { readonly on: string; readonly maxAttempts: number }[]
@@ -679,8 +679,8 @@ const deriveResolvedTrailGraphDetail = (
   | 'activationContext'
   | 'activationEdges'
   | 'cli'
-  | 'contourDetails'
-  | 'contours'
+  | 'entityDetails'
+  | 'entities'
   | 'fieldOverrides'
   | 'governance'
   | 'input'
@@ -695,12 +695,12 @@ const deriveResolvedTrailGraphDetail = (
   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'))
+  const entities = topoEntry?.entities ?? [];
+  const entityDetails = entities
+    .map((entityId) => findTopoEntry(topoGraph, entityId, 'entity'))
     .filter(
-      (entry): entry is TopoGraphContourEntry =>
-        entry !== undefined && entry.kind === 'contour'
+      (entry): entry is TopoGraphEntityEntry =>
+        entry !== undefined && entry.kind === 'entity'
     );
 
   return {
@@ -715,8 +715,8 @@ const deriveResolvedTrailGraphDetail = (
       fallbackActivationEdges
     ),
     cli: topoEntry?.cli ?? null,
-    contourDetails,
-    contours,
+    entities,
+    entityDetails,
     fieldOverrides: topoEntry?.fieldOverrides ?? [],
     governance: topoEntry?.governance ?? null,
     input: topoEntry?.input ?? null,
@@ -782,10 +782,10 @@ export const deriveTrailDetail = (
       trail: trailLayerNames,
     },
     composes: item.composes.toSorted(),
-    contourDetails: graphDetail.contourDetails,
-    contours: graphDetail.contours,
     description: item.description ?? null,
     detours: formatTrailDetours(item),
+    entities: graphDetail.entities,
+    entityDetails: graphDetail.entityDetails,
     examples: item.examples ?? [],
     fieldOverrides: graphDetail.fieldOverrides,
     fires: activation.fires,

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

@@ -22,21 +22,23 @@ import type {
   TopoGraphOverlayRegistration,
   TopoSnapshot,
   TrailsLock,
-} from '@ontrails/topographer';
-import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
+} from '@ontrails/topography';
+import type { StoredTopoExport } from '@ontrails/topography/backend-support';
 import {
   annotateTopoGraphForces,
   carryForwardTopoGraphForces,
   deriveSourceFingerprint,
   deriveTopoGraphDiff,
   deriveTopoGraphHash,
+  isTopoArtifactRegenerationError,
   readTopoGraph,
+  TRAILS_LOCK_SCHEMA_VERSION,
   writeTrailsLock,
-} from '@ontrails/topographer';
+} from '@ontrails/topography';
 import {
   createStoredTopoSnapshot,
   getStoredTopoExport,
-} from '@ontrails/topographer/backend-support';
+} from '@ontrails/topography/backend-support';
 
 import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
 
@@ -152,8 +154,15 @@ export const deriveCurrentTopoExport = (
 const readPreviousCommittedTopo = async (
   rootDir: string
 ): Promise<TopoGraph | null> => {
-  const rootTopo = await readTopoGraph({ dir: rootDir });
-  return rootTopo ?? readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+  try {
+    const rootTopo = await readTopoGraph({ dir: rootDir });
+    return rootTopo ?? readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+  } catch (error) {
+    if (isTopoArtifactRegenerationError(error)) {
+      return null;
+    }
+    throw error;
+  }
 };
 
 const prepareStoredExportArtifacts = async (
@@ -232,8 +241,8 @@ const writeStoredExportArtifacts = async (
     {
       scope: lockManifest.scope,
       summary: {
-        contours: prepared.topoGraph.entries.filter(
-          (entry) => entry.kind === 'contour'
+        entities: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'entity'
         ).length,
         resources: prepared.topoGraph.entries.filter(
           (entry) => entry.kind === 'resource'
@@ -247,7 +256,7 @@ const writeStoredExportArtifacts = async (
       },
       topoGraph: committedTopoGraph,
       topoGraphHash: prepared.hash,
-      version: 4,
+      version: TRAILS_LOCK_SCHEMA_VERSION,
     } as TrailsLock,
     { dir: rootDir }
   );

package/src/trails/topo-support.ts

@@ -8,8 +8,8 @@ import {
   listTopoSnapshots as readTopoSnapshots,
   pinTopoSnapshot,
   unpinTopoSnapshot,
-} from '@ontrails/topographer';
-import type { TopoSnapshot } from '@ontrails/topographer';
+} from '@ontrails/topography';
+import type { TopoSnapshot } from '@ontrails/topography';
 import { z } from 'zod';
 
 import {

package/src/trails/topo-unpin.ts

@@ -9,7 +9,18 @@ import {
 import { resolveTrailRootDir } from './root-dir.js';
 
 export const topoUnpinTrail = trail('topo.unpin', {
-  blaze: (input, ctx) => {
+  description: 'Remove a named topo pin',
+  examples: [
+    {
+      input: {
+        ...createIsolatedExampleInput('topo-unpin'),
+        dryRun: true,
+        name: 'before-auth-refactor',
+      },
+      name: 'Preview pin removal',
+    },
+  ],
+  implementation: (input, ctx) => {
     if (input.dryRun !== true && input.yes !== true) {
       return Result.err(
         new ValidationError(
@@ -31,17 +42,6 @@ export const topoUnpinTrail = trail('topo.unpin', {
       })
     );
   },
-  description: 'Remove a named topo pin',
-  examples: [
-    {
-      input: {
-        ...createIsolatedExampleInput('topo-unpin'),
-        dryRun: true,
-        name: 'before-auth-refactor',
-      },
-      name: 'Preview pin removal',
-    },
-  ],
   input: z.object({
     dryRun: z
       .boolean()

package/src/trails/topo.ts

@@ -72,10 +72,6 @@ const summaryOutput = z.object({
 });
 
 export const topoTrail = trail('topo', {
-  blaze: async (input, ctx) =>
-    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
-      Result.ok(deriveTopoSummary(lease.app, { rootDir }))
-    ),
   description: 'Show the current topo summary and entry list',
   examples: [
     {
@@ -83,6 +79,10 @@ export const topoTrail = trail('topo', {
       name: 'Show the current topo summary',
     },
   ],
+  implementation: async (input, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      Result.ok(deriveTopoSummary(lease.app, { rootDir }))
+    ),
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),

package/src/trails/validate.ts

@@ -5,14 +5,14 @@ import { withFreshOperatorApp } from './operator-context.js';
 import { validateCurrentTopo } from './topo-read-support.js';
 
 export const validateTrail = trail('validate', {
-  blaze: async (input, ctx) =>
+  description: 'Validate that root trails.lock matches the current topo',
+  implementation: async (input, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
       validateCurrentTopo(lease.app, {
         overlays: lease.overlays,
         rootDir,
       })
     ),
-  description: 'Validate that root trails.lock matches the current topo',
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),

package/src/trails/version-lifecycle-support.ts

@@ -3,9 +3,9 @@ import { join } from 'node:path';
 
 import { Result, ValidationError } from '@ontrails/core';
 import type { AnyTrail, Topo } from '@ontrails/core';
-import { deriveTopoGraph } from '@ontrails/topographer';
-import type { TopoGraph, TopoGraphForceEntry } from '@ontrails/topographer';
-import { findTrailDefinitions, parse } from '@ontrails/warden/ast';
+import { deriveTopoGraph } from '@ontrails/topography';
+import type { TopoGraph, TopoGraphForceEntry } from '@ontrails/topography';
+import { findTrailDefinitions, parse } from '@ontrails/source';
 
 import {
   readLifecycleSourceFile,
@@ -432,7 +432,7 @@ const missingResultImportWarning = (source: string): readonly string[] =>
   hasDirectResultImport(source)
     ? []
     : [
-        'Fork blaze placeholder references Result.err, but this file does not import Result from @ontrails/core.',
+        'Fork implementation placeholder references Result.err, but this file does not import Result from @ontrails/core.',
       ];
 
 const lineIndentAt = (source: string, index: number): string => {
@@ -460,13 +460,13 @@ const buildVersionEntry = (
   kind: LifecycleEntryKind,
   input: string,
   output: string,
-  blaze: string | undefined
+  implementation: string | undefined
 ): string => {
   if (kind === 'fork') {
     return `    ${version}: {
       input: ${input},
       output: ${output},
-      blaze: ${blaze ?? 'async () => Result.err(new Error("TODO: implement fork blaze"))'},
+      implementation: ${implementation ?? 'async () => Result.err(new Error("TODO: implement fork implementation"))'},
     },`;
   }
 
@@ -542,8 +542,9 @@ export const reviseTrailSource = (
 
   const currentVersion = trail.version ?? 1;
   const nextVersion = currentVersion + 1;
-  const blaze = findConfigProperty(match.value, 'blaze');
-  const usesForkPlaceholder = kind === 'fork' && blaze?.value === undefined;
+  const implementation = findConfigProperty(match.value, 'implementation');
+  const usesForkPlaceholder =
+    kind === 'fork' && implementation?.value === undefined;
   let nextSource = upsertCurrentVersion(
     match.value.source,
     match.value,
@@ -563,7 +564,7 @@ export const reviseTrailSource = (
       kind,
       input.value,
       output.value,
-      blaze?.value
+      implementation?.value
     )
   );
   const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
@@ -596,8 +597,8 @@ const forkVersionEntry = (
     configEnd: entry.valueEnd,
     configStart: propertyObjectStart(source, entry),
   };
-  const forkBlaze =
-    'blaze: async () => Result.err(new Error("TODO: implement fork blaze"))';
+  const forkImplementation =
+    'implementation: async () => Result.err(new Error("TODO: implement fork implementation"))';
   const transpose = findConfigProperty(entryMatch, 'transpose');
   if (transpose !== undefined) {
     const indent = lineIndentAt(source, transpose.start);
@@ -606,13 +607,13 @@ const forkVersionEntry = (
         source,
         transpose.start,
         transpose.end,
-        `${indent}${forkBlaze},`
+        `${indent}${forkImplementation},`
       ),
       usedPlaceholder: true,
     };
   }
-  const blaze = findConfigProperty(entryMatch, 'blaze');
-  if (blaze !== undefined) {
+  const implementation = findConfigProperty(entryMatch, 'implementation');
+  if (implementation !== undefined) {
     return { source, usedPlaceholder: false };
   }
   return {
@@ -620,7 +621,7 @@ const forkVersionEntry = (
       source,
       propertyObjectCloseLineStart(source, entry),
       propertyObjectCloseLineStart(source, entry),
-      `      ${forkBlaze},\n`
+      `      ${forkImplementation},\n`
     ),
     usedPlaceholder: true,
   };
@@ -848,7 +849,7 @@ const isDoctorForceEntry = (value: unknown): value is TopoGraphForceEntry =>
   (value['change'] === 'modified' || value['change'] === 'removed') &&
   typeof value['detail'] === 'string' &&
   typeof value['id'] === 'string' &&
-  (value['kind'] === 'contour' ||
+  (value['kind'] === 'entity' ||
     value['kind'] === 'trail' ||
     value['kind'] === 'signal' ||
     value['kind'] === 'resource') &&

package/src/trails/warden-guide.ts

@@ -104,14 +104,6 @@ const wardenGuideFields = {
 >;
 
 export const wardenGuideTrail = trail('warden.guide', {
-  blaze: (input) => {
-    const manifest = buildWardenGuideManifest();
-    return Result.ok({
-      format: input.guideFormat,
-      formatted: formatWardenGuide(manifest, input.guideFormat),
-      manifest,
-    });
-  },
   description: 'Project Warden rule guidance as markdown or JSON',
   examples: [
     {
@@ -124,6 +116,14 @@ export const wardenGuideTrail = trail('warden.guide', {
     },
   ],
   fields: wardenGuideFields,
+  implementation: (input) => {
+    const manifest = buildWardenGuideManifest();
+    return Result.ok({
+      format: input.guideFormat,
+      formatted: formatWardenGuide(manifest, input.guideFormat),
+      manifest,
+    });
+  },
   input: wardenGuideInputSchema,
   intent: 'read',
   output: z.object({

package/src/trails/warden.ts

@@ -171,7 +171,27 @@ export const buildWardenCommandArgs = (
 };
 
 export const wardenTrail = trail('warden', {
-  blaze: async (input, ctx) => {
+  description: 'Run governance checks (lint + drift)',
+  examples: [
+    {
+      input: {
+        depth: 'source',
+        lock: 'skip',
+        rootDir: createIsolatedWardenExampleRoot('default'),
+      },
+      name: 'Default warden run',
+    },
+    {
+      input: {
+        depth: 'source',
+        format: 'github',
+        lock: 'skip',
+        rootDir: createIsolatedWardenExampleRoot('github'),
+      },
+      name: 'GitHub Actions annotations',
+    },
+  ],
+  implementation: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
@@ -194,26 +214,6 @@ export const wardenTrail = trail('warden', {
       warnCount: report.warnCount,
     });
   },
-  description: 'Run governance checks (lint + drift)',
-  examples: [
-    {
-      input: {
-        depth: 'source',
-        lock: 'skip',
-        rootDir: createIsolatedWardenExampleRoot('default'),
-      },
-      name: 'Default warden run',
-    },
-    {
-      input: {
-        depth: 'source',
-        format: 'github',
-        lock: 'skip',
-        rootDir: createIsolatedWardenExampleRoot('github'),
-      },
-      name: 'GitHub Actions annotations',
-    },
-  ],
   input: wardenInputSchema,
   intent: 'write',
   output: z.object({