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

package/src/trails/create-scaffold.ts

@@ -164,7 +164,7 @@ bun run guide
 ## Lexicon
 
 - \`trail\`, not action or handler
-- \`blaze\`, not handler or impl
+- \`implementation\`, not handler or impl
 - \`topo\`, not registry or collection
 - \`compose\`, not follow
 - \`surface\`, not transport
@@ -173,9 +173,9 @@ bun run guide
 
 ## Trail Rules
 
-- Blazes return \`Result\`; never throw from trail logic.
+- Implementations return \`Result\`; never throw from trail logic.
 - Use \`Result.ok()\` and \`Result.err()\`; branch with \`isOk()\`, \`isErr()\`, or \`match()\`.
-- Keep trail logic surface-agnostic. Do not import CLI, MCP, HTTP, request, or response types into blazes.
+- Keep trail logic surface-agnostic. Do not import CLI, MCP, HTTP, request, or response types into implementations.
 - Public MCP or HTTP trails declare an \`output\` schema.
 - Trails that compose other trails declare \`composes: [...]\` and invoke them with \`ctx.compose(...)\`.
 - Trails that use infrastructure declare \`resources: [...]\` and access them through the resource helpers.
@@ -236,7 +236,7 @@ const generateHelloTrail = (): string =>
 import { z } from 'zod';
 
 export const hello = trail('hello', {
-  blaze: (input) => {
+  implementation: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: \`Hello, \${name}!\` });
   },
@@ -277,7 +277,7 @@ const entitySchema = z.object({
 });
 
 export const show = trail('entity.show', {
-  blaze: (input, ctx) => {
+  implementation: (input, ctx) => {
     const store = entityStore.from(ctx);
     const entity = store.get(input.id);
     if (!entity) {
@@ -300,7 +300,7 @@ export const show = trail('entity.show', {
 });
 
 export const add = trail('entity.add', {
-  blaze: (input, ctx) => {
+  implementation: (input, ctx) => {
     const store = entityStore.from(ctx);
     const entity = { id: randomUUID(), name: input.name };
     store.add(entity);
@@ -322,7 +322,7 @@ export const add = trail('entity.add', {
 });
 
 export const list = trail('entity.list', {
-  blaze: (_input, ctx) => {
+  implementation: (_input, ctx) => {
     const store = entityStore.from(ctx);
     return Result.ok({ entities: store.list() });
   },
@@ -343,7 +343,7 @@ export const list = trail('entity.list', {
 });
 
 export const remove = trail('entity.delete', {
-  blaze: (input, ctx) => {
+  implementation: (input, ctx) => {
     const store = entityStore.from(ctx);
     const deleted = store.delete(input.id);
     return Result.ok({ deleted, id: input.id });
@@ -372,7 +372,7 @@ const generateSearchTrail = (): string =>
 import { z } from 'zod';
 
 export const search = trail('search', {
-  blaze: () => {
+  implementation: () => {
     return Result.ok({ results: [] });
   },
   description: 'Search entities by query',
@@ -396,7 +396,7 @@ const generateOnboardTrail = (): string =>
 import { z } from 'zod';
 
 export const onboard = trail('entity.onboard', {
-  blaze: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     const result = await ctx.compose('entity.add', { name: input.name });
     if (result.isErr()) {
       return result;
@@ -569,7 +569,8 @@ const collectScaffoldOperations = (
 // ---------------------------------------------------------------------------
 
 export const createScaffold = trail('create.scaffold', {
-  blaze: async (input) => {
+  description: 'Scaffold a new Trails project',
+  implementation: async (input) => {
     const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
     if (projectDirResult.isErr()) {
       return projectDirResult;
@@ -606,7 +607,6 @@ export const createScaffold = trail('create.scaffold', {
       plannedOperations: plannedOperations.value,
     } satisfies ScaffoldResult);
   },
-  description: 'Scaffold a new Trails project',
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
     dryRun: z

package/src/trails/create-versions.ts

@@ -27,7 +27,14 @@ const createVersionsOutputSchema = z.object({
 });
 
 export const createVersionsTrail = trail('create.versions', {
-  blaze: async (input, ctx) => {
+  description: 'Sync generated scaffold dependency versions',
+  examples: [
+    {
+      input: { check: true },
+      name: 'Verify generated scaffold versions are current',
+    },
+  ],
+  implementation: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
@@ -48,13 +55,6 @@ export const createVersionsTrail = trail('create.versions', {
       );
     }
   },
-  description: 'Sync generated scaffold dependency versions',
-  examples: [
-    {
-      input: { check: true },
-      name: 'Verify generated scaffold versions are current',
-    },
-  ],
   input: createVersionsInputSchema,
   intent: 'write',
   output: createVersionsOutputSchema,

package/src/trails/create.ts

@@ -200,7 +200,41 @@ const writeReadme = async (
 // ---------------------------------------------------------------------------
 
 export const createTrail = trail('create', {
-  blaze: async (input: CreateInput, ctx) => {
+  composes: ['create.scaffold', 'add.surface', 'add.verify'],
+  description: 'Create a new Trails project',
+  fields: {
+    starter: {
+      options: [
+        {
+          hint: 'One trail, one example',
+          label: 'Hello world',
+          value: 'hello',
+        },
+        {
+          hint: '4 trails, signal, store',
+          label: 'Entity CRUD',
+          value: 'entity',
+        },
+        { hint: 'Just the structure', label: 'Empty', value: 'empty' },
+      ],
+    },
+    surfaces: {
+      options: [
+        { hint: 'Commander-based command line', label: 'CLI', value: 'cli' },
+        {
+          hint: 'Model Context Protocol for agents',
+          label: 'MCP',
+          value: 'mcp',
+        },
+        {
+          hint: 'Hono-powered HTTP endpoints',
+          label: 'HTTP',
+          value: 'http',
+        },
+      ],
+    },
+  },
+  implementation: async (input: CreateInput, ctx) => {
     if (!hasCompose(ctx)) {
       return Result.err(new InternalError('create trail requires ctx.compose'));
     }
@@ -257,40 +291,6 @@ export const createTrail = trail('create', {
 
     return finishCreate();
   },
-  composes: ['create.scaffold', 'add.surface', 'add.verify'],
-  description: 'Create a new Trails project',
-  fields: {
-    starter: {
-      options: [
-        {
-          hint: 'One trail, one example',
-          label: 'Hello world',
-          value: 'hello',
-        },
-        {
-          hint: '4 trails, signal, store',
-          label: 'Entity CRUD',
-          value: 'entity',
-        },
-        { hint: 'Just the structure', label: 'Empty', value: 'empty' },
-      ],
-    },
-    surfaces: {
-      options: [
-        { hint: 'Commander-based command line', label: 'CLI', value: 'cli' },
-        {
-          hint: 'Model Context Protocol for agents',
-          label: 'MCP',
-          value: 'mcp',
-        },
-        {
-          hint: 'Hono-powered HTTP endpoints',
-          label: 'HTTP',
-          value: 'http',
-        },
-      ],
-    },
-  },
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
     name: z

package/src/trails/deprecate.ts

@@ -9,7 +9,8 @@ import {
 
 export const deprecateTrail = trail('deprecate', {
   args: ['target'],
-  blaze: async (input, ctx) =>
+  description: 'Mark a historical trail version deprecated or archived',
+  implementation: async (input, ctx) =>
     withLifecycleApp(input, ctx.cwd, async (_app, rootDir) => {
       const target = parseLifecycleTarget(input.target);
       if (target.isErr()) {
@@ -27,7 +28,6 @@ export const deprecateTrail = trail('deprecate', {
         }
       );
     }),
-  description: 'Mark a historical trail version deprecated or archived',
   input: z.object({
     archive: z
       .boolean()

package/src/trails/dev-clean.ts

@@ -9,7 +9,17 @@ import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devCleanTrail = trail('dev.clean', {
-  blaze: (input, ctx) => {
+  description: 'Prune unpinned topo snapshots and old trace records',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-clean').rootDir,
+      },
+      name: 'Preview local cleanup',
+    },
+  ],
+  implementation: (input, ctx) => {
     if (input.dryRun !== true && input.yes !== true) {
       return Result.err(
         new ValidationError(
@@ -33,16 +43,6 @@ export const devCleanTrail = trail('dev.clean', {
       })
     );
   },
-  description: 'Prune unpinned topo snapshots and old trace records',
-  examples: [
-    {
-      input: {
-        dryRun: true,
-        rootDir: createIsolatedExampleInput('dev-clean').rootDir,
-      },
-      name: 'Preview local cleanup',
-    },
-  ],
   input: z.object({
     dryRun: z
       .boolean()

package/src/trails/dev-reset.ts

@@ -6,7 +6,17 @@ import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devResetTrail = trail('dev.reset', {
-  blaze: (input, ctx) => {
+  description: 'Remove local Trails database artifacts',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
+      },
+      name: 'Preview local reset',
+    },
+  ],
+  implementation: (input, ctx) => {
     if (input.dryRun !== true && input.yes !== true) {
       return Result.err(
         new ValidationError(
@@ -22,16 +32,6 @@ export const devResetTrail = trail('dev.reset', {
     const rootDir = rootDirResult.value;
     return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
   },
-  description: 'Remove local Trails database artifacts',
-  examples: [
-    {
-      input: {
-        dryRun: true,
-        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
-      },
-      name: 'Preview local reset',
-    },
-  ],
   input: z.object({
     dryRun: z
       .boolean()

package/src/trails/dev-stats.ts

@@ -9,7 +9,14 @@ import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devStatsTrail = trail('dev.stats', {
-  blaze: (input, ctx) => {
+  description: 'Show local Trails workspace state and retention',
+  examples: [
+    {
+      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
+      name: 'Show local dev state',
+    },
+  ],
+  implementation: (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
@@ -24,13 +31,6 @@ export const devStatsTrail = trail('dev.stats', {
       })
     );
   },
-  description: 'Show local Trails workspace state and retention',
-  examples: [
-    {
-      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
-      name: 'Show local dev state',
-    },
-  ],
   input: z.object({
     rootDir: z.string().optional().describe('Workspace root directory'),
     snapshots: z

package/src/trails/dev-support.ts

@@ -11,7 +11,7 @@ import {
   countPrunableSnapshots,
   countTopoSnapshots,
   pruneUnpinnedSnapshots,
-} from '@ontrails/topographer/backend-support';
+} from '@ontrails/topography/backend-support';
 import {
   DEFAULT_MAX_AGE,
   DEFAULT_MAX_RECORDS,

package/src/trails/doctor.ts

@@ -5,7 +5,7 @@ import {
   Result,
   trail,
 } from '@ontrails/core';
-import { readTopoGraph } from '@ontrails/topographer';
+import { readTopoGraph } from '@ontrails/topography';
 import { z } from 'zod';
 
 import {
@@ -30,7 +30,8 @@ const toDoctorSummaryError = (error: unknown): InternalError =>
     : new InternalError(`Unable to derive doctor summary: ${String(error)}`);
 
 export const doctorTrail = trail('doctor', {
-  blaze: async (input, ctx) =>
+  description: 'Diagnose trail versioning lifecycle state',
+  implementation: async (input, ctx) =>
     withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
       const forceGraph = await readDoctorForceGraph(rootDir);
       try {
@@ -45,7 +46,6 @@ export const doctorTrail = trail('doctor', {
         return Result.err(toDoctorSummaryError(error));
       }
     }),
-  description: 'Diagnose trail versioning lifecycle state',
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),
@@ -61,7 +61,7 @@ export const doctorTrail = trail('doctor', {
           change: z.enum(['modified', 'removed']),
           detail: z.string(),
           id: z.string(),
-          kind: z.enum(['contour', 'trail', 'signal', 'resource']),
+          kind: z.enum(['entity', 'trail', 'signal', 'resource']),
           reason: z.string().optional(),
           scope: z.enum(['entry', 'graph']),
           severity: z.literal('breaking'),

package/src/trails/draft-promote.ts

@@ -21,7 +21,7 @@ import {
   isDraftMarkedFile,
   stripDraftFileMarkers,
 } from '@ontrails/warden';
-import { findStringLiterals, parse } from '@ontrails/warden/ast';
+import { findStringLiterals, parse } from '@ontrails/source';
 import { z } from 'zod';
 
 import {
@@ -674,7 +674,7 @@ const resolvePromotionAppModule = async (
  * @remarks
  * The lease deletes its on-disk mirror on release. Any Topo consumption that
  * may trigger deferred filesystem imports (for example inside a trail's
- * `blaze` or a lazy relative `import()`) must run before the lease is
+ * `implementation` or a lazy relative `import()`) must run before the lease is
  * released, otherwise those resolutions race the mirror teardown. Collapsing
  * consumption into the leased critical section keeps that contract
  * structural rather than relying on the caller to discover it.
@@ -884,7 +884,6 @@ const promoteDraftState = async (
 };
 
 export const draftPromoteTrail = trail('draft.promote', {
-  blaze: promoteDraftState,
   description:
     'Promote a draft id to an established id, rewrite inbound references, and verify the result against a fresh topo load.',
   examples: [
@@ -900,6 +899,7 @@ export const draftPromoteTrail = trail('draft.promote', {
       name: 'Rejects a missing project root before any rewrite begins',
     },
   ],
+  implementation: promoteDraftState,
   input: z.object({
     appModule: z
       .string()

package/src/trails/guide.ts

@@ -50,7 +50,15 @@ type GuideTrailInput = z.output<typeof guideTrailInputSchema>;
 // ---------------------------------------------------------------------------
 
 export const guideTrail = trail('guide', {
-  blaze: async (input: GuideTrailInput, ctx) =>
+  description: 'Runtime guidance for trails',
+  examples: [
+    {
+      description: 'Lists all trails with descriptions and example counts',
+      input: createIsolatedExampleInput('guide-list'),
+      name: 'List trail guidance',
+    },
+  ],
+  implementation: async (input: GuideTrailInput, ctx) =>
     withFreshOperatorApp<GuideTrailOutput>(input, ctx, ({ lease, rootDir }) => {
       if (input.trailId) {
         const detail = deriveCurrentTopoDetail(lease.app, input.trailId, {
@@ -76,14 +84,6 @@ export const guideTrail = trail('guide', {
         mode: 'list' as const,
       });
     }),
-  description: 'Runtime guidance for trails',
-  examples: [
-    {
-      description: 'Lists all trails with descriptions and example counts',
-      input: createIsolatedExampleInput('guide-list'),
-      name: 'List trail guidance',
-    },
-  ],
   input: guideTrailInputSchema,
   intent: 'read',
   output: z.discriminatedUnion('mode', [

package/src/trails/load-app.ts

@@ -26,7 +26,7 @@ import {
 } from '@ontrails/core';
 import type { Topo } from '@ontrails/core';
 import { resolveTrailsOverlays } from '@ontrails/adapter-kit';
-import type { TopoGraphOverlayRegistration } from '@ontrails/topographer';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topography';
 import { findAppModule } from '@ontrails/cli';
 
 import {
@@ -75,7 +75,7 @@ const getImportScanner = (loader: TranspilerLoader): Bun.Transpiler => {
  * @remarks
  * A fresh-loaded module may expose functions whose deferred relative imports
  * are resolved only when those functions run (for example inside a trail's
- * `blaze`). If we deleted the mirror tree immediately after the initial
+ * `implementation`). If we deleted the mirror tree immediately after the initial
  * `import()` resolved, those later resolutions would hit an ENOENT. We keep
  * the mirrors on disk and clean them up once, on process exit.
  */
@@ -964,7 +964,7 @@ const mirrorFreshImportGraph = async (
  * filesystem imports are mirrored into the fresh temp root. The mirror tree
  * is retained for the lifetime of the process so that deferred relative
  * `import()`/`require()` calls originating from the loaded module (e.g.
- * inside a trail's `blaze`) can still resolve. If the graph walk itself
+ * inside a trail's `implementation`) can still resolve. If the graph walk itself
  * fails, the partially-written mirror is removed immediately so failed
  * loads do not leak disk space.
  */