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

package/dist/provision-config.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { InternalError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+import { createProvisionLookup } from './provision.js';
+// ---------------------------------------------------------------------------
+// Singleton caches
+// ---------------------------------------------------------------------------
+const singletonProvisions = new WeakMap();
+/** In-flight provision creation promises, keyed by provision x context. */
+const pendingCreations = new WeakMap();
+// ---------------------------------------------------------------------------
+// Context helpers
+// ---------------------------------------------------------------------------
+const toProvisionContext = (ctx, config) => ({
+    config,
+    cwd: ctx.cwd,
+    env: ctx.env,
+    workspaceRoot: ctx.workspaceRoot,
+});
+const toProvisionContextKey = (ctx) => 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, configValues) => {
+    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, id) => overrides !== undefined && Object.hasOwn(overrides, id);
+const getCachedSingletonProvision = (declaredProvision, provisionContext) => {
+    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, overrides, declaredProvision, provisionContext) => {
+    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, overrides, declaredProvision) => getProvidedProvision(ctx, overrides, declaredProvision, toProvisionContext(ctx));
+const resolveConfigAwareProvidedProvision = (ctx, declaredProvision, configValues) => {
+    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, error) => {
+    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) => {
+    const existing = singletonProvisions.get(declaredProvision);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = new Map();
+    singletonProvisions.set(declaredProvision, created);
+    return created;
+};
+const doCreateProvisionInstance = async (declaredProvision, provisionContext) => {
+    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) {
+        return Result.err(toInternalProvisionError(declaredProvision.id, error));
+    }
+};
+const trackPendingCreation = (declaredProvision, key, promise) => {
+    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, provisionContext) => {
+    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, ctx, overrides, configValues) => {
+    // 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, resolvedProvisions) => {
+    const extensions = { ...ctx.extensions, ...resolvedProvisions };
+    const resolvedCtx = { ...ctx, extensions };
+    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, ctx, overrides, configValues) => {
+    const { provisions } = trail;
+    if (provisions.length === 0) {
+        return Result.ok(ctx);
+    }
+    const resolvedProvisions = {};
+    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));
+};
+//# sourceMappingURL=provision-config.js.map

package/dist/provision-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-config.js","sourceRoot":"","sources":["../src/provision-config.ts"],"names":[],"mappings":"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"}

package/dist/provision.d.ts

@@ -0,0 +1,71 @@
+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.
+ */
+export type AnyProvision = Provision<any>;
+/** Explicit runtime overrides keyed by provision ID. */
+export type ProvisionOverrideMap = Readonly<Record<string, unknown>>;
+/** Create a `ctx.provision(...)` accessor bound to a concrete context snapshot. */
+export declare const createProvisionLookup: (getContext: () => Pick<TrailContext, "extensions">) => ProvisionLookup;
+/**
+ * Create a typed provision definition.
+ *
+ * The provision object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export declare const provision: <T>(id: string, spec: ProvisionSpec<T>) => Provision<T>;
+/** Narrow unknown values to provision definitions during topo discovery. */
+export declare const isProvision: (value: unknown) => value is AnyProvision;
+/**
+ * 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 declare const findDuplicateProvisionId: (provisions: readonly Pick<AnyProvision, "id">[]) => string | undefined;
+//# sourceMappingURL=provision.d.ts.map

package/dist/provision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision.d.ts","sourceRoot":"","sources":["../src/provision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,IAAI,CAC9C,YAAY,EACZ,KAAK,GAAG,KAAK,GAAG,eAAe,CAChC,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,CACf,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KACrB,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IAClD,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IACxE,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EACZ,CAAC,CACC,SAAS,EAAE,CAAC,KACT,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,GAC9D,SAAS,CAAC;IACd,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACnD,kCAAkC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/D;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAS,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,CAAC,CAAC;CAC5B;AAED;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;AAE1C,wDAAwD;AACxD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAqBrE,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,GAChC,YAAY,MAAM,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,KACjD,eAQoB,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EACzB,IAAI,MAAM,EACV,MAAM,aAAa,CAAC,CAAC,CAAC,KACrB,SAAS,CAAC,CAAC,CASV,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,YAMrD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,YAAY,SAAS,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,KAC9C,MAAM,GAAG,SASX,CAAC"}

package/dist/provision.js

@@ -0,0 +1,56 @@
+import { NotFoundError } from './errors.js';
+const getProvisionId = (provisionOrId) => typeof provisionOrId === 'string' ? provisionOrId : provisionOrId.id;
+const getProvisionInstance = (ctx, provisionOrId) => {
+    const id = getProvisionId(provisionOrId);
+    return ctx.extensions?.[id];
+};
+const hasProvisionInstance = (ctx, provisionOrId) => Object.hasOwn(ctx.extensions ?? {}, getProvisionId(provisionOrId));
+/** Create a `ctx.provision(...)` accessor bound to a concrete context snapshot. */
+export const createProvisionLookup = (getContext) => ((provisionOrId) => {
+    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);
+});
+/**
+ * Create a typed provision definition.
+ *
+ * The provision object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export const provision = (id, spec) => Object.freeze({
+    ...spec,
+    from(ctx) {
+        const lookup = ctx.provision ?? createProvisionLookup(() => ctx);
+        return lookup(this);
+    },
+    id,
+    kind: 'provision',
+});
+/** Narrow unknown values to provision definitions during topo discovery. */
+export const isProvision = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    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) => {
+    const seen = new Set();
+    for (const candidate of provisions) {
+        if (seen.has(candidate.id)) {
+            return candidate.id;
+        }
+        seen.add(candidate.id);
+    }
+    return undefined;
+};
+//# sourceMappingURL=provision.js.map

