@ontrails/core 1.0.0-beta.11 → 1.0.0-beta.13

package/src/execute.ts

@@ -1,25 +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 {
-  AnyService,
-  ServiceContext,
-  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 { createProvisionLookup } from './provision.js';
+import { resolveProvisions } from './provision-config.js';
 import { validateInput } from './validation.js';
 
 type MutableTrailContext = {
@@ -35,36 +32,29 @@ 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;
+  /** 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;
 }
 
 // ---------------------------------------------------------------------------
 // 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,
@@ -72,220 +62,46 @@ const resolveContext = async (
         extensions: { ...base.extensions, ...options.ctx.extensions },
       }
     : base;
-  const resolved = options?.signal
-    ? { ...withOverrides, signal: options.signal }
-    : withOverrides;
-  if (
-    options?.ctx?.extensions !== undefined ||
-    resolved.service === undefined
-  ) {
-    const bound = { ...resolved } as MutableTrailContext;
-    bound.service = createServiceLookup(() => bound);
-    return bound;
-  }
-
-  return resolved as TrailContext;
-};
-
-const singletonServices = new WeakMap<AnyService, Map<string, unknown>>();
-
-/** In-flight service creation promises, keyed by service × context. */
-const pendingCreations = new WeakMap<
-  AnyService,
-  Map<string, Promise<Result<unknown, Error>>>
->();
-
-const hasOwnServiceOverride = (
-  overrides: ServiceOverrideMap | undefined,
-  id: string
-): overrides is ServiceOverrideMap =>
-  overrides !== undefined && Object.hasOwn(overrides, id);
-
-const toServiceContext = (ctx: TrailContext): ServiceContext => ({
-  cwd: ctx.cwd,
-  env: ctx.env,
-  workspaceRoot: ctx.workspaceRoot,
-});
 
-const toServiceContextKey = (ctx: ServiceContext): string =>
-  JSON.stringify({
-    cwd: ctx.cwd,
-    env: Object.entries(ctx.env ?? {}).toSorted(([left], [right]) =>
-      left.localeCompare(right)
-    ),
-    workspaceRoot: ctx.workspaceRoot,
-  });
-
-const toInternalServiceError = (id: string, error: unknown): InternalError => {
-  const cause = error instanceof Error ? error : undefined;
-  const message = cause?.message ?? String(error);
-  return new InternalError(`Service "${id}" failed to resolve: ${message}`, {
-    ...(cause ? { cause } : {}),
-    context: { serviceId: id },
-  });
-};
-
-const getCachedSingletonService = (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
-): { readonly found: boolean; readonly value: unknown } => {
-  const scopedCache = singletonServices.get(declaredService);
-  if (scopedCache === undefined) {
-    return { found: false, value: undefined };
-  }
-
-  const key = toServiceContextKey(serviceContext);
-  if (!scopedCache.has(key)) {
-    return { found: false, value: undefined };
-  }
-
-  return {
-    found: true,
-    value: scopedCache.get(key),
-  };
-};
-
-const getProvidedService = (
-  ctx: TrailContext,
-  overrides: ServiceOverrideMap | undefined,
-  declaredService: AnyService,
-  serviceContext: ServiceContext
-): Result<unknown, Error> | undefined => {
-  const { id } = declaredService;
-  if (hasOwnServiceOverride(overrides, id)) {
-    return Result.ok(overrides[id]);
-  }
-
-  if (Object.hasOwn(ctx.extensions ?? {}, id)) {
-    return Result.ok(ctx.extensions?.[id]);
-  }
-
-  const cached = getCachedSingletonService(declaredService, serviceContext);
-  if (cached.found) {
-    return Result.ok(cached.value);
-  }
-
-  return undefined;
-};
-
-const getSingletonServiceCache = (
-  declaredService: AnyService
-): Map<string, unknown> => {
-  const existing = singletonServices.get(declaredService);
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const created = new Map<string, unknown>();
-  singletonServices.set(declaredService, created);
-  return created;
+  return options?.abortSignal
+    ? { ...withOverrides, abortSignal: options.abortSignal }
+    : withOverrides;
 };
 
-const doCreateServiceInstance = async (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
-): Promise<Result<unknown, Error>> => {
-  try {
-    const created = await declaredService.create(serviceContext);
-    if (created.isErr()) {
-      return Result.err(created.error);
-    }
-
-    const instance = created.unwrap();
-    getSingletonServiceCache(declaredService).set(
-      toServiceContextKey(serviceContext),
-      instance
-    );
-    return Result.ok(instance);
-  } catch (error: unknown) {
-    return Result.err(toInternalServiceError(declaredService.id, error));
+const bindProvisionLookup = (
+  resolved: TrailContextInit,
+  options?: ExecuteTrailOptions
+): TrailContext => {
+  if (
+    options?.ctx?.extensions === undefined &&
+    resolved.provision !== undefined
+  ) {
+    return resolved as TrailContext;
   }
-};
 
-const trackPendingCreation = (
-  declaredService: AnyService,
-  key: string,
-  promise: Promise<Result<unknown, Error>>
-): void => {
-  const pending = pendingCreations.get(declaredService);
-  if (pending) {
-    pending.set(key, promise);
-  } else {
-    pendingCreations.set(declaredService, new Map([[key, promise]]));
-  }
+  const bound = { ...resolved } as MutableTrailContext;
+  const lookup = createProvisionLookup(() => bound);
+  bound.provision = lookup;
+  return bound;
 };
 
 /**
- * Deduplicates concurrent creation of the same service singleton.
- * If a creation is already in flight for this service × context key,
- * returns the existing promise instead of spawning a second factory call.
+ * 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 createServiceInstance = async (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
-): Promise<Result<unknown, Error>> => {
-  const key = toServiceContextKey(serviceContext);
-  const inflight = pendingCreations.get(declaredService)?.get(key);
-  if (inflight) {
-    return inflight;
-  }
-
-  const promise = doCreateServiceInstance(declaredService, serviceContext);
-  trackPendingCreation(declaredService, key, promise);
-
-  try {
-    return await promise;
-  } finally {
-    pendingCreations.get(declaredService)?.delete(key);
-  }
-};
-
-const resolveServiceInstance = async (
-  declaredService: AnyService,
-  ctx: TrailContext,
-  serviceContext: ServiceContext,
-  overrides?: ServiceOverrideMap
-): Promise<Result<unknown, Error>> =>
-  getProvidedService(ctx, overrides, declaredService, serviceContext) ??
-  (await createServiceInstance(declaredService, serviceContext));
-
-const withResolvedServices = (
-  ctx: TrailContext,
-  resolvedServices: Record<string, unknown>
-): TrailContext => {
-  const extensions = { ...ctx.extensions, ...resolvedServices };
-  const resolvedCtx = { ...ctx, extensions } as MutableTrailContext;
-  resolvedCtx.service = createServiceLookup(() => resolvedCtx);
-  return resolvedCtx;
-};
-
-const resolveServices = async (
-  trail: AnyTrail,
-  ctx: TrailContext,
-  overrides?: ServiceOverrideMap
-): Promise<Result<TrailContext, Error>> => {
-  if (trail.services.length === 0) {
-    return Result.ok(ctx);
-  }
-
-  const resolvedServices: Record<string, unknown> = {};
-  const serviceContext = toServiceContext(ctx);
-
-  for (const declaredService of trail.services) {
-    const resolved = await resolveServiceInstance(
-      declaredService,
-      ctx,
-      serviceContext,
-      overrides
-    );
-    if (resolved.isErr()) {
-      return resolved;
-    }
-
-    resolvedServices[declaredService.id] = resolved.unwrap();
-  }
-
-  return Result.ok(withResolvedServices(ctx, resolvedServices));
+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 (
@@ -293,16 +109,21 @@ const prepareContext = async (
   options?: ExecuteTrailOptions
 ): Promise<Result<TrailContext, Error>> => {
   const baseCtx = await resolveContext(options);
-  return await resolveServices(trail, baseCtx, options?.services);
+  return await resolveProvisions(
+    trail,
+    baseCtx,
+    options?.provisions,
+    options?.configValues
+  );
 };
 
 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);
 };
 
@@ -311,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)`.
@@ -336,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,30 +31,33 @@ export type {
   Implementation,
   TrailContext,
   TrailContextInit,
-  FollowFn,
+  CrossFn,
+  BasePermit,
+  PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
-  ServiceLookup,
+  ProvisionLookup,
 } 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';
@@ -70,7 +73,9 @@ 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';
 
@@ -82,9 +87,9 @@ export type { Topo } from './topo.js';
 export { validateTopo } from './validate-topo.js';
 export type { TopoIssue } from './validate-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';
@@ -94,9 +99,9 @@ export type { Field, FieldOverride } from './derive.js';
 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 {