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

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/workspace.ts

@@ -20,6 +20,11 @@ const GITIGNORE_CONTENT = [
   '# Generated artifacts',
   'generated/',
   '',
+  '# Shared Trails database',
+  'trails.db',
+  'trails.db-shm',
+  'trails.db-wal',
+  '',
 ].join('\n');
 
 /**

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/app-config.ts","./src/collect.ts","./src/compose.ts","./src/config-layer.ts","./src/config-service.ts","./src/define-config.ts","./src/describe.ts","./src/doctor.ts","./src/explain.ts","./src/extensions.ts","./src/index.ts","./src/merge.ts","./src/ref.ts","./src/registry.ts","./src/resolve.ts","./src/secret-heuristics.ts","./src/workspace.ts","./src/zod-utils.ts","./src/generate/env.ts","./src/generate/example.ts","./src/generate/helpers.ts","./src/generate/index.ts","./src/generate/json-schema.ts","./src/trails/config-check.ts","./src/trails/config-describe.ts","./src/trails/config-explain.ts","./src/trails/config-init.ts"],"version":"5.9.3"}
+{"root":["./src/app-config.ts","./src/collect.ts","./src/compose.ts","./src/config-gate.ts","./src/config-provision.ts","./src/define-config.ts","./src/describe.ts","./src/doctor.ts","./src/explain.ts","./src/extensions.ts","./src/index.ts","./src/merge.ts","./src/ref.ts","./src/registry.ts","./src/resolve.ts","./src/secret-heuristics.ts","./src/workspace.ts","./src/zod-utils.ts","./src/generate/env.ts","./src/generate/example.ts","./src/generate/helpers.ts","./src/generate/index.ts","./src/generate/json-schema.ts","./src/trails/config-check.ts","./src/trails/config-describe.ts","./src/trails/config-explain.ts","./src/trails/config-init.ts"],"version":"5.9.3"}

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),
-};