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

package/src/provision-config.ts

@@ -0,0 +1,373 @@
+/**
+ * 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 provisions.
+ */
+
+import type {
+  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 { createProvisionLookup } from './provision.js';
+
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
+type ConfigValues = Readonly<Record<string, Record<string, unknown>>>;
+
+// ---------------------------------------------------------------------------
+// Singleton caches
+// ---------------------------------------------------------------------------
+
+const singletonProvisions = new WeakMap<AnyProvision, Map<string, unknown>>();
+
+/** In-flight provision creation promises, keyed by provision x context. */
+const pendingCreations = new WeakMap<
+  AnyProvision,
+  Map<string, Promise<Result<unknown, Error>>>
+>();
+
+// ---------------------------------------------------------------------------
+// Context helpers
+// ---------------------------------------------------------------------------
+
+const toProvisionContext = (
+  ctx: TrailContext,
+  config?: unknown
+): ProvisionContext => ({
+  config,
+  cwd: ctx.cwd,
+  env: ctx.env,
+  workspaceRoot: ctx.workspaceRoot,
+});
+
+const toProvisionContextKey = (ctx: ProvisionContext): string =>
+  JSON.stringify({
+    config: ctx.config,
+    cwd: ctx.cwd,
+    env: Object.entries(ctx.env ?? {}).toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    ),
+    workspaceRoot: ctx.workspaceRoot,
+  });
+
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+
+/** Validate and resolve a provision's config from the provided configValues map. */
+const resolveProvisionConfig = (
+  declaredProvision: AnyProvision,
+  configValues?: ConfigValues
+): Result<unknown, Error> => {
+  if (declaredProvision.config === undefined) {
+    return Result.ok();
+  }
+  const raw = configValues?.[declaredProvision.id];
+  if (raw === undefined) {
+    return Result.err(
+      new ValidationError(
+        `Provision "${declaredProvision.id}" declares a config schema but no config was provided`
+      )
+    );
+  }
+  const parsed = declaredProvision.config.safeParse(raw);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError(
+        `Provision "${declaredProvision.id}" config validation failed: ${parsed.error.message}`
+      )
+    );
+  }
+  return Result.ok(parsed.data);
+};
+
+// ---------------------------------------------------------------------------
+// Override / cache lookups
+// ---------------------------------------------------------------------------
+
+const hasOwnProvisionOverride = (
+  overrides: ProvisionOverrideMap | undefined,
+  id: string
+): overrides is ProvisionOverrideMap =>
+  overrides !== undefined && Object.hasOwn(overrides, id);
+
+const getCachedSingletonProvision = (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
+): { readonly found: boolean; readonly value: unknown } => {
+  const scopedCache = singletonProvisions.get(declaredProvision);
+  if (scopedCache === undefined) {
+    return { found: false, value: undefined };
+  }
+
+  const key = toProvisionContextKey(provisionContext);
+  if (!scopedCache.has(key)) {
+    return { found: false, value: undefined };
+  }
+
+  return {
+    found: true,
+    value: scopedCache.get(key),
+  };
+};
+
+const getProvidedProvision = (
+  ctx: TrailContext,
+  overrides: ProvisionOverrideMap | undefined,
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
+): Result<unknown, Error> | undefined => {
+  const { id } = declaredProvision;
+  if (hasOwnProvisionOverride(overrides, id)) {
+    return Result.ok(overrides[id]);
+  }
+
+  if (Object.hasOwn(ctx.extensions ?? {}, id)) {
+    return Result.ok(ctx.extensions?.[id]);
+  }
+
+  const cached = getCachedSingletonProvision(
+    declaredProvision,
+    provisionContext
+  );
+  if (cached.found) {
+    return Result.ok(cached.value);
+  }
+
+  return undefined;
+};
+
+const getOverrideOrExtension = (
+  ctx: TrailContext,
+  overrides: ProvisionOverrideMap | undefined,
+  declaredProvision: AnyProvision
+): Result<unknown, Error> | undefined =>
+  getProvidedProvision(
+    ctx,
+    overrides,
+    declaredProvision,
+    toProvisionContext(ctx)
+  );
+
+type ConfigAwareResolution =
+  | Result<{ readonly kind: 'provided'; readonly value: unknown }, Error>
+  | Result<
+      { readonly kind: 'context'; readonly provisionContext: ProvisionContext },
+      Error
+    >;
+
+const resolveConfigAwareProvidedProvision = (
+  ctx: TrailContext,
+  declaredProvision: AnyProvision,
+  configValues: ConfigValues | undefined
+): ConfigAwareResolution => {
+  const configResult = resolveProvisionConfig(declaredProvision, configValues);
+  if (configResult.isErr()) {
+    return configResult;
+  }
+
+  const provisionContext = toProvisionContext(ctx, configResult.value);
+  const provided = getProvidedProvision(
+    ctx,
+    undefined,
+    declaredProvision,
+    provisionContext
+  );
+
+  return provided
+    ? Result.ok({ kind: 'provided', value: provided.unwrap() })
+    : Result.ok({ kind: 'context', provisionContext });
+};
+
+// ---------------------------------------------------------------------------
+// Instance creation
+// ---------------------------------------------------------------------------
+
+const toInternalProvisionError = (
+  id: string,
+  error: unknown
+): InternalError => {
+  const cause = error instanceof Error ? error : undefined;
+  const message = cause?.message ?? String(error);
+  return new InternalError(`Provision "${id}" failed to resolve: ${message}`, {
+    ...(cause ? { cause } : {}),
+    context: { provisionId: id },
+  });
+};
+
+const getSingletonProvisionCache = (
+  declaredProvision: AnyProvision
+): Map<string, unknown> => {
+  const existing = singletonProvisions.get(declaredProvision);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = new Map<string, unknown>();
+  singletonProvisions.set(declaredProvision, created);
+  return created;
+};
+
+const doCreateProvisionInstance = async (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
+): Promise<Result<unknown, Error>> => {
+  try {
+    const created = await declaredProvision.create(provisionContext);
+    if (created.isErr()) {
+      return Result.err(created.error);
+    }
+
+    const instance = created.unwrap();
+    getSingletonProvisionCache(declaredProvision).set(
+      toProvisionContextKey(provisionContext),
+      instance
+    );
+    return Result.ok(instance);
+  } catch (error: unknown) {
+    return Result.err(toInternalProvisionError(declaredProvision.id, error));
+  }
+};
+
+const trackPendingCreation = (
+  declaredProvision: AnyProvision,
+  key: string,
+  promise: Promise<Result<unknown, Error>>
+): void => {
+  const pending = pendingCreations.get(declaredProvision);
+  if (pending) {
+    pending.set(key, promise);
+  } else {
+    pendingCreations.set(declaredProvision, new Map([[key, promise]]));
+  }
+};
+
+/**
+ * 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 createProvisionInstance = async (
+  declaredProvision: AnyProvision,
+  provisionContext: ProvisionContext
+): Promise<Result<unknown, Error>> => {
+  const key = toProvisionContextKey(provisionContext);
+  const inflight = pendingCreations.get(declaredProvision)?.get(key);
+  if (inflight) {
+    return inflight;
+  }
+
+  const promise = doCreateProvisionInstance(
+    declaredProvision,
+    provisionContext
+  );
+  trackPendingCreation(declaredProvision, key, promise);
+
+  try {
+    return await promise;
+  } finally {
+    pendingCreations.get(declaredProvision)?.delete(key);
+  }
+};
+
+/** Validate config and resolve a single declared provision. */
+const resolveDeclaredProvision = async (
+  declaredProvision: AnyProvision,
+  ctx: TrailContext,
+  overrides: ProvisionOverrideMap | undefined,
+  configValues: ConfigValues | undefined
+): Promise<Result<unknown, Error>> => {
+  // Check overrides/extensions first — skip config validation entirely when
+  // a provision instance is already provided.
+  const overrideOrExtension = getOverrideOrExtension(
+    ctx,
+    overrides,
+    declaredProvision
+  );
+  if (overrideOrExtension !== undefined) {
+    return overrideOrExtension;
+  }
+
+  // Resolve config before consulting the singleton cache so config-aware
+  // provisions use the same canonical context for cache reads and writes.
+  const configAwareProvision = resolveConfigAwareProvidedProvision(
+    ctx,
+    declaredProvision,
+    configValues
+  );
+  if (configAwareProvision.isErr()) {
+    return configAwareProvision;
+  }
+
+  // No provided instance — create via factory.
+  const resolved = configAwareProvision.unwrap();
+  if (resolved.kind === 'provided') {
+    return Result.ok(resolved.value);
+  }
+
+  return await createProvisionInstance(
+    declaredProvision,
+    resolved.provisionContext
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Full trail provision resolution
+// ---------------------------------------------------------------------------
+
+const withResolvedProvisions = (
+  ctx: TrailContext,
+  resolvedProvisions: Record<string, unknown>
+): TrailContext => {
+  const extensions = { ...ctx.extensions, ...resolvedProvisions };
+  const resolvedCtx = { ...ctx, extensions } as MutableTrailContext;
+  const lookup = createProvisionLookup(() => resolvedCtx);
+  resolvedCtx.provision = lookup;
+  return resolvedCtx;
+};
+
+/**
+ * Resolve all declared provisions for a trail.
+ *
+ * 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 resolveProvisions = async (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  overrides?: ProvisionOverrideMap,
+  configValues?: ConfigValues
+): Promise<Result<TrailContext, Error>> => {
+  const { provisions } = trail;
+  if (provisions.length === 0) {
+    return Result.ok(ctx);
+  }
+
+  const resolvedProvisions: Record<string, unknown> = {};
+
+  for (const declaredProvision of provisions) {
+    const resolved = await resolveDeclaredProvision(
+      declaredProvision,
+      ctx,
+      overrides,
+      configValues
+    );
+    if (resolved.isErr()) {
+      return resolved;
+    }
+    resolvedProvisions[declaredProvision.id] = resolved.unwrap();
+  }
+
+  return Result.ok(withResolvedProvisions(ctx, resolvedProvisions));
+};

package/src/provision.ts

@@ -0,0 +1,148 @@
+import { NotFoundError } from './errors.js';
+import type { Result } from './result.js';
+import type { ProvisionLookup, TrailContext } from './types.js';
+import type { z } from 'zod';
+
+/**
+ * Stable process-scoped fields available when constructing a provision.
+ *
+ * Provisions are app-level singletons, so they intentionally do not receive
+ * the full per-request TrailContext. When a provision declares a `config` schema,
+ * the validated config is passed as `svc.config`.
+ */
+export type ProvisionContext<C = unknown> = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+> & {
+  readonly config: C;
+};
+
+/**
+ * Everything needed to describe a provision before a factory is introduced.
+ *
+ * When `config` is a Zod schema, the `create` callback receives
+ * `ProvisionContext<C>` with the validated config value.
+ */
+export interface ProvisionSpec<T, C = unknown> {
+  /** Create the provision instance from stable process-scoped context. */
+  readonly create: (
+    svc: ProvisionContext<C>
+  ) => Result<T, Error> | Promise<Result<T, Error>>;
+  /** Config schema — when present, config is validated and passed to `create`. */
+  readonly config?: z.ZodType<C> | undefined;
+  /** Optional cleanup performed when the hosting trailhead shuts down. */
+  readonly dispose?: ((provision: T) => void | Promise<void>) | undefined;
+  /** Optional operational readiness probe for introspection tooling. */
+  readonly health?:
+    | ((
+        provision: T
+      ) => Result<unknown, Error> | Promise<Result<unknown, Error>>)
+    | undefined;
+  /** Optional test factory used by higher-level helpers. */
+  readonly mock?: (() => T | Promise<T>) | undefined;
+  /** Human-readable description. */
+  readonly description?: string | undefined;
+  /** Arbitrary meta for tooling and filtering. */
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** A typed provision definition. */
+export interface Provision<T> extends ProvisionSpec<T> {
+  readonly kind: 'provision';
+  readonly id: string;
+  /** Read the resolved provision instance from a trail context. */
+  from(ctx: TrailContext): T;
+}
+
+/**
+ * Existential type for heterogeneous provision collections.
+ *
+ * `Provision<T>` includes function parameters in `dispose`/`health`, so
+ * `unknown` is too narrow for mixed provision arrays. `any` is the correct
+ * existential here.
+ */
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous provision collections
+export type AnyProvision = Provision<any>;
+
+/** Explicit runtime overrides keyed by provision ID. */
+export type ProvisionOverrideMap = Readonly<Record<string, unknown>>;
+
+const getProvisionId = <T>(
+  provisionOrId: string | Pick<Provision<T>, 'id'>
+): string =>
+  typeof provisionOrId === 'string' ? provisionOrId : provisionOrId.id;
+
+const getProvisionInstance = <T>(
+  ctx: Pick<TrailContext, 'extensions'>,
+  provisionOrId: string | Pick<Provision<T>, 'id'>
+): T => {
+  const id = getProvisionId(provisionOrId);
+  return ctx.extensions?.[id] as T;
+};
+
+const hasProvisionInstance = (
+  ctx: Pick<TrailContext, 'extensions'>,
+  provisionOrId: string | Pick<AnyProvision, 'id'>
+): boolean =>
+  Object.hasOwn(ctx.extensions ?? {}, getProvisionId(provisionOrId));
+
+/** Create a `ctx.provision(...)` accessor bound to a concrete context snapshot. */
+export const createProvisionLookup = (
+  getContext: () => Pick<TrailContext, 'extensions'>
+): ProvisionLookup =>
+  ((provisionOrId: string | Pick<AnyProvision, 'id'>) => {
+    const id = getProvisionId(provisionOrId);
+    const ctx = getContext();
+    if (!hasProvisionInstance(ctx, id)) {
+      throw new NotFoundError(`Provision "${id}" not found in trail context`);
+    }
+    return getProvisionInstance(ctx, id);
+  }) as ProvisionLookup;
+
+/**
+ * Create a typed provision definition.
+ *
+ * The provision object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export const provision = <T>(
+  id: string,
+  spec: ProvisionSpec<T>
+): Provision<T> =>
+  Object.freeze({
+    ...spec,
+    from(ctx: TrailContext): T {
+      const lookup = ctx.provision ?? createProvisionLookup(() => ctx);
+      return lookup(this);
+    },
+    id,
+    kind: 'provision' as const,
+  });
+
+/** Narrow unknown values to provision definitions during topo discovery. */
+export const isProvision = (value: unknown): value is AnyProvision => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as { kind?: unknown; id?: unknown };
+  return v.kind === 'provision' && typeof v.id === 'string';
+};
+
+/**
+ * Return the first duplicate provision ID in a collection, if any.
+ *
+ * This supports later topo registration without each caller duplicating the
+ * same scan logic.
+ */
+export const findDuplicateProvisionId = (
+  provisions: readonly Pick<AnyProvision, 'id'>[]
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const candidate of provisions) {
+    if (seen.has(candidate.id)) {
+      return candidate.id;
+    }
+    seen.add(candidate.id);
+  }
+  return undefined;
+};

package/src/{dispatch.ts → run.ts}

@@ -1,5 +1,5 @@
 /**
- * Headless trail execution — the "no-surface" surface.
+ * Headless trail execution without mounting a trailhead.
  *
  * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
  * Returns a `Result` and never throws.
@@ -15,15 +15,15 @@ import { Result } from './result.js';
 // Options
 // ---------------------------------------------------------------------------
 
-/** Options forwarded to `executeTrail` from `dispatch`. */
-export type DispatchOptions = ExecuteTrailOptions;
+/** Options forwarded to `executeTrail` from `run`. */
+export type RunOptions = ExecuteTrailOptions;
 
 // ---------------------------------------------------------------------------
-// dispatch()
+// run()
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a trail by ID from a topo without mounting a surface.
+ * Execute a trail by ID from a topo without mounting a trailhead.
  *
  * Resolves the trail from the topo, then runs it through the standard
  * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
@@ -32,15 +32,15 @@ export type DispatchOptions = ExecuteTrailOptions;
  *
  * @example
  * ```typescript
- * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * const result = await run(myTopo, 'greet', { name: 'Alice' });
  * if (result.isOk()) console.log(result.value);
  * ```
  */
-export const dispatch = (
+export const run = (
   topo: Topo,
   id: string,
   input: unknown,
-  options?: DispatchOptions
+  options?: RunOptions
 ): Promise<Result<unknown, Error>> => {
   const trail = topo.get(id);
   if (trail === undefined) {

package/src/signal.ts

@@ -0,0 +1,65 @@
+/**
+ * Signal — a named payload schema with optional provenance meta.
+ */
+
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Spec (input to the factory)
+// ---------------------------------------------------------------------------
+
+export interface SignalSpec<T> {
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this signal (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shape (output of the factory)
+// ---------------------------------------------------------------------------
+
+export interface Signal<T> {
+  readonly id: string;
+  readonly kind: 'signal';
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this signal (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a signal definition.
+ *
+ * A signal is a named payload schema describing something that happened.
+ * Returns a frozen object with `kind: "signal"` and all spec fields.
+ */
+export function signal<T>(id: string, spec: SignalSpec<T>): Signal<T>;
+export function signal<T>(
+  spec: SignalSpec<T> & { readonly id: string }
+): Signal<T>;
+export function signal<T>(
+  idOrSpec: string | (SignalSpec<T> & { readonly id: string }),
+  maybeSpec?: SignalSpec<T>
+): Signal<T> {
+  const resolvedId = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const resolvedSpec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  return Object.freeze({
+    description: resolvedSpec.description,
+    from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
+    id: resolvedId,
+    kind: 'signal' as const,
+    meta: resolvedSpec.meta,
+    payload: resolvedSpec.payload,
+  });
+}
+
+/** Existential type for heterogeneous signal collections */
+export type AnySignal = Signal<unknown>;