@ontrails/config 1.0.0-beta.12 → 1.0.0-beta.13

package/CHANGELOG.md

@@ -1,17 +1,45 @@
 # @ontrails/config
 
-## 1.0.0-beta.12
+## 1.0.0-beta.13
 
 ### Minor Changes
 
-- Complete trifecta for config, permits, and crumbs (formerly tracks)
+- 6944147: Complete trifecta for config, permits, and tracker (formerly tracks)
 
-  - **config**: Add `configService`, `config.layer`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **config**: Add `configProvision`, `configGate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
   - **permits**: Add `authService` and `auth.verify` trail for runtime authorization checks
-  - **crumbs**: Rename tracks to crumbs; add `crumbsService` and `crumbs.status` trail for structured event tracking
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured signal tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Trail-native vocabulary cutover. Breaking API field renames across all packages:
+
+  - Trail spec: `run:` → `blaze:`, `follow:` → `crosses:`, `services:` → `provisions:`, `metadata:` → `meta:`, `emits:` → `signals:`
+  - Runtime: `ctx.follow()` → `ctx.cross()`, `ctx.emit()` → `ctx.signal()`, `ctx.signal` (abort) → `ctx.abortSignal`
+  - Entry points: `blaze(app)` → `trailhead(app)`
+  - Package rename: `@ontrails/crumbs` → `@ontrails/tracker`
+  - Wrapper types: `Layer` → `Gate`, `layers`/`middleware` → `gates`
+  - Transport: `surface` → `trailhead`, `adapter` → `connector`
+
+### Patch Changes
+
+- Updated dependencies [6944147]
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.13
+
+## 1.0.0-beta.12
+
+### Minor Changes
+
+- Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `config.gate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authProvision` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured event tracking
   - **cli**: Fix build flag handling and improve bootstrap scaffolding
   - **testing**: Expand test context helpers and example-based testing utilities
-  - **core/mcp/http**: Internal alignment for service and composition updates
+  - **core/mcp/http**: Internal alignment for provision and composition updates
 
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/config",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/__tests__/compose.test.ts

@@ -2,57 +2,57 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
-import { collectServiceConfigs } from '../compose.js';
+import { collectProvisionConfigs } from '../compose.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('collectServiceConfigs', () => {
-  test('extracts config schemas from services that declare them', () => {
+describe('collectProvisionConfigs', () => {
+  test('extracts config schemas from provisions that declare them', () => {
     const dbSchema = z.object({ url: z.string().url() });
     const cacheSchema = z.object({ ttl: z.number() });
 
-    const services = [
+    const provisions = [
       { config: dbSchema, id: 'db.main' },
       { config: cacheSchema, id: 'cache.main' },
     ];
 
-    const entries = collectServiceConfigs(services);
+    const entries = collectProvisionConfigs(provisions);
 
     expect(entries).toHaveLength(2);
-    expect(entries[0]).toEqual({ schema: dbSchema, serviceId: 'db.main' });
+    expect(entries[0]).toEqual({ provisionId: 'db.main', schema: dbSchema });
     expect(entries[1]).toEqual({
+      provisionId: 'cache.main',
       schema: cacheSchema,
-      serviceId: 'cache.main',
     });
   });
 
-  test('excludes services without config', () => {
+  test('excludes provisions without config', () => {
     const schema = z.object({ url: z.string() });
 
-    const services = [
+    const provisions = [
       { config: schema, id: 'db.main' },
       { id: 'counter.main' },
       { config: undefined, id: 'logger.main' },
     ];
 
-    const entries = collectServiceConfigs(services);
+    const entries = collectProvisionConfigs(provisions);
 
     expect(entries).toHaveLength(1);
-    expect(entries[0]?.serviceId).toBe('db.main');
+    expect(entries[0]?.provisionId).toBe('db.main');
   });
 
-  test('returns empty array when no services have config', () => {
-    const services = [{ id: 'counter.main' }, { id: 'logger.main' }];
+  test('returns empty array when no provisions have config', () => {
+    const provisions = [{ id: 'counter.main' }, { id: 'logger.main' }];
 
-    const entries = collectServiceConfigs(services);
+    const entries = collectProvisionConfigs(provisions);
 
     expect(entries).toEqual([]);
   });
 
   test('returns empty array for empty input', () => {
-    const entries = collectServiceConfigs([]);
+    const entries = collectProvisionConfigs([]);
 
     expect(entries).toEqual([]);
   });

package/src/__tests__/config-check.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createServiceLookup } from '@ontrails/core';
+import { createProvisionLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -7,22 +7,22 @@ import { configCheck } from '../trails/config-check.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configService resolved in extensions.
+ * Build a TrailContext with configProvision resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
   const ctx: TrailContext = {
+    abortSignal: AbortSignal.timeout(5000),
     cwd: '/tmp',
     env: {},
     extensions,
+    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
-    service: undefined as unknown as TrailContext['service'],
-    signal: AbortSignal.timeout(5000),
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    service: createServiceLookup(() => withLookup),
+    provision: createProvisionLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -41,17 +41,17 @@ describe('config.check trail', () => {
       expect(configCheck.intent).toBe('read');
     });
 
-    test('has infrastructure metadata', () => {
-      expect(configCheck.metadata).toEqual({ category: 'infrastructure' });
+    test('has infrastructure meta', () => {
+      expect(configCheck.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has output schema', () => {
       expect(configCheck.output).toBeDefined();
     });
 
-    test('declares configService dependency', () => {
-      expect(configCheck.services).toBeDefined();
-      expect(configCheck.services?.length).toBe(1);
+    test('declares configProvision dependency', () => {
+      expect(configCheck.provisions).toBeDefined();
+      expect(configCheck.provisions?.length).toBe(1);
     });
   });
 
@@ -72,7 +72,7 @@ describe('config.check trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configCheck.run({ values: {} }, ctx);
+      const result = await configCheck.blaze({ values: {} }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -90,7 +90,7 @@ describe('config.check trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configCheck.run({ values: {} }, ctx);
+      const result = await configCheck.blaze({ values: {} }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -108,7 +108,7 @@ describe('config.check trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configCheck.run({ values: { port: 8080 } }, ctx);
+      const result = await configCheck.blaze({ values: { port: 8080 } }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -129,7 +129,7 @@ describe('config.check trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configCheck.run(
+      const result = await configCheck.blaze(
         { values: { db: { port: 6543 } } },
         ctx
       );
@@ -159,7 +159,7 @@ describe('config.check trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configCheck.run({ values: {} }, ctx);
+      const result = await configCheck.blaze({ values: {} }, ctx);
 
       expect(result.isOk()).toBe(true);
       const defaults = result

package/src/__tests__/config-describe.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createServiceLookup } from '@ontrails/core';
+import { createProvisionLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -8,22 +8,22 @@ import { env, secret } from '../extensions.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configService resolved in extensions.
+ * Build a TrailContext with configProvision resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
   const ctx: TrailContext = {
+    abortSignal: AbortSignal.timeout(5000),
     cwd: '/tmp',
     env: {},
     extensions,
+    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
-    service: undefined as unknown as TrailContext['service'],
-    signal: AbortSignal.timeout(5000),
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    service: createServiceLookup(() => withLookup),
+    provision: createProvisionLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -42,17 +42,17 @@ describe('config.describe trail', () => {
       expect(configDescribe.intent).toBe('read');
     });
 
-    test('has infrastructure metadata', () => {
-      expect(configDescribe.metadata).toEqual({ category: 'infrastructure' });
+    test('has infrastructure meta', () => {
+      expect(configDescribe.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has output schema', () => {
       expect(configDescribe.output).toBeDefined();
     });
 
-    test('declares configService dependency', () => {
-      expect(configDescribe.services).toBeDefined();
-      expect(configDescribe.services?.length).toBe(1);
+    test('declares configProvision dependency', () => {
+      expect(configDescribe.provisions).toBeDefined();
+      expect(configDescribe.provisions?.length).toBe(1);
     });
   });
 
@@ -73,7 +73,7 @@ describe('config.describe trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configDescribe.run({}, ctx);
+      const result = await configDescribe.blaze({}, ctx);
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap().fields.length).toBe(2);
@@ -89,7 +89,7 @@ describe('config.describe trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configDescribe.run({}, ctx);
+      const result = await configDescribe.blaze({}, ctx);
       const { fields } = result.unwrap();
 
       expect(fields[0]?.path).toBe('host');
@@ -107,7 +107,7 @@ describe('config.describe trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configDescribe.run({}, ctx);
+      const result = await configDescribe.blaze({}, ctx);
 
       expect(result.isOk()).toBe(true);
       const [field] = result.unwrap().fields;
@@ -123,7 +123,7 @@ describe('config.describe trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configDescribe.run({}, ctx);
+      const result = await configDescribe.blaze({}, ctx);
 
       expect(result.isOk()).toBe(true);
       const [field] = result.unwrap().fields;
@@ -141,7 +141,7 @@ describe('config.describe trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configDescribe.run({}, ctx);
+      const result = await configDescribe.blaze({}, ctx);
 
       expect(result.isOk()).toBe(true);
       const { fields } = result.unwrap();

package/src/__tests__/config-explain.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { createServiceLookup } from '@ontrails/core';
+import { createProvisionLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -8,22 +8,22 @@ import { env } from '../extensions.js';
 import type { ConfigState } from '../registry.js';
 
 /**
- * Build a TrailContext with configService resolved in extensions.
+ * Build a TrailContext with configProvision resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
   const ctx: TrailContext = {
+    abortSignal: AbortSignal.timeout(5000),
     cwd: '/tmp',
     env: {},
     extensions,
+    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
-    service: undefined as unknown as TrailContext['service'],
-    signal: AbortSignal.timeout(5000),
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    service: createServiceLookup(() => withLookup),
+    provision: createProvisionLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -42,17 +42,17 @@ describe('config.explain trail', () => {
       expect(configExplain.intent).toBe('read');
     });
 
-    test('has infrastructure metadata', () => {
-      expect(configExplain.metadata).toEqual({ category: 'infrastructure' });
+    test('has infrastructure meta', () => {
+      expect(configExplain.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has output schema', () => {
       expect(configExplain.output).toBeDefined();
     });
 
-    test('declares configService dependency', () => {
-      expect(configExplain.services).toBeDefined();
-      expect(configExplain.services?.length).toBe(1);
+    test('declares configProvision dependency', () => {
+      expect(configExplain.provisions).toBeDefined();
+      expect(configExplain.provisions?.length).toBe(1);
     });
   });
 
@@ -73,7 +73,7 @@ describe('config.explain trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configExplain.run({ path: '' }, ctx);
+      const result = await configExplain.blaze({ path: '' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -96,7 +96,7 @@ describe('config.explain trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configExplain.run({ path: 'db' }, ctx);
+      const result = await configExplain.blaze({ path: 'db' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -121,7 +121,7 @@ describe('config.explain trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configExplain.run({ path: 'db' }, ctx);
+      const result = await configExplain.blaze({ path: 'db' }, ctx);
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap().entries).toEqual([
@@ -139,7 +139,7 @@ describe('config.explain trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configExplain.run({ path: '' }, ctx);
+      const result = await configExplain.blaze({ path: '' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const [entry] = result.unwrap().entries;
@@ -157,7 +157,7 @@ describe('config.explain trail', () => {
         schema,
       };
       const ctx = buildCtx(state);
-      const result = await configExplain.run({ path: '' }, ctx);
+      const result = await configExplain.blaze({ path: '' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const [entry] = result.unwrap().entries;

package/src/__tests__/{config-layer.test.ts → config-gate.test.ts}

@@ -3,33 +3,33 @@ import { Result } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
-import { configLayer } from '../config-layer.js';
+import { configGate } from '../config-gate.js';
 
 const stubTrail = {
+  blaze: (_input: unknown, _ctx: TrailContext) => Result.ok({}),
+  crosses: [],
   description: undefined,
   detours: undefined,
   examples: undefined,
   fields: undefined,
-  follow: [],
   id: 'test.stub',
   idempotent: undefined,
   input: z.object({}),
   intent: 'read' as const,
   kind: 'trail' as const,
-  metadata: undefined,
+  meta: undefined,
   output: undefined,
-  run: (_input: unknown, _ctx: TrailContext) => Result.ok({}),
-  services: [],
+  provisions: [],
 };
 
-describe('configLayer', () => {
+describe('configGate', () => {
   describe('identity', () => {
     test('has name "config"', () => {
-      expect(configLayer.name).toBe('config');
+      expect(configGate.name).toBe('config');
     });
 
     test('has a description', () => {
-      expect(configLayer.description).toBeDefined();
+      expect(configGate.description).toBeDefined();
     });
   });
 
@@ -38,7 +38,7 @@ describe('configLayer', () => {
       const impl = (_input: unknown, _ctx: TrailContext) =>
         Result.ok({ called: true });
 
-      const wrapped = configLayer.wrap(stubTrail, impl);
+      const wrapped = configGate.wrap(stubTrail, impl);
       const ctx = {
         cwd: '/tmp',
         env: {},

package/src/__tests__/config-init.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createServiceLookup } from '@ontrails/core';
+import { createProvisionLookup } from '@ontrails/core';
 import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -11,22 +11,22 @@ import type { ConfigState } from '../registry.js';
 import { configInit } from '../trails/config-init.js';
 
 /**
- * Build a TrailContext with configService resolved in extensions.
+ * Build a TrailContext with configProvision resolved in extensions.
  */
 const buildCtx = (state: ConfigState): TrailContext => {
   const extensions = { config: state };
   const ctx: TrailContext = {
+    abortSignal: AbortSignal.timeout(5000),
     cwd: '/tmp',
     env: {},
     extensions,
+    provision: undefined as unknown as TrailContext['provision'],
     requestId: 'test',
-    service: undefined as unknown as TrailContext['service'],
-    signal: AbortSignal.timeout(5000),
     workspaceRoot: '/tmp',
   };
   const withLookup = {
     ...ctx,
-    service: createServiceLookup(() => withLookup),
+    provision: createProvisionLookup(() => withLookup),
   };
   return withLookup;
 };
@@ -55,17 +55,17 @@ describe('config.init trail', () => {
       expect(configInit.intent).toBe('write');
     });
 
-    test('has infrastructure metadata', () => {
-      expect(configInit.metadata).toEqual({ category: 'infrastructure' });
+    test('has infrastructure meta', () => {
+      expect(configInit.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has output schema', () => {
       expect(configInit.output).toBeDefined();
     });
 
-    test('declares configService dependency', () => {
-      expect(configInit.services).toBeDefined();
-      expect(configInit.services?.length).toBe(1);
+    test('declares configProvision dependency', () => {
+      expect(configInit.provisions).toBeDefined();
+      expect(configInit.provisions?.length).toBe(1);
     });
   });
 
@@ -78,7 +78,7 @@ describe('config.init trail', () => {
   describe('wired behavior', () => {
     test('generates TOML output by default', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'toml' }, ctx);
+      const result = await configInit.blaze({ format: 'toml' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -90,7 +90,7 @@ describe('config.init trail', () => {
 
     test('generates JSON output when requested', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'json' }, ctx);
+      const result = await configInit.blaze({ format: 'json' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -101,7 +101,7 @@ describe('config.init trail', () => {
 
     test('generates YAML output when requested', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'yaml' }, ctx);
+      const result = await configInit.blaze({ format: 'yaml' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -111,7 +111,7 @@ describe('config.init trail', () => {
 
     test('generates JSONC output when requested', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'jsonc' }, ctx);
+      const result = await configInit.blaze({ format: 'jsonc' }, ctx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap();
@@ -121,7 +121,7 @@ describe('config.init trail', () => {
 
     test('output content is non-empty for schema with fields', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'toml' }, ctx);
+      const result = await configInit.blaze({ format: 'toml' }, ctx);
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap().content.trim().length).toBeGreaterThan(0);
@@ -129,7 +129,7 @@ describe('config.init trail', () => {
 
     test('returns content without writtenFiles when dir is not provided', async () => {
       const ctx = buildCtx(testState);
-      const result = await configInit.run({ format: 'toml' }, ctx);
+      const result = await configInit.blaze({ format: 'toml' }, ctx);
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap().writtenFiles).toBeUndefined();
@@ -159,7 +159,7 @@ describe('config.init trail', () => {
 
     test('writes .schema.json when dir is provided', async () => {
       const ctx = buildCtx(envState);
-      const result = await configInit.run(
+      const result = await configInit.blaze(
         { dir: tempDir, format: 'toml' },
         ctx
       );
@@ -181,7 +181,7 @@ describe('config.init trail', () => {
 
     test('writes .env.example when schema has env bindings', async () => {
       const ctx = buildCtx(envState);
-      const result = await configInit.run(
+      const result = await configInit.blaze(
         { dir: tempDir, format: 'toml' },
         ctx
       );
@@ -196,7 +196,7 @@ describe('config.init trail', () => {
 
     test('still returns content alongside written files', async () => {
       const ctx = buildCtx(envState);
-      const result = await configInit.run(
+      const result = await configInit.blaze(
         { dir: tempDir, format: 'json' },
         ctx
       );

package/src/__tests__/{config-service.test.ts → config-provision.test.ts}

@@ -1,11 +1,11 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
-import { configService } from '../config-service.js';
+import { configProvision } from '../config-provision.js';
 import type { ConfigState } from '../registry.js';
 import { clearConfigState, registerConfigState } from '../registry.js';
 
-/** Stub ServiceContext for create calls. */
+/** Stub ProvisionContext for create calls. */
 const stubSvcCtx = {
   config: undefined,
   cwd: '/tmp',
@@ -13,32 +13,32 @@ const stubSvcCtx = {
   workspaceRoot: '/tmp',
 };
 
-describe('configService', () => {
+describe('configProvision', () => {
   afterEach(() => {
     clearConfigState();
   });
 
   describe('identity', () => {
     test('has id "config"', () => {
-      expect(configService.id).toBe('config');
+      expect(configProvision.id).toBe('config');
     });
 
-    test('has kind "service"', () => {
-      expect(configService.kind).toBe('service');
+    test('has kind "provision"', () => {
+      expect(configProvision.kind).toBe('provision');
     });
 
-    test('has infrastructure metadata', () => {
-      expect(configService.metadata).toEqual({ category: 'infrastructure' });
+    test('has infrastructure meta', () => {
+      expect(configProvision.meta).toEqual({ category: 'infrastructure' });
     });
 
     test('has description', () => {
-      expect(configService.description).toBeDefined();
+      expect(configProvision.description).toBeDefined();
     });
   });
 
   describe('mock', () => {
     test('returns a ConfigState with empty schema and resolved', () => {
-      const value = configService.mock?.() as ConfigState;
+      const value = configProvision.mock?.() as ConfigState;
       expect(value).toBeDefined();
       expect(value.resolved).toEqual({});
       expect(value.schema).toBeDefined();
@@ -51,7 +51,7 @@ describe('configService', () => {
       const state: ConfigState = { resolved: { port: 3000 }, schema };
       registerConfigState(state);
 
-      const result = await configService.create(stubSvcCtx);
+      const result = await configProvision.create(stubSvcCtx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap() as ConfigState;
@@ -69,7 +69,7 @@ describe('configService', () => {
       };
       registerConfigState(state);
 
-      const result = await configService.create(stubSvcCtx);
+      const result = await configProvision.create(stubSvcCtx);
 
       expect(result.isOk()).toBe(true);
       const value = result.unwrap() as ConfigState;
@@ -78,7 +78,7 @@ describe('configService', () => {
     });
 
     test('returns Result.err when no state is registered', async () => {
-      const result = await configService.create(stubSvcCtx);
+      const result = await configProvision.create(stubSvcCtx);
 
       expect(result.isErr()).toBe(true);
       expect(result.error.message).toContain('Config state not registered');

package/src/compose.ts

@@ -1,7 +1,7 @@
 /**
- * Config composition utilities for services.
+ * Config composition utilities for provisions.
  *
- * Collects config schemas from service declarations so they can be
+ * Collects config schemas from provision declarations so they can be
  * composed into a unified config structure via `defineConfig`.
  */
 
@@ -11,14 +11,17 @@ import type { z } from 'zod';
 // Types
 // ---------------------------------------------------------------------------
 
-/** A service config schema entry extracted from a service declaration. */
-export interface ServiceConfigEntry {
-  readonly serviceId: string;
+/** A provision config schema entry extracted from a provision declaration. */
+export interface ProvisionConfigEntry {
+  readonly provisionId: string;
   readonly schema: z.ZodType;
 }
 
-/** Minimal shape needed to extract config from a service-like object. */
-interface ServiceWithOptionalConfig {
+/** Backward-compatible alias while the migration is in flight. */
+export type ServiceConfigEntry = ProvisionConfigEntry;
+
+/** Minimal shape needed to extract config from a provision-like object. */
+interface ProvisionWithOptionalConfig {
   readonly id: string;
   readonly config?: z.ZodType | undefined;
 }
@@ -28,19 +31,22 @@ interface ServiceWithOptionalConfig {
 // ---------------------------------------------------------------------------
 
 /**
- * Collect config schemas from services that declare them.
+ * Collect config schemas from provisions that declare them.
  *
- * Returns entries keyed by service ID for composition into `defineConfig`.
- * Services without a `config` schema are excluded.
+ * Returns entries keyed by provision ID for composition into `defineConfig`.
+ * Provisions without a `config` schema are excluded.
  */
-export const collectServiceConfigs = (
-  services: readonly ServiceWithOptionalConfig[]
-): ServiceConfigEntry[] =>
-  services
+export const collectProvisionConfigs = (
+  provisions: readonly ProvisionWithOptionalConfig[]
+): ProvisionConfigEntry[] =>
+  provisions
     .filter(
       (
         svc
-      ): svc is ServiceWithOptionalConfig & { readonly config: z.ZodType } =>
+      ): svc is ProvisionWithOptionalConfig & { readonly config: z.ZodType } =>
         svc.config !== undefined
     )
-    .map((svc) => ({ schema: svc.config, serviceId: svc.id }));
+    .map((svc) => ({ provisionId: svc.id, schema: svc.config }));
+
+/** Backward-compatible alias while the migration is in flight. */
+export const collectServiceConfigs = collectProvisionConfigs;

package/src/config-gate.ts

@@ -0,0 +1,15 @@
+/**
+ * Config gate — attaches resolved config to the execution context.
+ *
+ * For v1, the gate is a pass-through: config resolution happens at
+ * bootstrap time and the provision pipeline (TRL-91) injects the resolved
+ * config before any trail runs. The gate reserves a named slot so future
+ * versions can add per-trail config overrides or validation.
+ */
+import type { Gate } from '@ontrails/core';
+
+export const configGate: Gate = {
+  description: 'Ensures resolved config is available in the execution context',
+  name: 'config',
+  wrap: (_trail, impl) => (input, ctx) => impl(input, ctx),
+};

package/src/{config-service.ts → config-provision.ts}

@@ -1,17 +1,17 @@
 /**
- * Config service — manages resolved config lifecycle.
+ * Config provision — manages resolved config lifecycle.
  *
  * The config is resolved during bootstrap (two-phase init per ADR-010)
- * and registered via `registerConfigState`. This service reads from the
- * global registry so trails can access it through `configService.from(ctx)`.
+ * and registered via `registerConfigState`. This provision reads from the
+ * global registry so trails can access it through `configProvision.from(ctx)`.
  */
-import { InternalError, Result, service } from '@ontrails/core';
+import { InternalError, Result, provision } from '@ontrails/core';
 import { z } from 'zod';
 
 import type { ConfigState } from './registry.js';
 import { getConfigState } from './registry.js';
 
-export const configService = service<ConfigState>('config', {
+export const configProvision = provision<ConfigState>('config', {
   create: () => {
     const state = getConfigState();
     if (state === undefined) {
@@ -24,7 +24,7 @@ export const configService = service<ConfigState>('config', {
     return Result.ok(state);
   },
   description: 'Resolved application configuration',
-  metadata: { category: 'infrastructure' },
+  meta: { category: 'infrastructure' },
   mock: (): ConfigState => ({
     resolved: {},
     schema: z.object({}),

package/src/explain.ts

@@ -64,8 +64,8 @@ const buildSecretSet = (
   return result;
 };
 
-/** Source layers in reverse precedence order for winner detection. */
-type SourceLayer = readonly [
+/** Source entries in reverse precedence order for winner detection. */
+type SourceEntry = readonly [
   name: ProvenanceEntry['source'],
   values: Record<string, unknown> | undefined,
 ];
@@ -74,7 +74,7 @@ type SourceLayer = readonly [
 const determineSource = (
   path: string,
   resolved: Record<string, unknown>,
-  layers: readonly SourceLayer[],
+  sources: readonly SourceEntry[],
   envMap: Map<string, string>,
   envVars: Record<string, string | undefined> | undefined
 ): ProvenanceEntry['source'] => {
@@ -86,7 +86,7 @@ const determineSource = (
   }
 
   const resolvedValue = getAtPath(resolved, path);
-  for (const [name, values] of layers) {
+  for (const [name, values] of sources) {
     if (values && getAtPath(values, path) === resolvedValue) {
       return name;
     }
@@ -144,7 +144,7 @@ export const explainConfig = <T extends z.ZodType>(
   const envMap = buildEnvMap(objSchema);
   const secretSet = buildSecretSet(objSchema);
 
-  const layers: readonly SourceLayer[] = [
+  const sources: readonly SourceEntry[] = [
     ['local', options.local],
     ['loadout', options.loadout],
     ['base', options.base],
@@ -156,7 +156,7 @@ export const explainConfig = <T extends z.ZodType>(
     const source = determineSource(
       path,
       options.resolved,
-      layers,
+      sources,
       envMap,
       options.env
     );

package/src/extensions.ts

@@ -34,7 +34,7 @@ export const secret = <T extends z.ZodType>(schema: T): T =>
  * standard key. We set `deprecated: true` so Zod-native tooling (schema
  * serializers, OpenAPI generators) recognises the field as deprecated, and store
  * the human-readable message under `deprecationMessage` for our own
- * `collectConfigMeta` / survey / explain surfaces.
+ * `collectConfigMeta` / survey / explain trailheads.
  *
  * Must be called BEFORE `.default()`, `.optional()`, or other transforms
  * so that the metadata lives on the inner type where `collectConfigMeta`

package/src/index.ts

@@ -7,7 +7,12 @@ export {
   type ResolveOptions,
 } from './app-config.js';
 export { collectConfigMeta } from './collect.js';
-export { collectServiceConfigs, type ServiceConfigEntry } from './compose.js';
+export {
+  collectProvisionConfigs,
+  collectServiceConfigs,
+  type ProvisionConfigEntry,
+  type ServiceConfigEntry,
+} from './compose.js';
 export { defineConfig, type DefineConfigOptions } from './define-config.js';
 export { describeConfig, type FieldDescription } from './describe.js';
 export {
@@ -26,8 +31,8 @@ export {
   generateExample,
   generateJsonSchema,
 } from './generate/index.js';
-export { configLayer } from './config-layer.js';
-export { configService } from './config-service.js';
+export { configGate } from './config-gate.js';
+export { configProvision } from './config-provision.js';
 export {
   clearConfigState,
   type ConfigState,

package/src/registry.ts

@@ -2,7 +2,7 @@
  * Module-level config state registry.
  *
  * Config is resolved once at bootstrap (two-phase init per ADR-010) and
- * registered here so `configService` can surface it to trails. This is
+ * registered here so `configProvision` can expose it to trailheads. This is
  * a process-level singleton — config resolution is inherently global.
  */
 import type { z } from 'zod';

package/src/trails/config-check.ts

@@ -7,7 +7,7 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { configService } from '../config-service.js';
+import { configProvision } from '../config-provision.js';
 import { checkConfig } from '../doctor.js';
 import { deepMerge } from '../merge.js';
 
@@ -32,6 +32,15 @@ const mergeValues = (
 };
 
 export const configCheck = trail('config.check', {
+  blaze: (input, ctx) => {
+    const state = configProvision.from(ctx);
+    const effective = mergeValues(state.resolved, input.values);
+    const checked = checkConfig(state.schema, effective);
+    return Result.ok({
+      diagnostics: [...checked.diagnostics],
+      valid: checked.valid,
+    });
+  },
   examples: [
     {
       input: {},
@@ -45,16 +54,7 @@ export const configCheck = trail('config.check', {
       .default({}),
   }),
   intent: 'read',
-  metadata: { category: 'infrastructure' },
+  meta: { category: 'infrastructure' },
   output: outputSchema,
-  run: (input, ctx) => {
-    const state = configService.from(ctx);
-    const effective = mergeValues(state.resolved, input.values);
-    const checked = checkConfig(state.schema, effective);
-    return Result.ok({
-      diagnostics: [...checked.diagnostics],
-      valid: checked.valid,
-    });
-  },
-  services: [configService],
+  provisions: [configProvision],
 });

package/src/trails/config-describe.ts

@@ -7,7 +7,7 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { configService } from '../config-service.js';
+import { configProvision } from '../config-provision.js';
 import { describeConfig } from '../describe.js';
 
 const fieldSchema = z.object({
@@ -25,6 +25,11 @@ const outputSchema = z.object({
 });
 
 export const configDescribe = trail('config.describe', {
+  blaze: (_input, ctx) => {
+    const state = configProvision.from(ctx);
+    const fields = describeConfig(state.schema);
+    return Result.ok({ fields: [...fields] });
+  },
   examples: [
     {
       input: {},
@@ -33,12 +38,7 @@ export const configDescribe = trail('config.describe', {
   ],
   input: z.object({}),
   intent: 'read',
-  metadata: { category: 'infrastructure' },
+  meta: { category: 'infrastructure' },
   output: outputSchema,
-  run: (_input, ctx) => {
-    const state = configService.from(ctx);
-    const fields = describeConfig(state.schema);
-    return Result.ok({ fields: [...fields] });
-  },
-  services: [configService],
+  provisions: [configProvision],
 });

package/src/trails/config-explain.ts

@@ -7,7 +7,7 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { configService } from '../config-service.js';
+import { configProvision } from '../config-provision.js';
 import type { ExplainConfigOptions } from '../explain.js';
 import { explainConfig } from '../explain.js';
 import type { ConfigState } from '../registry.js';
@@ -34,7 +34,7 @@ const filterByPath = (
       )
     : entries;
 
-/** Build ExplainConfigOptions from ConfigState, omitting undefined layers. */
+/** Build ExplainConfigOptions from ConfigState, omitting undefined source overrides. */
 const toExplainOptions = (
   state: ConfigState
 ): ExplainConfigOptions<typeof state.schema> => {
@@ -48,7 +48,7 @@ const toExplainOptions = (
   return base;
 };
 
-/** Enrich explain options with env and layer overrides from state. */
+/** Enrich explain options with env and source overrides from state. */
 const enrichOptions = (
   state: ConfigState,
   options: ExplainConfigOptions<typeof state.schema>
@@ -67,6 +67,13 @@ const enrichOptions = (
 };
 
 export const configExplain = trail('config.explain', {
+  blaze: (input, ctx) => {
+    const state = configProvision.from(ctx);
+    const options = enrichOptions(state, toExplainOptions(state));
+    const entries = explainConfig(options);
+    const filtered = filterByPath(entries, input.path);
+    return Result.ok({ entries: [...filtered] });
+  },
   examples: [
     {
       input: {},
@@ -80,14 +87,7 @@ export const configExplain = trail('config.explain', {
       .default(''),
   }),
   intent: 'read',
-  metadata: { category: 'infrastructure' },
+  meta: { category: 'infrastructure' },
   output: outputSchema,
-  run: (input, ctx) => {
-    const state = configService.from(ctx);
-    const options = enrichOptions(state, toExplainOptions(state));
-    const entries = explainConfig(options);
-    const filtered = filterByPath(entries, input.path);
-    return Result.ok({ entries: [...filtered] });
-  },
-  services: [configService],
+  provisions: [configProvision],
 });

package/src/trails/config-init.ts

@@ -14,7 +14,7 @@ import { Result, trail } from '@ontrails/core';
 import type { z } from 'zod';
 import { z as zod } from 'zod';
 
-import { configService } from '../config-service.js';
+import { configProvision } from '../config-provision.js';
 import {
   generateEnvExample,
   generateExample,
@@ -62,6 +62,18 @@ const writeArtifacts = async (
 };
 
 export const configInit = trail('config.init', {
+  blaze: async (input, ctx) => {
+    const state = configProvision.from(ctx);
+    const schema = state.schema as z.ZodObject<Record<string, z.ZodType>>;
+    const content = generateExample(schema, input.format);
+
+    if (input.dir) {
+      const writtenFiles = await writeArtifacts(input.dir, schema);
+      return Result.ok({ content, format: input.format, writtenFiles });
+    }
+
+    return Result.ok({ content, format: input.format });
+  },
   examples: [
     {
       input: {},
@@ -78,19 +90,7 @@ export const configInit = trail('config.init', {
       .default('toml'),
   }),
   intent: 'write',
-  metadata: { category: 'infrastructure' },
+  meta: { category: 'infrastructure' },
   output: outputSchema,
-  run: async (input, ctx) => {
-    const state = configService.from(ctx);
-    const schema = state.schema as z.ZodObject<Record<string, z.ZodType>>;
-    const content = generateExample(schema, input.format);
-
-    if (input.dir) {
-      const writtenFiles = await writeArtifacts(input.dir, schema);
-      return Result.ok({ content, format: input.format, writtenFiles });
-    }
-
-    return Result.ok({ content, format: input.format });
-  },
-  services: [configService],
+  provisions: [configProvision],
 });

package/src/config-layer.ts

@@ -1,15 +0,0 @@
-/**
- * Config layer — attaches resolved config to the execution context.
- *
- * For v1, the layer is a pass-through: config resolution happens at
- * bootstrap time and the service pipeline (TRL-91) injects the resolved
- * config before any trail runs. The layer reserves a named slot so
- * future versions can add per-trail config overrides or validation.
- */
-import type { Layer } from '@ontrails/core';
-
-export const configLayer: Layer = {
-  description: 'Ensures resolved config is available in the execution context',
-  name: 'config',
-  wrap: (_trail, impl) => (input, ctx) => impl(input, ctx),
-};