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

package/dist/service.d.ts

@@ -1,71 +0,0 @@
-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 surface 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 metadata for tooling and filtering. */
-    readonly metadata?: 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=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.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,sEAAsE;IACtE,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,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACnE;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/service.js

@@ -1,56 +0,0 @@
-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=service.js.map

package/dist/service.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.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/src/__tests__/service.test.ts

@@ -1,197 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { z } from 'zod';
-
-import {
-  Result,
-  createTrailContext,
-  findDuplicateProvisionId,
-  isProvision,
-  provision as defineProvision,
-} from '../index.js';
-import type {
-  Provision,
-  ProvisionContext,
-  ProvisionSpec,
-  TrailContext,
-} from '../index.js';
-
-const provisionCtx: ProvisionContext = {
-  cwd: '/tmp/trails',
-  env: { DATABASE_URL: 'file::memory:' },
-  workspaceRoot: '/tmp',
-};
-
-let disposedValue: number | undefined;
-
-const counterProvisionSpec: ProvisionSpec<number> = {
-  create: () => Result.ok(3),
-  description: 'Counter provision',
-  dispose: (provision) => {
-    disposedValue = provision;
-  },
-  health: (provision) => Result.ok({ healthy: provision > 0 }),
-  meta: { domain: 'data' },
-  mock: () => 1,
-};
-
-const resolvedServiceCtx = (id: string, instance: unknown): TrailContext =>
-  createTrailContext({
-    abortSignal: new AbortController().signal,
-    extensions: { [id]: instance },
-    requestId: `${id}-request`,
-  });
-
-describe('provision types', () => {
-  test('ProvisionContext exposes the stable process-scoped fields', () => {
-    expect(provisionCtx.cwd).toBe('/tmp/trails');
-    expect(provisionCtx.env?.DATABASE_URL).toBe('file::memory:');
-    expect(provisionCtx.workspaceRoot).toBe('/tmp');
-  });
-
-  test('ProvisionSpec stores description and meta', () => {
-    expect(counterProvisionSpec.description).toBe('Counter provision');
-    expect(counterProvisionSpec.meta).toEqual({ domain: 'data' });
-  });
-
-  test('ProvisionSpec can reserve a config schema for future composition', () => {
-    const config = z.object({ url: z.string().url() });
-    const spec: ProvisionSpec<number> = {
-      config,
-      create: () => Result.ok(1),
-    };
-
-    expect(spec.config).toBe(config);
-  });
-
-  test('ProvisionSpec create and health callbacks are callable', async () => {
-    const result = await counterProvisionSpec.create(provisionCtx);
-    expect(result.isOk()).toBe(true);
-    expect(result.unwrap()).toBe(3);
-
-    const health = await counterProvisionSpec.health?.(result.unwrap());
-    expect(health?.isOk()).toBe(true);
-    expect(health?.unwrap()).toEqual({ healthy: true });
-  });
-
-  test('ProvisionSpec mock and dispose callbacks are callable', async () => {
-    disposedValue = undefined;
-    const result = await counterProvisionSpec.create(provisionCtx);
-    expect(result.isOk()).toBe(true);
-
-    const provision = result.unwrap();
-    expect(await counterProvisionSpec.mock?.()).toBe(1);
-
-    await counterProvisionSpec.dispose?.(provision);
-    expect(disposedValue).toBe(3);
-  });
-
-  test('ProvisionSpec create can be async', async () => {
-    const spec: ProvisionSpec<number> = {
-      create: async () => {
-        await Bun.sleep(0);
-        return Result.ok(7);
-      },
-    };
-
-    const result = await spec.create(provisionCtx);
-    expect(result.isOk()).toBe(true);
-    expect(result.unwrap()).toBe(7);
-  });
-
-  test('Provision carries identity alongside the shared spec fields', async () => {
-    const counterProvision: Provision<number> = {
-      from(ctx) {
-        return ctx.provision(this);
-      },
-      id: 'counter.main',
-      kind: 'provision',
-      ...counterProvisionSpec,
-    };
-
-    expect(counterProvision.kind).toBe('provision');
-    expect(counterProvision.id).toBe('counter.main');
-
-    const created = await counterProvision.create(provisionCtx);
-    expect(created.isOk()).toBe(true);
-    expect(created.unwrap()).toBe(3);
-    expect(await counterProvision.mock?.()).toBe(1);
-  });
-});
-
-describe('provision()', () => {
-  test('returns a frozen provision object with kind and id', () => {
-    const counter = defineProvision('counter.main', counterProvisionSpec);
-
-    expect(counter.kind).toBe('provision');
-    expect(counter.id).toBe('counter.main');
-    expect(Object.isFrozen(counter)).toBe(true);
-  });
-
-  test('infers the provision type through from(ctx)', () => {
-    const db = defineProvision('db.main', {
-      create: () =>
-        Result.ok({
-          query(sql: string) {
-            return sql.length;
-          },
-        }),
-      description: 'Typed database service',
-    });
-
-    const store = {
-      query(sql: string) {
-        return sql.length;
-      },
-    };
-    const ctx = resolvedServiceCtx('db.main', store);
-
-    const resolved = db.from(ctx);
-    expect(resolved.query('select 1')).toBe(8);
-  });
-
-  test('from(ctx) throws when the provision is missing', () => {
-    const counter = defineProvision('counter.main', counterProvisionSpec);
-    const ctx = createTrailContext({
-      abortSignal: new AbortController().signal,
-      requestId: 'missing-provision',
-    });
-
-    expect(() => counter.from(ctx)).toThrow(
-      'Provision "counter.main" not found in trail context'
-    );
-  });
-
-  test('from(ctx) returns undefined when the provision key exists with an undefined value', () => {
-    const optional = defineProvision<undefined>('optional.main', {
-      create: () => Result.ok<undefined>(),
-    });
-    const ctx = createTrailContext({
-      abortSignal: new AbortController().signal,
-      extensions: { [optional.id]: undefined },
-      requestId: 'undefined-provision',
-    });
-
-    expect(optional.from(ctx)).toBeUndefined();
-  });
-});
-
-describe('provision helpers', () => {
-  test('isProvision identifies provision definitions', () => {
-    const counter = defineProvision('counter.main', counterProvisionSpec);
-
-    expect(isProvision(counter)).toBe(true);
-    expect(isProvision({ id: 'counter.main', kind: 'trail' })).toBe(false);
-    expect(isProvision(null)).toBe(false);
-  });
-
-  test('findDuplicateProvisionId returns the first repeated ID', () => {
-    const first = defineProvision('counter.main', counterProvisionSpec);
-    const duplicate = defineProvision('counter.main', counterProvisionSpec);
-    const other = defineProvision('counter.secondary', counterProvisionSpec);
-
-    expect(findDuplicateProvisionId([first, other])).toBeUndefined();
-    expect(findDuplicateProvisionId([first, other, duplicate])).toBe(
-      'counter.main'
-    );
-  });
-});