package/dist/provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision.js","sourceRoot":"","sources":["../src/provision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqE5C,MAAM,cAAc,GAAG,CACrB,aAAgD,EACxC,EAAE,CACV,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC;AAEvE,MAAM,oBAAoB,GAAG,CAC3B,GAAqC,EACrC,aAAgD,EAC7C,EAAE;IACL,MAAM,EAAE,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC,EAAE,CAAM,CAAC;AACnC,CAAC,CAAC;AAEF,MAAM,oBAAoB,GAAG,CAC3B,GAAqC,EACrC,aAAgD,EACvC,EAAE,CACX,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;AAErE,mFAAmF;AACnF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,UAAkD,EACjC,EAAE,CACnB,CAAC,CAAC,aAAgD,EAAE,EAAE;IACpD,MAAM,EAAE,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,aAAa,CAAC,cAAc,EAAE,8BAA8B,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,oBAAoB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC,CAAoB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,EAAU,EACV,IAAsB,EACR,EAAE,CAChB,MAAM,CAAC,MAAM,CAAC;IACZ,GAAG,IAAI;IACP,IAAI,CAAC,GAAiB;QACpB,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,IAAI,qBAAqB,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,EAAE;IACF,IAAI,EAAE,WAAoB;CAC3B,CAAC,CAAC;AAEL,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAAyB,EAAE;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,CAAC,GAAG,KAAyC,CAAC;IACpD,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC;AAC5D,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,UAA+C,EAC3B,EAAE;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+import type { Topo } from './topo.js';
+import type { ExecuteTrailOptions } from './execute.js';
+import { Result } from './result.js';
+/** Options forwarded to `executeTrail` from `run`. */
+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)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await run(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export declare const run: (topo: Topo, id: string, input: unknown, options?: RunOptions) => Promise<Result<unknown, Error>>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAMrC,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAM7C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,GAAG,GACd,MAAM,IAAI,EACV,IAAI,MAAM,EACV,OAAO,OAAO,EACd,UAAU,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAUhC,CAAC"}

package/dist/run.js

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+import { executeTrail } from './execute.js';
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+// ---------------------------------------------------------------------------
+// run()
+// ---------------------------------------------------------------------------
+/**
+ * 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)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await run(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export const run = (topo, id, input, options) => {
+    const trail = topo.get(id);
+    if (trail === undefined) {
+        return Promise.resolve(Result.err(new NotFoundError(`Trail "${id}" not found in topo "${topo.name}"`)));
+    }
+    return executeTrail(trail, input, options);
+};
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CACjB,IAAU,EACV,EAAU,EACV,KAAc,EACd,OAAoB,EACa,EAAE;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,CACpB,MAAM,CAAC,GAAG,CACR,IAAI,aAAa,CAAC,UAAU,EAAE,wBAAwB,IAAI,CAAC,IAAI,GAAG,CAAC,CACpE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC,CAAC"}

package/dist/service-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { ProvisionOverrideMap } from './service.js';
+import type { AnyTrail } from './trail.js';
+import type { TrailContext } from './types.js';
+import { Result } from './result.js';
+type ConfigValues = Readonly<Record<string, Record<string, unknown>>>;
+/**
+ * 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 declare const resolveProvisions: (trail: AnyTrail, ctx: TrailContext, overrides?: ProvisionOverrideMap, configValues?: ConfigValues) => Promise<Result<TrailContext, Error>>;
+export {};
+//# sourceMappingURL=service-config.d.ts.map

package/dist/service-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-config.d.ts","sourceRoot":"","sources":["../src/service-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAGV,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC,KAAK,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AA0TtE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,QAAQ,EACf,KAAK,YAAY,EACjB,YAAY,oBAAoB,EAChC,eAAe,YAAY,KAC1B,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,CAsBrC,CAAC"}