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

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

@@ -1,22 +1,22 @@
 /**
- * Provision resolution pipeline.
+ * Resource 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.
+ * and the full resolve-or-create flow for declared resources.
  */
 
 import type {
-  AnyProvision,
-  ProvisionContext,
-  ProvisionOverrideMap,
-} from './provision.js';
+  AnyResource,
+  ResourceContext,
+  ResourceOverrideMap,
+} from './resource.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';
+import { createResourceLookup } from './resource.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 singletonProvisions = new WeakMap<AnyProvision, Map<string, unknown>>();
+const singletonResources = new WeakMap<AnyResource, Map<string, unknown>>();
 
-/** In-flight provision creation promises, keyed by provision x context. */
+/** In-flight resource creation promises, keyed by resource x context. */
 const pendingCreations = new WeakMap<
-  AnyProvision,
+  AnyResource,
   Map<string, Promise<Result<unknown, Error>>>
 >();
 
@@ -40,17 +40,17 @@ const pendingCreations = new WeakMap<
 // Context helpers
 // ---------------------------------------------------------------------------
 
-const toProvisionContext = (
+const toResourceContext = (
   ctx: TrailContext,
   config?: unknown
-): ProvisionContext => ({
+): ResourceContext => ({
   config,
   cwd: ctx.cwd,
   env: ctx.env,
   workspaceRoot: ctx.workspaceRoot,
 });
 
-const toProvisionContextKey = (ctx: ProvisionContext): string =>
+const toResourceContextKey = (ctx: ResourceContext): string =>
   JSON.stringify({
     config: ctx.config,
     cwd: ctx.cwd,
@@ -64,27 +64,27 @@ const toProvisionContextKey = (ctx: ProvisionContext): string =>
 // Config validation
 // ---------------------------------------------------------------------------
 
-/** Validate and resolve a provision's config from the provided configValues map. */
-const resolveProvisionConfig = (
-  declaredProvision: AnyProvision,
+/** Validate and resolve a resource's config from the provided configValues map. */
+const resolveResourceConfig = (
+  declaredResource: AnyResource,
   configValues?: ConfigValues
 ): Result<unknown, Error> => {
-  if (declaredProvision.config === undefined) {
+  if (declaredResource.config === undefined) {
     return Result.ok();
   }
-  const raw = configValues?.[declaredProvision.id];
+  const raw = configValues?.[declaredResource.id];
   if (raw === undefined) {
     return Result.err(
       new ValidationError(
-        `Provision "${declaredProvision.id}" declares a config schema but no config was provided`
+        `Resource "${declaredResource.id}" declares a config schema but no config was provided`
       )
     );
   }
-  const parsed = declaredProvision.config.safeParse(raw);
+  const parsed = declaredResource.config.safeParse(raw);
   if (!parsed.success) {
     return Result.err(
       new ValidationError(
-        `Provision "${declaredProvision.id}" config validation failed: ${parsed.error.message}`
+        `Resource "${declaredResource.id}" config validation failed: ${parsed.error.message}`
       )
     );
   }
@@ -95,22 +95,22 @@ const resolveProvisionConfig = (
 // Override / cache lookups
 // ---------------------------------------------------------------------------
 
-const hasOwnProvisionOverride = (
-  overrides: ProvisionOverrideMap | undefined,
+const hasOwnResourceOverride = (
+  overrides: ResourceOverrideMap | undefined,
   id: string
-): overrides is ProvisionOverrideMap =>
+): overrides is ResourceOverrideMap =>
   overrides !== undefined && Object.hasOwn(overrides, id);
 
-const getCachedSingletonProvision = (
-  declaredProvision: AnyProvision,
-  provisionContext: ProvisionContext
+const getCachedSingletonResource = (
+  declaredResource: AnyResource,
+  resourceContext: ResourceContext
 ): { readonly found: boolean; readonly value: unknown } => {
-  const scopedCache = singletonProvisions.get(declaredProvision);
+  const scopedCache = singletonResources.get(declaredResource);
   if (scopedCache === undefined) {
     return { found: false, value: undefined };
   }
 
-  const key = toProvisionContextKey(provisionContext);
+  const key = toResourceContextKey(resourceContext);
   if (!scopedCache.has(key)) {
     return { found: false, value: undefined };
   }
@@ -121,14 +121,14 @@ const getCachedSingletonProvision = (
   };
 };
 
-const getProvidedProvision = (
+const getProvidedResource = (
   ctx: TrailContext,
-  overrides: ProvisionOverrideMap | undefined,
-  declaredProvision: AnyProvision,
-  provisionContext: ProvisionContext
+  overrides: ResourceOverrideMap | undefined,
+  declaredResource: AnyResource,
+  resourceContext: ResourceContext
 ): Result<unknown, Error> | undefined => {
-  const { id } = declaredProvision;
-  if (hasOwnProvisionOverride(overrides, id)) {
+  const { id } = declaredResource;
+  if (hasOwnResourceOverride(overrides, id)) {
     return Result.ok(overrides[id]);
   }
 
@@ -136,10 +136,7 @@ const getProvidedProvision = (
     return Result.ok(ctx.extensions?.[id]);
   }
 
-  const cached = getCachedSingletonProvision(
-    declaredProvision,
-    provisionContext
-  );
+  const cached = getCachedSingletonResource(declaredResource, resourceContext);
   if (cached.found) {
     return Result.ok(cached.value);
   }
@@ -149,216 +146,205 @@ const getProvidedProvision = (
 
 const getOverrideOrExtension = (
   ctx: TrailContext,
-  overrides: ProvisionOverrideMap | undefined,
-  declaredProvision: AnyProvision
+  overrides: ResourceOverrideMap | undefined,
+  declaredResource: AnyResource
 ): Result<unknown, Error> | undefined =>
-  getProvidedProvision(
-    ctx,
-    overrides,
-    declaredProvision,
-    toProvisionContext(ctx)
-  );
+  getProvidedResource(ctx, overrides, declaredResource, toResourceContext(ctx));
 
 type ConfigAwareResolution =
   | Result<{ readonly kind: 'provided'; readonly value: unknown }, Error>
   | Result<
-      { readonly kind: 'context'; readonly provisionContext: ProvisionContext },
+      { readonly kind: 'context'; readonly resourceContext: ResourceContext },
       Error
     >;
 
-const resolveConfigAwareProvidedProvision = (
+const resolveConfigAwareProvidedResource = (
   ctx: TrailContext,
-  declaredProvision: AnyProvision,
+  declaredResource: AnyResource,
   configValues: ConfigValues | undefined
 ): ConfigAwareResolution => {
-  const configResult = resolveProvisionConfig(declaredProvision, configValues);
+  const configResult = resolveResourceConfig(declaredResource, configValues);
   if (configResult.isErr()) {
     return configResult;
   }
 
-  const provisionContext = toProvisionContext(ctx, configResult.value);
-  const provided = getProvidedProvision(
+  const resourceContext = toResourceContext(ctx, configResult.value);
+  const provided = getProvidedResource(
     ctx,
     undefined,
-    declaredProvision,
-    provisionContext
+    declaredResource,
+    resourceContext
   );
 
   return provided
     ? Result.ok({ kind: 'provided', value: provided.unwrap() })
-    : Result.ok({ kind: 'context', provisionContext });
+    : Result.ok({ kind: 'context', resourceContext });
 };
 
 // ---------------------------------------------------------------------------
 // Instance creation
 // ---------------------------------------------------------------------------
 
-const toInternalProvisionError = (
-  id: string,
-  error: unknown
-): InternalError => {
+const toInternalResourceError = (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}`, {
+  return new InternalError(`Resource "${id}" failed to resolve: ${message}`, {
     ...(cause ? { cause } : {}),
-    context: { provisionId: id },
+    context: { resourceId: id },
   });
 };
 
-const getSingletonProvisionCache = (
-  declaredProvision: AnyProvision
+const getSingletonResourceCache = (
+  declaredResource: AnyResource
 ): Map<string, unknown> => {
-  const existing = singletonProvisions.get(declaredProvision);
+  const existing = singletonResources.get(declaredResource);
   if (existing !== undefined) {
     return existing;
   }
 
   const created = new Map<string, unknown>();
-  singletonProvisions.set(declaredProvision, created);
+  singletonResources.set(declaredResource, created);
   return created;
 };
 
-const doCreateProvisionInstance = async (
-  declaredProvision: AnyProvision,
-  provisionContext: ProvisionContext
+const doCreateResourceInstance = async (
+  declaredResource: AnyResource,
+  resourceContext: ResourceContext
 ): Promise<Result<unknown, Error>> => {
   try {
-    const created = await declaredProvision.create(provisionContext);
+    const created = await declaredResource.create(resourceContext);
     if (created.isErr()) {
       return Result.err(created.error);
     }
 
     const instance = created.unwrap();
-    getSingletonProvisionCache(declaredProvision).set(
-      toProvisionContextKey(provisionContext),
+    getSingletonResourceCache(declaredResource).set(
+      toResourceContextKey(resourceContext),
       instance
     );
     return Result.ok(instance);
   } catch (error: unknown) {
-    return Result.err(toInternalProvisionError(declaredProvision.id, error));
+    return Result.err(toInternalResourceError(declaredResource.id, error));
   }
 };
 
 const trackPendingCreation = (
-  declaredProvision: AnyProvision,
+  declaredResource: AnyResource,
   key: string,
   promise: Promise<Result<unknown, Error>>
 ): void => {
-  const pending = pendingCreations.get(declaredProvision);
+  const pending = pendingCreations.get(declaredResource);
   if (pending) {
     pending.set(key, promise);
   } else {
-    pendingCreations.set(declaredProvision, new Map([[key, promise]]));
+    pendingCreations.set(declaredResource, 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,
+ * Deduplicates concurrent creation of the same resource singleton.
+ * If a creation is already in flight for this resource x context key,
  * returns the existing promise instead of spawning a second factory call.
  */
-const createProvisionInstance = async (
-  declaredProvision: AnyProvision,
-  provisionContext: ProvisionContext
+const createResourceInstance = async (
+  declaredResource: AnyResource,
+  resourceContext: ResourceContext
 ): Promise<Result<unknown, Error>> => {
-  const key = toProvisionContextKey(provisionContext);
-  const inflight = pendingCreations.get(declaredProvision)?.get(key);
+  const key = toResourceContextKey(resourceContext);
+  const inflight = pendingCreations.get(declaredResource)?.get(key);
   if (inflight) {
     return inflight;
   }
 
-  const promise = doCreateProvisionInstance(
-    declaredProvision,
-    provisionContext
-  );
-  trackPendingCreation(declaredProvision, key, promise);
+  const promise = doCreateResourceInstance(declaredResource, resourceContext);
+  trackPendingCreation(declaredResource, key, promise);
 
   try {
     return await promise;
   } finally {
-    pendingCreations.get(declaredProvision)?.delete(key);
+    pendingCreations.get(declaredResource)?.delete(key);
   }
 };
 
-/** Validate config and resolve a single declared provision. */
-const resolveDeclaredProvision = async (
-  declaredProvision: AnyProvision,
+/** Validate config and resolve a single declared resource. */
+const resolveDeclaredResource = async (
+  declaredResource: AnyResource,
   ctx: TrailContext,
-  overrides: ProvisionOverrideMap | undefined,
+  overrides: ResourceOverrideMap | undefined,
   configValues: ConfigValues | undefined
 ): Promise<Result<unknown, Error>> => {
   // Check overrides/extensions first — skip config validation entirely when
-  // a provision instance is already provided.
+  // a resource instance is already provided.
   const overrideOrExtension = getOverrideOrExtension(
     ctx,
     overrides,
-    declaredProvision
+    declaredResource
   );
   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(
+  // resources use the same canonical context for cache reads and writes.
+  const configAwareResource = resolveConfigAwareProvidedResource(
     ctx,
-    declaredProvision,
+    declaredResource,
     configValues
   );
-  if (configAwareProvision.isErr()) {
-    return configAwareProvision;
+  if (configAwareResource.isErr()) {
+    return configAwareResource;
   }
 
   // No provided instance — create via factory.
-  const resolved = configAwareProvision.unwrap();
+  const resolved = configAwareResource.unwrap();
   if (resolved.kind === 'provided') {
     return Result.ok(resolved.value);
   }
 
-  return await createProvisionInstance(
-    declaredProvision,
-    resolved.provisionContext
+  return await createResourceInstance(
+    declaredResource,
+    resolved.resourceContext
   );
 };
 
 // ---------------------------------------------------------------------------
-// Full trail provision resolution
+// Full trail resource resolution
 // ---------------------------------------------------------------------------
 
-const withResolvedProvisions = (
+const withResolvedResources = (
   ctx: TrailContext,
-  resolvedProvisions: Record<string, unknown>
+  resolvedResources: Record<string, unknown>
 ): TrailContext => {
-  const extensions = { ...ctx.extensions, ...resolvedProvisions };
+  const extensions = { ...ctx.extensions, ...resolvedResources };
   const resolvedCtx = { ...ctx, extensions } as MutableTrailContext;
-  const lookup = createProvisionLookup(() => resolvedCtx);
-  resolvedCtx.provision = lookup;
+  const lookup = createResourceLookup(() => resolvedCtx);
+  resolvedCtx.resource = lookup;
   return resolvedCtx;
 };
 
 /**
- * Resolve all declared provisions for a trail.
+ * Resolve all declared resources for a trail.
  *
- * Validates per-provision config, checks overrides and caches, and creates
- * new instances as needed. Returns an enriched context with all provision
+ * Validates per-resource config, checks overrides and caches, and creates
+ * new instances as needed. Returns an enriched context with all resource
  * instances injected into extensions.
  */
-export const resolveProvisions = async (
+export const createResources = async (
   trail: AnyTrail,
   ctx: TrailContext,
-  overrides?: ProvisionOverrideMap,
+  overrides?: ResourceOverrideMap,
   configValues?: ConfigValues
 ): Promise<Result<TrailContext, Error>> => {
-  const { provisions } = trail;
-  if (provisions.length === 0) {
+  const { resources } = trail;
+  if (resources.length === 0) {
     return Result.ok(ctx);
   }
 
-  const resolvedProvisions: Record<string, unknown> = {};
+  const resolvedResources: Record<string, unknown> = {};
 
-  for (const declaredProvision of provisions) {
-    const resolved = await resolveDeclaredProvision(
-      declaredProvision,
+  for (const declaredResource of resources) {
+    const resolved = await resolveDeclaredResource(
+      declaredResource,
       ctx,
       overrides,
       configValues
@@ -366,8 +352,8 @@ export const resolveProvisions = async (
     if (resolved.isErr()) {
       return resolved;
     }
-    resolvedProvisions[declaredProvision.id] = resolved.unwrap();
+    resolvedResources[declaredResource.id] = resolved.unwrap();
   }
 
-  return Result.ok(withResolvedProvisions(ctx, resolvedProvisions));
+  return Result.ok(withResolvedResources(ctx, resolvedResources));
 };

package/src/resource.ts

@@ -0,0 +1,155 @@
+import { InternalError } from './errors.js';
+import type { Result } from './result.js';
+import type { AnySignal } from './signal.js';
+import type { ResourceLookup, TrailContext } from './types.js';
+import type { z } from 'zod';
+
+/**
+ * Stable process-scoped fields available when constructing a resource.
+ *
+ * Resources are app-level singletons, so they intentionally do not receive
+ * the full per-request TrailContext. When a resource declares a `config` schema,
+ * the validated config is passed as `svc.config`.
+ */
+export type ResourceContext<C = unknown> = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+> & {
+  readonly config: C;
+};
+
+/**
+ * Everything needed to describe a resource before a factory is introduced.
+ *
+ * When `config` is a Zod schema, the `create` callback receives
+ * `ResourceContext<C>` with the validated config value.
+ */
+export interface ResourceSpec<T, C = unknown> {
+  /** Create the resource instance from stable process-scoped context. */
+  readonly create: (
+    svc: ResourceContext<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?: ((resource: T) => void | Promise<void>) | undefined;
+  /** Optional operational readiness probe for introspection tooling. */
+  readonly health?:
+    | ((
+        resource: 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;
+  /** Signals projected or owned by this resource. */
+  readonly signals?: readonly AnySignal[] | undefined;
+}
+
+/** A typed resource definition. */
+export interface Resource<T> extends ResourceSpec<T> {
+  readonly kind: 'resource';
+  readonly id: string;
+  /** Read the resolved resource instance from a trail context. */
+  from(ctx: TrailContext): T;
+}
+
+/**
+ * Existential type for heterogeneous resource collections.
+ *
+ * `Resource<T>` includes function parameters in `dispose`/`health`, so
+ * `unknown` is too narrow for mixed resource arrays. `any` is the correct
+ * existential here.
+ */
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous resource collections
+export type AnyResource = Resource<any>;
+
+/** Explicit runtime overrides keyed by resource ID. */
+export type ResourceOverrideMap = Readonly<Record<string, unknown>>;
+
+const getResourceId = <T>(
+  resourceOrId: string | Pick<Resource<T>, 'id'>
+): string =>
+  typeof resourceOrId === 'string' ? resourceOrId : resourceOrId.id;
+
+const getResourceInstance = <T>(
+  ctx: Pick<TrailContext, 'extensions'>,
+  resourceOrId: string | Pick<Resource<T>, 'id'>
+): T => {
+  const id = getResourceId(resourceOrId);
+  return ctx.extensions?.[id] as T;
+};
+
+const hasResourceInstance = (
+  ctx: Pick<TrailContext, 'extensions'>,
+  resourceOrId: string | Pick<AnyResource, 'id'>
+): boolean => Object.hasOwn(ctx.extensions ?? {}, getResourceId(resourceOrId));
+
+/** Create a `ctx.resource(...)` accessor bound to a concrete context snapshot. */
+export const createResourceLookup = (
+  getContext: () => Pick<TrailContext, 'extensions'>
+): ResourceLookup =>
+  ((resourceOrId: string | Pick<AnyResource, 'id'>) => {
+    const id = getResourceId(resourceOrId);
+    const ctx = getContext();
+    if (!hasResourceInstance(ctx, id)) {
+      throw new InternalError(`Resource "${id}" not provisioned in context`);
+    }
+    return getResourceInstance(ctx, id);
+  }) as ResourceLookup;
+
+/**
+ * Create a typed resource definition.
+ *
+ * The resource object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export const resource = <T>(id: string, spec: ResourceSpec<T>): Resource<T> =>
+  (() => {
+    if (id.includes(':')) {
+      throw new InternalError(
+        `Resource "${id}" is invalid because resource ids may not contain ":"`
+      );
+    }
+
+    return Object.freeze({
+      ...spec,
+      from(ctx: TrailContext): T {
+        const lookup = ctx.resource ?? createResourceLookup(() => ctx);
+        return lookup(this);
+      },
+      id,
+      kind: 'resource' as const,
+    });
+  })();
+
+/** Narrow unknown values to resource definitions during topo discovery. */
+export const isResource = (value: unknown): value is AnyResource => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as { kind?: unknown; id?: unknown };
+  return v.kind === 'resource' && typeof v.id === 'string';
+};
+
+/**
+ * Return the first duplicate resource ID in a collection, if any.
+ *
+ * This supports later topo registration without each caller duplicating the
+ * same scan logic.
+ */
+export const findDuplicateResourceId = (
+  resources: readonly Pick<AnyResource, 'id'>[]
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const candidate of resources) {
+    if (seen.has(candidate.id)) {
+      return candidate.id;
+    }
+    seen.add(candidate.id);
+  }
+  return undefined;
+};

package/src/run.ts

@@ -26,9 +26,10 @@ export type RunOptions = ExecuteTrailOptions;
  * 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
- * trail ID is not registered. Never throws — unexpected exceptions are
- * returned as `Result.err(InternalError)`.
+ * `executeTrail` pipeline with `topo` threaded so `ctx.fire()` is bound
+ * to the producer's context inside `executeTrail`. Returns
+ * `Result.err(NotFoundError)` if the trail ID is not registered. Never
+ * throws — unexpected exceptions are returned as `Result.err(InternalError)`.
  *
  * @example
  * ```typescript
@@ -50,5 +51,5 @@ export const run = (
       )
     );
   }
-  return executeTrail(trail, input, options);
+  return executeTrail(trail, input, { ...options, topo });
 };

package/src/serialization.ts

@@ -18,6 +18,7 @@ import {
   RateLimitError,
   NetworkError,
   InternalError,
+  DerivationError,
   AuthError,
   CancelledError,
   isTrailsError,
@@ -100,6 +101,7 @@ const errorConstructorsByName: Record<string, ErrorFactory> = {
   AuthError: (msg, opts) => new AuthError(msg, opts),
   CancelledError: (msg, opts) => new CancelledError(msg, opts),
   ConflictError: (msg, opts) => new ConflictError(msg, opts),
+  DerivationError: (msg, opts) => new DerivationError(msg, opts),
   InternalError: (msg, opts) => new InternalError(msg, opts),
   NetworkError: (msg, opts) => new NetworkError(msg, opts),
   NotFoundError: (msg, opts) => new NotFoundError(msg, opts),