@ontrails/trails 1.0.0-beta.32 → 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/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,
@@ -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 = deriveCurrentTopoMatches(app, entityId, {
-    cliAliases,
+    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 = deriveCurrentTrailDetail(app, id, {
-    cliAliases,
+    overlays,
     rootDir,
     surfaceLayerNames,
   });
@@ -581,24 +582,16 @@ 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(deriveCurrentTopoList(app, { rootDir })),
 };
@@ -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)
       )
     ),
@@ -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-read-support.ts

@@ -8,7 +8,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import type { CliCommandAliasInput, Topo, TrailContext } from '@ontrails/core';
+import type { Topo, TrailContext } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDbPath,
@@ -27,7 +27,11 @@ import {
   readTrailsLock,
   stripTopoGraphForces,
 } from '@ontrails/topographer';
-import type { LockManifest, TopoGraph } from '@ontrails/topographer';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+} from '@ontrails/topographer';
 
 import type {
   BriefReport,
@@ -72,10 +76,8 @@ export interface CurrentTopoMatch {
 }
 
 export interface CurrentTopoReadOptions {
-  readonly cliAliases?:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined;
   readonly rootDir?: string | undefined;
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
 }
 
@@ -199,7 +201,9 @@ export const deriveCurrentTrailDetail = (
     ? undefined
     : deriveTrailDetail(trail, app, undefined, {
         surfaceLayerNames: options?.surfaceLayerNames,
-        topoGraph: deriveTopoGraph(app, { cliAliases: options?.cliAliases }),
+        topoGraph: deriveTopoGraph(app, {
+          overlays: options?.overlays,
+        }),
       });
 };
 
@@ -238,7 +242,9 @@ export const deriveCurrentTopoMatches = (
     (activationGraph ??= deriveActivationGraph(app));
   let topoGraph: ReturnType<typeof deriveTopoGraph> | undefined;
   const getTopoGraph = (): ReturnType<typeof deriveTopoGraph> =>
-    (topoGraph ??= deriveTopoGraph(app, { cliAliases: options?.cliAliases }));
+    (topoGraph ??= deriveTopoGraph(app, {
+      overlays: options?.overlays,
+    }));
 
   const trail = app.get(id);
   if (trail !== undefined) {
@@ -267,10 +273,8 @@ export const deriveCurrentTopoMatches = (
 export const validateCurrentTopo = async (
   app: Topo,
   options?: {
-    readonly cliAliases?:
-      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-      | undefined;
     readonly rootDir?: string;
+    readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   }
 ): Promise<Result<TopoValidateReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -298,7 +302,7 @@ export const validateCurrentTopo = async (
   }
 
   const currentExport = deriveCurrentTopoExport(app, {
-    cliAliases: options?.cliAliases,
+    overlays: options?.overlays,
     rootDir,
   });
   if (currentExport.isErr()) {

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

@@ -7,7 +7,7 @@
 
 import { Database } from 'bun:sqlite';
 
-import type { CliCommandAliasInput, Topo } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDir,
@@ -19,6 +19,7 @@ import {
 import type {
   LockManifest,
   TopoGraph,
+  TopoGraphOverlayRegistration,
   TopoSnapshot,
   TrailsLock,
 } from '@ontrails/topographer';
@@ -26,6 +27,7 @@ import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
 import {
   annotateTopoGraphForces,
   carryForwardTopoGraphForces,
+  deriveSourceFingerprint,
   deriveTopoGraphDiff,
   deriveTopoGraphHash,
   readTopoGraph,
@@ -45,21 +47,24 @@ import {
   readGitState,
 } from './topo-support.js';
 
-type CliAliasesOption = Readonly<
-  Record<string, readonly CliCommandAliasInput[]>
->;
+type OverlaysOption = readonly TopoGraphOverlayRegistration[];
 
 const persistAndReadStoredExport = (
   app: Topo,
   db: ReturnType<typeof openWriteTrailsDb>,
   rootDir: string,
-  options?: { readonly cliAliases?: CliAliasesOption | undefined } | undefined
+  options?:
+    | {
+        readonly overlays?: OverlaysOption | undefined;
+      }
+    | undefined
 ): Result<
   { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
   Error
 > => {
   const snapshotResult = createStoredTopoSnapshot(db, app, {
-    cliAliases: options?.cliAliases,
+    overlays: options?.overlays,
+    sourceFingerprint: deriveSourceFingerprint(rootDir),
     ...readGitState(rootDir),
     ...deriveTopoCounts(app),
   });
@@ -125,8 +130,8 @@ export const mapTopoExportError = (error: unknown): Error => {
 export const deriveCurrentTopoExport = (
   app: Topo,
   options?: {
-    readonly cliAliases?: CliAliasesOption | undefined;
     readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
   }
 ): Result<StoredTopoExport, Error> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -134,7 +139,7 @@ export const deriveCurrentTopoExport = (
 
   try {
     const projected = persistAndReadStoredExport(app, db, rootDir, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
     });
     return projected.isErr()
       ? projected
@@ -219,6 +224,10 @@ const writeStoredExportArtifacts = async (
   const lockManifest = JSON.parse(
     storedExport.lockManifestJson
   ) as LockManifest;
+  // Omit wallclock provenance from the committed artifact so recompiling the
+  // same sources yields byte-identical lock files; the hash never covered it.
+  const { generatedAt: _generatedAt, ...committedTopoGraph } =
+    prepared.topoGraph;
   const lockPath = await writeTrailsLock(
     {
       scope: lockManifest.scope,
@@ -236,7 +245,7 @@ const writeStoredExportArtifacts = async (
           (entry) => entry.kind === 'trail'
         ).length,
       },
-      topoGraph: prepared.topoGraph,
+      topoGraph: committedTopoGraph,
       topoGraphHash: prepared.hash,
       version: 4,
     } as TrailsLock,
@@ -256,9 +265,9 @@ const writeStoredExportArtifacts = async (
 export const exportCurrentTopo = async (
   app: Topo,
   options?: {
-    readonly cliAliases?: CliAliasesOption | undefined;
     readonly force?: boolean | undefined;
     readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
   }
 ): Promise<Result<TopoExportReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -266,7 +275,7 @@ export const exportCurrentTopo = async (
 
   try {
     const candidate = deriveCurrentTopoExport(app, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
       rootDir,
     });
     if (candidate.isErr()) {
@@ -283,7 +292,7 @@ export const exportCurrentTopo = async (
 
     db = openWriteTrailsDb({ rootDir });
     const persisted = persistAndReadStoredExport(app, db, rootDir, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
     });
     if (persisted.isErr()) {
       return persisted;

package/src/trails/topo-support.ts

@@ -29,6 +29,7 @@ export const topoSnapshotOutput = z.object({
   pinnedAs: z.string().optional(),
   resourceCount: z.number(),
   signalCount: z.number(),
+  sourceFingerprint: z.string().optional(),
   trailCount: z.number(),
 });
 

package/src/trails/validate.ts

@@ -8,7 +8,7 @@ export const validateTrail = trail('validate', {
   blaze: async (input, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
       validateCurrentTopo(lease.app, {
-        cliAliases: lease.cliAliases,
+        overlays: lease.overlays,
         rootDir,
       })
     ),

package/src/trails/wayfind.ts

@@ -40,7 +40,6 @@ const wayfindInputSchema = z
       .default(false)
       .describe('Render the describe view for the selected target'),
     errors: z.boolean().default(false).describe('Resolve trail error facts'),
-    facets: z.boolean().default(false).describe('Resolve surface facet facts'),
     impact: z
       .boolean()
       .default(false)
@@ -66,6 +65,12 @@ const wayfindInputSchema = z
       .boolean()
       .default(false)
       .describe('Render the outline view for a source file target'),
+    overlay: z
+      .string()
+      .optional()
+      .describe(
+        'Read a namespaced fact overlay from the saved graph (e.g. --overlay cloudflare)'
+      ),
     overview: z
       .boolean()
       .default(false)
@@ -81,6 +86,10 @@ const wayfindInputSchema = z
       .string()
       .optional()
       .describe('Graph entity ID or source file path to inspect'),
+    trailheads: z
+      .boolean()
+      .default(false)
+      .describe('Resolve surface trailhead facts'),
     trails: z.boolean().default(false).describe('Resolve trail facts'),
     view: wayfinderViewSchema
       .default('list')
@@ -134,7 +143,7 @@ const wayfindInputSchema = z
       (input.adapter === undefined &&
         !input.contours &&
         !input.errors &&
-        !input.facets &&
+        !input.trailheads &&
         input.intent === undefined &&
         !input.resources &&
         !input.signals &&
@@ -155,7 +164,34 @@ const wayfindInputSchema = z
         '--include attaches facts to a target or filtered population from locked artifacts; impact/deps and live-source includes are not supported yet.',
       path: ['include'],
     }
-  );
+  )
+  .refine(
+    (input) =>
+      input.overlay === undefined ||
+      (input.target === undefined &&
+        !input.deps &&
+        !input.impact &&
+        input.include.length === 0 &&
+        input.adapter === undefined &&
+        !input.contours &&
+        !input.errors &&
+        !input.trailheads &&
+        input.intent === undefined &&
+        !input.resources &&
+        !input.signals &&
+        !input.surfaces &&
+        !input.trails),
+    {
+      message:
+        'The --overlay flag reads one lock overlay and cannot be combined with targets, population selectors, or includes.',
+      path: ['overlay'],
+    }
+  )
+  .refine((input) => input.overlay === undefined || input.source !== 'live', {
+    message:
+      '--overlay reads namespaced overlays from locked artifacts; live source does not carry lock overlays.',
+    path: ['overlay'],
+  });
 
 const wayfindComposeInputSchema = z
   .object({
@@ -200,7 +236,7 @@ const hasLiveTypedFilter = (input: WayfindInput): boolean =>
   input.adapter !== undefined ||
   input.contours ||
   input.errors ||
-  input.facets ||
+  input.trailheads ||
   input.intent !== undefined ||
   input.resources ||
   input.signals ||
@@ -214,14 +250,14 @@ const populationFilters = (
   readonly kind?:
     | readonly (
         | 'contour'
-        | 'facet'
+        | 'trailhead'
         | 'resource'
         | 'signal'
         | 'surface'
         | 'trail'
       )[]
     | 'contour'
-    | 'facet'
+    | 'trailhead'
     | 'resource'
     | 'signal'
     | 'surface'
@@ -232,7 +268,7 @@ const populationFilters = (
 } => {
   const kinds = [
     ...(input.contours ? ['contour' as const] : []),
-    ...(input.facets ? ['facet' as const] : []),
+    ...(input.trailheads ? ['trailhead' as const] : []),
     ...(input.resources ? ['resource' as const] : []),
     ...(input.signals ? ['signal' as const] : []),
     ...(input.surfaces ? ['surface' as const] : []),
@@ -713,9 +749,9 @@ const viewPopulation = async (
       view: 'list' as const,
     };
   }
-  if (input.facets) {
+  if (input.trailheads) {
     return {
-      result: ctx.compose('wayfind.facets', {
+      result: ctx.compose('wayfind.trailheads', {
         filters,
         limit: input.limit,
         ...sourceInput(input),
@@ -767,6 +803,17 @@ export const wayfindTrail = trail('wayfind.navigate', {
         );
       }
     }
+    if (input.overlay !== undefined) {
+      return envelopeFor(
+        await ctx.compose('wayfind.overlay', {
+          namespace: input.overlay,
+          ...sourceInput(input),
+        }),
+        input,
+        ctx,
+        'list'
+      );
+    }
     const dispatched =
       (await viewRelation(input, ctx)) ??
       (await (input.target === undefined
@@ -791,7 +838,8 @@ export const wayfindTrail = trail('wayfind.navigate', {
     'wayfind.describe',
     'wayfind.errors',
     'wayfind.examples',
-    'wayfind.facets',
+    'wayfind.overlay',
+    'wayfind.trailheads',
     'wayfind.impact',
     'wayfind.nearby',
     'wayfind.outline',
@@ -842,13 +890,17 @@ export const wayfindTrail = trail('wayfind.navigate', {
       name: 'List surface facts',
     },
     {
-      input: { facets: true },
-      name: 'List facet facts',
+      input: { trailheads: true },
+      name: 'List trailhead facts',
     },
     {
       input: { overview: true },
       name: 'Show graph overview',
     },
+    {
+      input: { overlay: 'cloudflare' },
+      name: 'Read a namespaced lock overlay',
+    },
     {
       input: { include: ['examples'], target: 'wayfind.search' },
       name: 'Attach examples for a target',