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

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,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';
 
@@ -85,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';
@@ -97,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 {

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

@@ -1,22 +1,22 @@
 /**
- * Service resolution pipeline.
+ * Provision resolution pipeline.
  *
  * Extracted from execute.ts to keep both modules under the 400 LOC ceiling.
  * Handles config validation, singleton caching, concurrent-creation dedup,
- * and the full resolve-or-create flow for declared services.
+ * and the full resolve-or-create flow for declared provisions.
  */
 
 import type {
-  AnyService,
-  ServiceContext,
-  ServiceOverrideMap,
-} from './service.js';
+  AnyProvision,
+  ProvisionContext,
+  ProvisionOverrideMap,
+} from './provision.js';
 import type { AnyTrail } from './trail.js';
 import type { TrailContext } from './types.js';
 
 import { InternalError, ValidationError } from './errors.js';
 import { Result } from './result.js';
-import { createServiceLookup } from './service.js';
+import { createProvisionLookup } from './provision.js';
 
 type MutableTrailContext = {
   -readonly [K in keyof TrailContext]: TrailContext[K];
@@ -28,11 +28,11 @@ type ConfigValues = Readonly<Record<string, Record<string, unknown>>>;
 // Singleton caches
 // ---------------------------------------------------------------------------
 
-const singletonServices = new WeakMap<AnyService, Map<string, unknown>>();
+const singletonProvisions = new WeakMap<AnyProvision, Map<string, unknown>>();
 
-/** In-flight service creation promises, keyed by service x context. */
+/** In-flight provision creation promises, keyed by provision x context. */
 const pendingCreations = new WeakMap<
-  AnyService,
+  AnyProvision,
   Map<string, Promise<Result<unknown, Error>>>
 >();
 
@@ -40,17 +40,17 @@ const pendingCreations = new WeakMap<
 // Context helpers
 // ---------------------------------------------------------------------------
 
-const toServiceContext = (
+const toProvisionContext = (
   ctx: TrailContext,
   config?: unknown
-): ServiceContext => ({
+): ProvisionContext => ({
   config,
   cwd: ctx.cwd,
   env: ctx.env,
   workspaceRoot: ctx.workspaceRoot,
 });
 
-const toServiceContextKey = (ctx: ServiceContext): string =>
+const toProvisionContextKey = (ctx: ProvisionContext): string =>
   JSON.stringify({
     config: ctx.config,
     cwd: ctx.cwd,
@@ -64,27 +64,27 @@ const toServiceContextKey = (ctx: ServiceContext): string =>
 // Config validation
 // ---------------------------------------------------------------------------
 
-/** Validate and resolve a service's config from the provided configValues map. */
-const resolveServiceConfig = (
-  declaredService: AnyService,
+/** Validate and resolve a provision's config from the provided configValues map. */
+const resolveProvisionConfig = (
+  declaredProvision: AnyProvision,
   configValues?: ConfigValues
 ): Result<unknown, Error> => {
-  if (declaredService.config === undefined) {
+  if (declaredProvision.config === undefined) {
     return Result.ok();
   }
-  const raw = configValues?.[declaredService.id];
+  const raw = configValues?.[declaredProvision.id];
   if (raw === undefined) {
     return Result.err(
       new ValidationError(
-        `Service "${declaredService.id}" declares a config schema but no config was provided`
+        `Provision "${declaredProvision.id}" declares a config schema but no config was provided`
       )
     );
   }
-  const parsed = declaredService.config.safeParse(raw);
+  const parsed = declaredProvision.config.safeParse(raw);
   if (!parsed.success) {
     return Result.err(
       new ValidationError(
-        `Service "${declaredService.id}" config validation failed: ${parsed.error.message}`
+        `Provision "${declaredProvision.id}" config validation failed: ${parsed.error.message}`
       )
     );
   }
@@ -95,22 +95,22 @@ const resolveServiceConfig = (
 // Override / cache lookups
 // ---------------------------------------------------------------------------
 
-const hasOwnServiceOverride = (
-  overrides: ServiceOverrideMap | undefined,
+const hasOwnProvisionOverride = (
+  overrides: ProvisionOverrideMap | undefined,
   id: string
-): overrides is ServiceOverrideMap =>
+): overrides is ProvisionOverrideMap =>
   overrides !== undefined && Object.hasOwn(overrides, id);
 
-const getCachedSingletonService = (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
+const getCachedSingletonProvision = (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
 ): { readonly found: boolean; readonly value: unknown } => {
-  const scopedCache = singletonServices.get(declaredService);
+  const scopedCache = singletonProvisions.get(declaredProvision);
   if (scopedCache === undefined) {
     return { found: false, value: undefined };
   }
 
-  const key = toServiceContextKey(serviceContext);
+  const key = toProvisionContextKey(provisionContext);
   if (!scopedCache.has(key)) {
     return { found: false, value: undefined };
   }
@@ -121,14 +121,14 @@ const getCachedSingletonService = (
   };
 };
 
-const getProvidedService = (
+const getProvidedProvision = (
   ctx: TrailContext,
-  overrides: ServiceOverrideMap | undefined,
-  declaredService: AnyService,
-  serviceContext: ServiceContext
+  overrides: ProvisionOverrideMap | undefined,
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
 ): Result<unknown, Error> | undefined => {
-  const { id } = declaredService;
-  if (hasOwnServiceOverride(overrides, id)) {
+  const { id } = declaredProvision;
+  if (hasOwnProvisionOverride(overrides, id)) {
     return Result.ok(overrides[id]);
   }
 
@@ -136,7 +136,10 @@ const getProvidedService = (
     return Result.ok(ctx.extensions?.[id]);
   }
 
-  const cached = getCachedSingletonService(declaredService, serviceContext);
+  const cached = getCachedSingletonProvision(
+    declaredProvision,
+    provisionContext
+  );
   if (cached.found) {
     return Result.ok(cached.value);
   }
@@ -146,200 +149,216 @@ const getProvidedService = (
 
 const getOverrideOrExtension = (
   ctx: TrailContext,
-  overrides: ServiceOverrideMap | undefined,
-  declaredService: AnyService
+  overrides: ProvisionOverrideMap | undefined,
+  declaredProvision: AnyProvision
 ): Result<unknown, Error> | undefined =>
-  getProvidedService(ctx, overrides, declaredService, toServiceContext(ctx));
+  getProvidedProvision(
+    ctx,
+    overrides,
+    declaredProvision,
+    toProvisionContext(ctx)
+  );
 
 type ConfigAwareResolution =
   | Result<{ readonly kind: 'provided'; readonly value: unknown }, Error>
   | Result<
-      { readonly kind: 'context'; readonly serviceContext: ServiceContext },
+      { readonly kind: 'context'; readonly provisionContext: ProvisionContext },
       Error
     >;
 
-const resolveConfigAwareProvidedService = (
+const resolveConfigAwareProvidedProvision = (
   ctx: TrailContext,
-  declaredService: AnyService,
+  declaredProvision: AnyProvision,
   configValues: ConfigValues | undefined
 ): ConfigAwareResolution => {
-  const configResult = resolveServiceConfig(declaredService, configValues);
+  const configResult = resolveProvisionConfig(declaredProvision, configValues);
   if (configResult.isErr()) {
     return configResult;
   }
 
-  const serviceContext = toServiceContext(ctx, configResult.value);
-  const provided = getProvidedService(
+  const provisionContext = toProvisionContext(ctx, configResult.value);
+  const provided = getProvidedProvision(
     ctx,
     undefined,
-    declaredService,
-    serviceContext
+    declaredProvision,
+    provisionContext
   );
 
   return provided
     ? Result.ok({ kind: 'provided', value: provided.unwrap() })
-    : Result.ok({ kind: 'context', serviceContext });
+    : Result.ok({ kind: 'context', provisionContext });
 };
 
 // ---------------------------------------------------------------------------
 // Instance creation
 // ---------------------------------------------------------------------------
 
-const toInternalServiceError = (id: string, error: unknown): InternalError => {
+const toInternalProvisionError = (
+  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}`, {
+  return new InternalError(`Provision "${id}" failed to resolve: ${message}`, {
     ...(cause ? { cause } : {}),
-    context: { serviceId: id },
+    context: { provisionId: id },
   });
 };
 
-const getSingletonServiceCache = (
-  declaredService: AnyService
+const getSingletonProvisionCache = (
+  declaredProvision: AnyProvision
 ): Map<string, unknown> => {
-  const existing = singletonServices.get(declaredService);
+  const existing = singletonProvisions.get(declaredProvision);
   if (existing !== undefined) {
     return existing;
   }
 
   const created = new Map<string, unknown>();
-  singletonServices.set(declaredService, created);
+  singletonProvisions.set(declaredProvision, created);
   return created;
 };
 
-const doCreateServiceInstance = async (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
+const doCreateProvisionInstance = async (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
 ): Promise<Result<unknown, Error>> => {
   try {
-    const created = await declaredService.create(serviceContext);
+    const created = await declaredProvision.create(provisionContext);
     if (created.isErr()) {
       return Result.err(created.error);
     }
 
     const instance = created.unwrap();
-    getSingletonServiceCache(declaredService).set(
-      toServiceContextKey(serviceContext),
+    getSingletonProvisionCache(declaredProvision).set(
+      toProvisionContextKey(provisionContext),
       instance
     );
     return Result.ok(instance);
   } catch (error: unknown) {
-    return Result.err(toInternalServiceError(declaredService.id, error));
+    return Result.err(toInternalProvisionError(declaredProvision.id, error));
   }
 };
 
 const trackPendingCreation = (
-  declaredService: AnyService,
+  declaredProvision: AnyProvision,
   key: string,
   promise: Promise<Result<unknown, Error>>
 ): void => {
-  const pending = pendingCreations.get(declaredService);
+  const pending = pendingCreations.get(declaredProvision);
   if (pending) {
     pending.set(key, promise);
   } else {
-    pendingCreations.set(declaredService, new Map([[key, promise]]));
+    pendingCreations.set(declaredProvision, new Map([[key, promise]]));
   }
 };
 
 /**
- * Deduplicates concurrent creation of the same service singleton.
- * If a creation is already in flight for this service x context key,
+ * Deduplicates concurrent creation of the same provision singleton.
+ * If a creation is already in flight for this provision x context key,
  * returns the existing promise instead of spawning a second factory call.
  */
-const createServiceInstance = async (
-  declaredService: AnyService,
-  serviceContext: ServiceContext
+const createProvisionInstance = async (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
 ): Promise<Result<unknown, Error>> => {
-  const key = toServiceContextKey(serviceContext);
-  const inflight = pendingCreations.get(declaredService)?.get(key);
+  const key = toProvisionContextKey(provisionContext);
+  const inflight = pendingCreations.get(declaredProvision)?.get(key);
   if (inflight) {
     return inflight;
   }
 
-  const promise = doCreateServiceInstance(declaredService, serviceContext);
-  trackPendingCreation(declaredService, key, promise);
+  const promise = doCreateProvisionInstance(
+    declaredProvision,
+    provisionContext
+  );
+  trackPendingCreation(declaredProvision, key, promise);
 
   try {
     return await promise;
   } finally {
-    pendingCreations.get(declaredService)?.delete(key);
+    pendingCreations.get(declaredProvision)?.delete(key);
   }
 };
 
-/** Validate config and resolve a single declared service. */
-const resolveDeclaredService = async (
-  declaredService: AnyService,
+/** Validate config and resolve a single declared provision. */
+const resolveDeclaredProvision = async (
+  declaredProvision: AnyProvision,
   ctx: TrailContext,
-  overrides: ServiceOverrideMap | undefined,
+  overrides: ProvisionOverrideMap | undefined,
   configValues: ConfigValues | undefined
 ): Promise<Result<unknown, Error>> => {
   // Check overrides/extensions first — skip config validation entirely when
-  // a service instance is already provided.
+  // a provision instance is already provided.
   const overrideOrExtension = getOverrideOrExtension(
     ctx,
     overrides,
-    declaredService
+    declaredProvision
   );
   if (overrideOrExtension !== undefined) {
     return overrideOrExtension;
   }
 
   // Resolve config before consulting the singleton cache so config-aware
-  // services use the same canonical context for cache reads and writes.
-  const configAwareService = resolveConfigAwareProvidedService(
+  // provisions use the same canonical context for cache reads and writes.
+  const configAwareProvision = resolveConfigAwareProvidedProvision(
     ctx,
-    declaredService,
+    declaredProvision,
     configValues
   );
-  if (configAwareService.isErr()) {
-    return configAwareService;
+  if (configAwareProvision.isErr()) {
+    return configAwareProvision;
   }
 
   // No provided instance — create via factory.
-  const resolved = configAwareService.unwrap();
+  const resolved = configAwareProvision.unwrap();
   if (resolved.kind === 'provided') {
     return Result.ok(resolved.value);
   }
 
-  return await createServiceInstance(declaredService, resolved.serviceContext);
+  return await createProvisionInstance(
+    declaredProvision,
+    resolved.provisionContext
+  );
 };
 
 // ---------------------------------------------------------------------------
-// Full trail service resolution
+// Full trail provision resolution
 // ---------------------------------------------------------------------------
 
-const withResolvedServices = (
+const withResolvedProvisions = (
   ctx: TrailContext,
-  resolvedServices: Record<string, unknown>
+  resolvedProvisions: Record<string, unknown>
 ): TrailContext => {
-  const extensions = { ...ctx.extensions, ...resolvedServices };
+  const extensions = { ...ctx.extensions, ...resolvedProvisions };
   const resolvedCtx = { ...ctx, extensions } as MutableTrailContext;
-  resolvedCtx.service = createServiceLookup(() => resolvedCtx);
+  const lookup = createProvisionLookup(() => resolvedCtx);
+  resolvedCtx.provision = lookup;
   return resolvedCtx;
 };
 
 /**
- * Resolve all declared services for a trail.
+ * Resolve all declared provisions for a trail.
  *
- * Validates per-service config, checks overrides and caches, and creates
- * new instances as needed. Returns an enriched context with all service
+ * Validates per-provision config, checks overrides and caches, and creates
+ * new instances as needed. Returns an enriched context with all provision
  * instances injected into extensions.
  */
-export const resolveServices = async (
+export const resolveProvisions = async (
   trail: AnyTrail,
   ctx: TrailContext,
-  overrides?: ServiceOverrideMap,
+  overrides?: ProvisionOverrideMap,
   configValues?: ConfigValues
 ): Promise<Result<TrailContext, Error>> => {
-  if (trail.services.length === 0) {
+  const { provisions } = trail;
+  if (provisions.length === 0) {
     return Result.ok(ctx);
   }
 
-  const resolvedServices: Record<string, unknown> = {};
+  const resolvedProvisions: Record<string, unknown> = {};
 
-  for (const declaredService of trail.services) {
-    const resolved = await resolveDeclaredService(
-      declaredService,
+  for (const declaredProvision of provisions) {
+    const resolved = await resolveDeclaredProvision(
+      declaredProvision,
       ctx,
       overrides,
       configValues
@@ -347,8 +366,8 @@ export const resolveServices = async (
     if (resolved.isErr()) {
       return resolved;
     }
-    resolvedServices[declaredService.id] = resolved.unwrap();
+    resolvedProvisions[declaredProvision.id] = resolved.unwrap();
   }
 
-  return Result.ok(withResolvedServices(ctx, resolvedServices));
+  return Result.ok(withResolvedProvisions(ctx, resolvedProvisions));
 };