package/src/event.ts

@@ -1,15 +0,0 @@
-/**
- * Legacy event aliases for the signal model.
- *
- * Keep this file as a compatibility seam while the repo-wide cutover lands.
- */
-
-export { signal as event } from './signal.js';
-export type {
-  AnySignal,
-  AnySignal as AnyEvent,
-  Signal,
-  Signal as Event,
-  SignalSpec,
-  SignalSpec as EventSpec,
-} from './signal.js';

package/src/gate.ts

@@ -1,44 +0,0 @@
-import type { Trail } from './trail.js';
-import type { Implementation } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Gate interface
-// ---------------------------------------------------------------------------
-
-/** 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<I, O>(
-    trail: Trail<I, O>,
-    implementation: Implementation<I, O>
-  ): Implementation<I, O>;
-}
-
-// ---------------------------------------------------------------------------
-// Composition
-// ---------------------------------------------------------------------------
-
-/**
- * Apply gates outermost-first: gates[0] wraps gates[1] wraps ... wraps
- * the base implementation.
- *
- * An empty gates array returns the implementation unchanged.
- */
-export const composeGates = <I, O>(
-  gates: readonly Gate[],
-  trail: Trail<I, O>,
-  implementation: Implementation<I, O>
-): Implementation<I, O> => {
-  // Fold right so gates[0] is the outermost wrapper.
-  let result = implementation;
-  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/provision.ts

@@ -1,148 +0,0 @@
-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;
-};