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

package/src/execute.ts

@@ -1,22 +1,22 @@
 /**
  * Centralized trail execution pipeline.
  *
- * Validates input, builds context, composes layers, and runs the
+ * Validates input, builds context, composes gates, and runs the
  * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
  * of reimplementing the pipeline.
  */
 
 import type { AnyTrail } from './trail.js';
-import type { Layer } from './layer.js';
-import type { ServiceOverrideMap } from './service.js';
+import type { Gate } from './gate.js';
+import type { ProvisionOverrideMap } from './provision.js';
 import type { TrailContext, TrailContextInit } from './types.js';
 
-import { composeLayers } from './layer.js';
+import { composeGates } from './gate.js';
 import { createTrailContext } from './context.js';
 import { InternalError } from './errors.js';
 import { Result } from './result.js';
-import { createServiceLookup } from './service.js';
-import { resolveServices } from './service-config.js';
+import { createProvisionLookup } from './provision.js';
+import { resolveProvisions } from './provision-config.js';
 import { validateInput } from './validation.js';
 
 type MutableTrailContext = {
@@ -32,16 +32,16 @@ export interface ExecuteTrailOptions {
   /** Partial context overrides merged on top of the base context. */
   readonly ctx?: Partial<TrailContextInit> | undefined;
   /** AbortSignal override (takes final precedence over ctx and factory). */
-  readonly signal?: AbortSignal | undefined;
-  /** Layers to compose around the implementation. */
-  readonly layers?: readonly Layer[] | undefined;
+  readonly abortSignal?: AbortSignal | undefined;
+  /** Gates to compose around the implementation. */
+  readonly gates?: readonly Gate[] | undefined;
   /** Factory that produces a base TrailContext (takes precedence over defaults). */
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  /** Explicit service instance overrides keyed by service ID. */
-  readonly services?: ServiceOverrideMap | undefined;
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  /** Explicit provision instance overrides keyed by provision ID. */
+  readonly provisions?: ProvisionOverrideMap | undefined;
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
@@ -51,21 +51,10 @@ export interface ExecuteTrailOptions {
 // Context resolution
 // ---------------------------------------------------------------------------
 
-/**
- * Build a TrailContext from options.
- *
- * Resolution order:
- * 1. Factory (`createContext`) or `createTrailContext()` defaults.
- * 2. Partial `ctx` overrides merged on top.
- * 3. `signal` override takes final precedence.
- */
-const resolveContext = async (
+const applyContextOverrides = (
+  base: TrailContextInit,
   options?: ExecuteTrailOptions
-): Promise<TrailContext> => {
-  const seed = options?.createContext
-    ? await options.createContext()
-    : createTrailContext();
-  const base = seed.service ? seed : createTrailContext(seed);
+): TrailContextInit => {
   const withOverrides = options?.ctx
     ? {
         ...base,
@@ -73,19 +62,46 @@ const resolveContext = async (
         extensions: { ...base.extensions, ...options.ctx.extensions },
       }
     : base;
-  const resolved = options?.signal
-    ? { ...withOverrides, signal: options.signal }
+
+  return options?.abortSignal
+    ? { ...withOverrides, abortSignal: options.abortSignal }
     : withOverrides;
+};
+
+const bindProvisionLookup = (
+  resolved: TrailContextInit,
+  options?: ExecuteTrailOptions
+): TrailContext => {
   if (
-    options?.ctx?.extensions !== undefined ||
-    resolved.service === undefined
+    options?.ctx?.extensions === undefined &&
+    resolved.provision !== undefined
   ) {
-    const bound = { ...resolved } as MutableTrailContext;
-    bound.service = createServiceLookup(() => bound);
-    return bound;
+    return resolved as TrailContext;
   }
 
-  return resolved as TrailContext;
+  const bound = { ...resolved } as MutableTrailContext;
+  const lookup = createProvisionLookup(() => bound);
+  bound.provision = lookup;
+  return bound;
+};
+
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `abortSignal` override takes final precedence.
+ */
+const resolveContext = async (
+  options?: ExecuteTrailOptions
+): Promise<TrailContext> => {
+  const seed = options?.createContext
+    ? await options.createContext()
+    : createTrailContext();
+  const base = seed.provision ? seed : createTrailContext(seed);
+  const resolved = applyContextOverrides(base, options);
+  return bindProvisionLookup(resolved, options);
 };
 
 const prepareContext = async (
@@ -93,10 +109,10 @@ const prepareContext = async (
   options?: ExecuteTrailOptions
 ): Promise<Result<TrailContext, Error>> => {
   const baseCtx = await resolveContext(options);
-  return await resolveServices(
+  return await resolveProvisions(
     trail,
     baseCtx,
-    options?.services,
+    options?.provisions,
     options?.configValues
   );
 };
@@ -105,9 +121,9 @@ const runTrail = async (
   trail: AnyTrail,
   input: unknown,
   ctx: TrailContext,
-  layers: readonly Layer[]
+  gates: readonly Gate[]
 ): Promise<Result<unknown, Error>> => {
-  const impl = composeLayers([...layers], trail, trail.run);
+  const impl = composeGates([...gates], trail, trail.blaze);
   return await impl(input, ctx);
 };
 
@@ -116,7 +132,7 @@ const runTrail = async (
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a trail through the standard validate-context-layers-run pipeline.
+ * Execute a trail through the standard validate-context-gates-run pipeline.
  *
  * The function never throws -- unexpected exceptions are caught and
  * returned as `Result.err(InternalError)`.
@@ -141,7 +157,7 @@ export const executeTrail = async (
       trail,
       validated.value,
       resolvedCtx.value,
-      options?.layers ?? []
+      options?.gates ?? []
     );
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/src/{layer.ts → gate.ts}

@@ -2,15 +2,15 @@ import type { Trail } from './trail.js';
 import type { Implementation } from './types.js';
 
 // ---------------------------------------------------------------------------
-// Layer interface
+// Gate interface
 // ---------------------------------------------------------------------------
 
-/** A composable middleware that wraps trail implementations */
-export interface Layer {
+/** A composable gate that wraps trail implementations. */
+export interface Gate {
   readonly name: string;
   readonly description?: string | undefined;
 
-  /** Wrap a trail's implementation, returning a new implementation */
+  /** Wrap a trail's implementation, returning a new implementation. */
   wrap<I, O>(
     trail: Trail<I, O>,
     implementation: Implementation<I, O>
@@ -22,22 +22,22 @@ export interface Layer {
 // ---------------------------------------------------------------------------
 
 /**
- * Apply layers outermost-first: layers[0] wraps layers[1] wraps ... wraps
+ * Apply gates outermost-first: gates[0] wraps gates[1] wraps ... wraps
  * the base implementation.
  *
- * An empty layers array returns the implementation unchanged.
+ * An empty gates array returns the implementation unchanged.
  */
-export const composeLayers = <I, O>(
-  layers: readonly Layer[],
+export const composeGates = <I, O>(
+  gates: readonly Gate[],
   trail: Trail<I, O>,
   implementation: Implementation<I, O>
 ): Implementation<I, O> => {
-  // Fold right so layers[0] is the outermost wrapper
+  // Fold right so gates[0] is the outermost wrapper.
   let result = implementation;
-  for (let i = layers.length - 1; i >= 0; i -= 1) {
-    const layer = layers[i];
-    if (layer) {
-      result = layer.wrap(trail, result);
+  for (let i = gates.length - 1; i >= 0; i -= 1) {
+    const gate = gates[i];
+    if (gate) {
+      result = gate.wrap(trail, result);
     }
   }
   return result;

package/src/index.ts

@@ -31,33 +31,33 @@ export type {
   Implementation,
   TrailContext,
   TrailContextInit,
-  FollowFn,
+  CrossFn,
   BasePermit,
   PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
-  ServiceLookup,
+  ProvisionLookup,
 } from './types.js';
-export { SURFACE_KEY } from './types.js';
+export { TRAILHEAD_KEY } from './types.js';
 
 // Context factory
 export { createTrailContext } from './context.js';
 
-// Service
+// Provision
 export {
-  createServiceLookup,
-  findDuplicateServiceId,
-  isService,
-  service,
-} from './service.js';
+  createProvisionLookup,
+  findDuplicateProvisionId,
+  isProvision,
+  provision,
+} from './provision.js';
 export type {
-  AnyService,
-  Service,
-  ServiceContext,
-  ServiceOverrideMap,
-  ServiceSpec,
-} from './service.js';
+  AnyProvision,
+  Provision,
+  ProvisionContext,
+  ProvisionOverrideMap,
+  ProvisionSpec,
+} from './provision.js';
 
 // Trail
 export { trail } from './trail.js';
@@ -73,33 +73,64 @@ export type {
 export type { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
 export { inputOf, outputOf } from './type-utils.js';
 
-// Event
+// Signal
+export { signal } from './signal.js';
+export type { AnySignal, Signal, SignalSpec } from './signal.js';
 export { event } from './event.js';
 export type { AnyEvent, Event, EventSpec } from './event.js';
 
 // Topo
 export { topo } from './topo.js';
 export type { Topo } from './topo.js';
+export {
+  createMockTopoStore,
+  createTopoStore,
+  topoStore,
+} from './topo-store.js';
+export type {
+  MockTopoStoreSeed,
+  ReadOnlyTopoStore,
+  TopoStoreExportRecord,
+  TopoStoreProvisionRecord,
+  TopoStoreRef,
+  TopoStoreTrailDetailRecord,
+  TopoStoreTrailRecord,
+} from './topo-store.js';
+
+// Draft state
+export {
+  DRAFT_ID_PREFIX,
+  analyzeDraftState,
+  isDraftId,
+  validateEstablishedTopo as validateDraftFreeTopo,
+} from './draft.js';
+export type {
+  DraftDependency,
+  DraftDependencyKind,
+  DraftFinding,
+  DraftStateAnalysis,
+} from './draft.js';
 
 // Topo validation
 export { validateTopo } from './validate-topo.js';
 export type { TopoIssue } from './validate-topo.js';
+export { validateEstablishedTopo } from './validate-established-topo.js';
 
-// Layer
-export { composeLayers } from './layer.js';
-export type { Layer } from './layer.js';
+// Gate
+export { composeGates } from './gate.js';
+export type { Gate } from './gate.js';
 
 // Derive
-export { deriveFields } from './derive.js';
+export { deriveCliPath, deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
 // Execute
 export { executeTrail } from './execute.js';
 export type { ExecuteTrailOptions } from './execute.js';
 
-// Dispatch
-export { dispatch } from './dispatch.js';
-export type { DispatchOptions } from './dispatch.js';
+// Run
+export { run } from './run.js';
+export type { RunOptions } from './run.js';
 
 // Validation
 export {