@demlik/tea 0.14.0 → 0.16.0

package/dist/{runtime-types-LWDoi943.d.ts → runtime-types-CiVpC0HN.d.ts}

@@ -1,341 +1,12 @@
-import { Result } from 'better-result';
-import { P as Port, N as NoCellError, C as Cmd, S as Sub, d as Reducer, A as AnyCmdDef, M as Machine, e as Settled, a as CmdOf, T as Transitions, f as RequirementsOf, g as PortEmitter, O as OkOf, E as ErrOf, U as UpdateForm, h as InterpretDetached } from './core-CTzMJ82M.js';
-
-/**
- * @packageDocumentation
- * The host-side provider graph — what satisfies a Cmd's `R` (Requirements)
- * channel.
- *
- * A `Cmd` is journaled data, so it can never carry a provider: a provider is a
- * closure, and a closure does not survive a `Store<S>` round-trip (ADR 0014).
- * The requirement it declares — `R` — is a TYPE, and a type needs no closure.
- * So the graph that SATISFIES it lives one layer out, in the host, where
- * closures are ordinary: `provide({ … })` builds the `ctx` object `run` already
- * takes, acquiring each provider once, in dependency order, and releasing them
- * in reverse when the run ends.
- *
- * The journal never sees any of this. Replay is a fold over Msgs (ADR 0014) and
- * a fold calls no handler, so it calls no `acquire`. The graph is host wiring —
- * hidden, per ADR 0015 — while the State it produced effects over stays visible.
- *
- * The contract is Effect's `Layer` + `Scope`, point for point, because that
- * shape has a decade of production behind it and inventing a fourth one here
- * would only be a fourth one to learn:
- *
- * 1. A provider is `acquire` plus an optional `release`; an `acquire` may depend
- *    on other providers.
- * 2. Built once per scope, in dependency order, MEMOIZED — a provider two others
- *    depend on is acquired exactly once.
- * 3. Released in reverse acquisition order, exactly once, on every terminal. A
- *    `release` that throws does not stop its siblings from running.
- * 4. An `acquire` failure releases whatever was already acquired, in reverse,
- *    then surfaces as a typed `ProvideFailedError` (ADR 0011) — never a throw
- *    that escapes `run`.
- *
- * A dependency is named with a TOKEN that carries its value type, so `acquire`
- * needs no parameter annotation and a name the tokens do not list is a compile
- * error where it is written. That is Effect's `Context.Tag` — a token carrying
- * name and type together, with the requirement set derived from what the
- * constructor reads (ZIO's `ZLayer` + `ZIO.service[T]` is the same move):
- *
- * ```ts
- * const Config = dep<{ url: string }>()("config");
- *
- * const scoped = provide({
- *   config: value({ url: "postgres://…" }),
- *   db: layer([Config], ({ config }) => connect(config.url), (db) => db.close()),
- * });
- *
- * // Either hand it straight to `run` — which acquires at boot and releases at
- * // `stop()` — or open it yourself when the host wires its own `ctx`.
- * const state = await driveToDone(run(machine, { ctx: scoped }), start, isDone);
- * ```
- *
- * The string-array form — `layer(["config"], ({ config }: { config: C }) => …)`
- * — is the UNTYPED escape hatch it remains beside. It spells each dependency
- * twice, once in `deps` and once in the annotation, and nothing ties the two
- * together until `provide` compares both against the map. Reach for it where
- * there is no token to hand: a dep name computed rather than written, or a graph
- * assembled against a `ctx` shape declared elsewhere.
- */
-/**
- * Brand marking a {@link Provided} graph apart from a hand-built `ctx`. Symbol
- * keyed and module-private, so it reaches no export and no `ctx` object can
- * collide with it by accident.
- */
-declare const providedBrand: unique symbol;
-/**
- * One node of the graph: an `acquire`, an optional `release`, and the names of
- * the sibling providers `acquire` reads.
- *
- * `D` is the shape `acquire` receives — a record of the resolved values of
- * {@link Provider.deps}. Build one with {@link layer} or {@link value} rather
- * than by hand; the constructors are what keep `deps` and `D` in step.
- *
- * `K` is the dependency NAME set — the keys `deps` may spell. {@link layer}
- * infers it from the literal you pass, and {@link provide} constrains it to the
- * map's own keys, so a misspelled dependency is a compile error at the call site
- * rather than an {@link UnknownProviderError} at `open()`. It defaults to
- * `string` — the untyped reading, for a provider read back off an erased map.
- *
- * MIGRATION: that default is why an ANNOTATION of the two-argument form no
- * longer fits inside {@link provide}. `readonly string[]` is not assignable to
- * `readonly ("config" | "db")[]`, so `const db: Provider<string, D> = …` is
- * rejected — a leaf `Provider<Config>` with `deps: []` included, since the
- * default is what is compared, not the value. Either name the key set,
- * `Provider<string, D, "config" | "db">`, or drop the annotation and let
- * {@link layer} / {@link value} infer `K` from the literal, which is the shape
- * this API is written for.
- */
-interface Provider<T, D = Record<never, never>, K extends string = string> {
-    /** Names of the sibling providers `acquire` reads, resolved before it runs. */
-    readonly deps: readonly K[];
-    /**
-     * Build the value. May be async; may read its declared `deps`.
-     *
-     * A function-typed PROPERTY, not a method: a method's parameters are
-     * bivariant, and bivariance here would silently accept a provider whose deps
-     * disagree with the map's — the one check `provide` exists to make.
-     */
-    readonly acquire: (deps: D) => T | Promise<T>;
-    /**
-     * Tear the value down. Optional — a provider with no `release` is a value with
-     * no lifetime. May be async; the scope awaits it.
-     *
-     * A METHOD, unlike `acquire`: its parameter is this provider's OWN value, so
-     * there is no sibling to cross-check and the bivariance a method's parameters
-     * get is what lets a `Provider<Db, …>` be read through the erased
-     * `Provider<unknown, …>` the map's constraint spells.
-     */
-    release?(value: T): unknown;
-}
-/**
- * The `ctx` a provider map produces: each key mapped to its provider's value.
- */
-type ProvidedCtx<M> = {
-    [K in keyof M]: M[K] extends Provider<infer T, never, string> ? T : never;
-};
-/**
- * A provider with no dependencies — {@link layer}'s one-argument form and
- * {@link value}. Its `K` is `never`, so an empty `deps` fits EVERY map: a
- * leaf provider built through those constructors is admissible wherever it is
- * declared, whatever keys the map around it happens to have.
- *
- * It is the CONSTRUCTED form that this holds for. Annotating the same value
- * `Provider<T>` puts `K` back at its `string` default and outside `provide`'s
- * constraint — see the migration note on {@link Provider}.
- */
-type LeafProvider<T> = Provider<T, Record<never, never>, never>;
-/**
- * A live scope — the `ctx` its graph produced, plus the one call that tears it
- * down. `release` is idempotent: the second call is a no-op, so a host that
- * releases in a `finally` beside a `run` that already released cannot double-free.
- */
-interface Scope<Ctx> {
-    /** The built `ctx`, one field per provider. */
-    readonly ctx: Ctx;
-    /**
-     * Release every acquired provider in reverse acquisition order, exactly once.
-     * Each `release` is isolated: a throw is routed to `onReleaseError` and the
-     * remaining releases still run. Never rejects.
-     */
-    release(): Promise<void>;
-}
-/**
- * Sink for a `release` that threw. A release failure has no caller to reject at
- * — the run is already over — so it is reported, never propagated.
- */
-type OnReleaseError = (error: unknown, provider: string) => void;
-/**
- * An unopened provider graph. Pass it to `run` as `ctx` (it acquires at boot and
- * releases at `stop()`), or {@link Provided.open} it yourself when the host
- * wires its own `ctx`.
- */
-interface Provided<Ctx> {
-    /** Brand — see the module note. Never assigned by a consumer. */
-    readonly [providedBrand]: true;
-    /**
-     * Acquire the whole graph and return the live {@link Scope}. Rejects with a
-     * {@link ProvideFailedError} when an `acquire` fails, having already released
-     * everything it had acquired, in reverse.
-     */
-    open(onReleaseError?: OnReleaseError): Promise<Scope<Ctx>>;
-}
-/**
- * An `acquire` failed. A typed failure (ADR 0011) rather than the raw throw:
- * `provider` names the node that failed and `cause` carries what it threw, so a
- * host reads which dependency the run could not stand up without matching on a
- * message.
- *
- * By the time this is raised, every provider acquired before it has been
- * released in reverse.
- */
-declare class ProvideFailedError extends Error {
-    readonly _tag: "provide_failed";
-    /** The provider key whose `acquire` failed. */
-    readonly provider: string;
-    constructor(provider: string, cause: unknown);
-}
-/**
- * A provider named a dependency the map has no key for. A contract breach
- * (ADR 0011) — the wiring itself is wrong, so it throws rather than settling.
- *
- * `provide` binds `deps` to `keyof M`, so a map it typechecked can never raise
- * this: the typo is a compile error at the call site instead. What is left is
- * the UNTYPED path — a map cast (`as never`, `as any`), assembled at runtime, or
- * read back through an erased `Provider<unknown, …>` — where there was no key
- * set to check against. The error stays because that path is real, not because
- * the typed one still needs it.
- */
-declare class UnknownProviderError extends Error {
-    readonly _tag: "unknown_provider";
-    /** The missing key. */
-    readonly provider: string;
-    /** The provider that asked for it. */
-    readonly requiredBy: string;
-    constructor(provider: string, requiredBy: string);
-}
-/**
- * The dependency graph has a cycle, so no acquisition order exists. A contract
- * breach (ADR 0011): the wiring is wrong and no run can fix it.
- */
-declare class ProviderCycleError extends Error {
-    readonly _tag: "provider_cycle";
-    /** The cycle, in the order it was walked, closing on its own first key. */
-    readonly cycle: readonly string[];
-    constructor(cycle: readonly string[]);
-}
-/**
- * Phantom key carrying a {@link DepToken}'s VALUE type. Declared, never
- * assigned: `dep` builds a token whose only runtime field is `name`, and this
- * property exists so the type survives into {@link DepsOf}. Symbol keyed and
- * module-private, so it reaches no export and no object literal can collide
- * with it.
- *
- * Typed `(probe: never) => T`, which makes the token COVARIANT in `T`: a
- * `DepToken<"config", Config>` is readable through the `DepToken<string,
- * unknown>` bound {@link layer}'s tuple is constrained by, while the value type
- * itself is still recovered exactly by {@link DepValue}'s `infer`.
- */
-declare const depValue: unique symbol;
-/**
- * A typed dependency name — Effect's `Context.Tag`. It carries the dependency's
- * literal NAME and its VALUE type in one value, so {@link layer} derives the
- * whole `acquire` parameter from the tokens and the caller annotates nothing.
- *
- * Build one with {@link dep}; the phantom field is not yours to write.
- */
-interface DepToken<N extends string = string, T = unknown> {
-    /** The provider key this token stands for — the `keyof M` `provide` checks. */
-    readonly name: N;
-    /** Phantom — see the note on `depValue`. Never present at runtime. */
-    readonly [depValue]?: (probe: never) => T;
-}
-/** The value type a {@link DepToken} carries. */
-type DepValue<Token> = Token extends DepToken<string, infer T> ? T : never;
-/**
- * The `acquire` parameter a tuple of {@link DepToken}s describes: one property
- * per token, named by the token and typed with what it carries. This is the
- * derivation that removes the second spelling — `D` is no longer annotated, it
- * falls out of `deps`.
- */
-type DepsOf<Tokens extends readonly DepToken<string, unknown>[]> = {
-    [N in Tokens[number]["name"]]: DepValue<Extract<Tokens[number], {
-        name: N;
-    }>>;
-};
-/**
- * Mint a typed dependency token: `dep<Config>()("config")`.
- *
- * CURRIED because TypeScript infers type arguments all-or-nothing — naming `T`
- * in a single call would force `N` to be spelled too, and a spelled `N` is the
- * widening this token exists to prevent. Effect's `Context.Tag("name")<Self,
- * Shape>()` curries for the same reason; this one takes the type first so the
- * name stays inferred from the literal.
- *
- * ```ts
- * const Config = dep<{ url: string }>()("config");
- * const Db = dep<Connection>()("db");
- * const cache = layer([Config, Db], ({ config, db }) => …);
- * ```
- */
-declare function dep<T>(): <const N extends string>(name: N) => DepToken<N, T>;
-/**
- * Declare a provider with no dependencies: an `acquire` and an optional
- * `release`.
- */
-declare function layer<T>(acquire: () => T | Promise<T>, release?: (value: T) => unknown): LeafProvider<T>;
-/**
- * Declare a provider that depends on siblings, naming each one with a
- * {@link DepToken} — the TYPED route, and the one to reach for.
- *
- * `D` is {@link DepsOf} the tuple, so `acquire` takes NO annotation: its
- * parameter is already a record of exactly the tokens' names at exactly the
- * tokens' types. Both halves of a dependency mistake then land at THIS call —
- * destructuring a property the tuple does not name does not compile, and
- * reading one at the wrong type does not either — instead of surfacing inside
- * `provide`'s `M` constraint as a message about the map.
- *
- * ```ts
- * const Config = dep<Config>()("config");
- * const db = layer([Config], ({ config }) => connect(config.url), (c) => c.end());
- * ```
- *
- * This is Effect's `Context.Tag`, and ZIO's `ZIO.service[T]`: the requirement
- * set is derived from what the constructor reads rather than restated beside it.
- */
-declare function layer<T, const Tokens extends readonly DepToken<string, unknown>[]>(deps: Tokens, acquire: (deps: DepsOf<Tokens>) => T | Promise<T>, release?: (value: T) => unknown): Provider<T, DepsOf<Tokens>, Tokens[number]["name"]>;
-/**
- * Declare a provider that depends on siblings, naming each one with a STRING —
- * the untyped escape hatch. `deps` names them; `acquire` receives their resolved
- * values as a record, and the annotation you give that parameter is what types
- * `D`.
- *
- * Nothing ties the two spellings together: `layer(["config"], ({ config }: {
- * cfg: C }) => …)` type-checks here and fails later, inside `provide`'s `M`
- * constraint, in the map's vocabulary rather than the typo's. Prefer the token
- * overload above, which derives the annotation instead of restating it; reach
- * for this one where there is no token to hand.
- *
- * The names are inferred as literals, not widened to `string`, so {@link provide}
- * can check them against the map's keys. `const K` is what pins that: without
- * the modifier TypeScript 7 widens `["config"]` to `string[]` here where 5.x
- * kept the literal, and every provider in the map then fails `provide`'s
- * key constraint with "`string` is not assignable to `"config" | …`".
- */
-declare function layer<T, D, const K extends string>(deps: readonly K[], acquire: (deps: D) => T | Promise<T>, release?: (value: T) => unknown): Provider<T, D, K>;
-/**
- * Lift an already-built value into the graph — a provider with no `acquire` work
- * and no lifetime. The escape hatch for the config object, the clock, the
- * `fetch` you were handed: things a `ctx` carries that were never resources.
- */
-declare function value<T>(v: T): LeafProvider<T>;
-/**
- * Build an unopened provider graph from a map of providers.
- *
- * The map's own key set is the resulting `ctx`'s shape, and each provider is
- * checked against that shape on BOTH of its ends — so both halves of a wiring
- * mistake are a compile error here, not a surprise at 3 a.m.:
- *
- * - the `acquire` parameter, so a provider that reads `{ config: Config }`
- *   beside a `config` provider of some other type does not compile;
- * - the `deps` names, bound to `keyof M`, so `layer(["confg"], …)` does not
- *   compile either.
- *
- * Nothing is acquired until the graph is opened — by `run`, at boot, or by
- * {@link Provided.open}.
- */
-declare function provide<M extends {
-    [K in keyof M]: Provider<unknown, ProvidedCtx<M>, Extract<keyof M, string>>;
-}>(map: M): Provided<ProvidedCtx<M>>;
-/** Is this `ctx` argument an unopened provider graph rather than a plain `ctx`? */
-declare function isProvided<Ctx>(candidate: Ctx | Provided<Ctx> | undefined): candidate is Provided<Ctx>;
+import { C as Cmd, S as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, i as Reducer, A as AnyCmdDef, j as Settled, c as CmdOf, k as Transitions, a as BuiltinSub, U as UpdateForm, l as Outcome, I as InterpretDetached, m as PortEmitter } from './core-BbgtiXdg.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
  * interfaces, and construction/composition helpers the runtime (`./run`)
  * implements against: `Store`, the error-sink and supervision contracts, the
- * `RuntimeRef` / `BootingRuntime` / `Runtime` handle hierarchy, `definePort`, the
+ * engine-neutral `RunHandle` / `BootedRunHandle` every engine's `run` returns,
+ * the Promise engine's `RuntimeRef` / `BootingRuntime` / `Runtime` handle
+ * hierarchy that widens it, `definePort`, the
  * identity-typed constructors `defineMachine` / `asReducer`, and the pure tools
  * `replay` (compose without running) and `tryInterpret` (Railway).
  */
@@ -362,28 +33,14 @@ declare function absurd(x: never): never;
 declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, readonly C[]];
 /**
  * Thrown by `definePort` when a name has already been registered in the current
- * process. Symmetric with `SubIdCollisionError` (thrown by `reconcileSubs`) —
- * both mechanize invariant 7 (identity is explicit) at the runtime layer the
- * type system cannot reach (string names compared at runtime).
+ * process. It mechanizes invariant 7 (identity is explicit) at the runtime
+ * layer the type system cannot reach (string names compared at runtime).
  */
 declare class PortNameCollisionError extends Error {
     readonly name = "PortNameCollisionError";
     readonly _tag: "PortNameCollisionError";
     constructor(portName: string);
 }
-/**
- * Thrown by `reconcileSubs` when, within ONE desired subscription set, two subs
- * share an `id` but declare different `type`s — a silent bug class the type
- * system cannot reach (ids are strings compared at runtime). The symmetric twin
- * of `PortNameCollisionError`: both mechanize invariant 7 (identity is explicit)
- * at the runtime layer. Same id across transitions is the no-churn case and does
- * NOT throw; only a within-set type conflict does.
- */
-declare class SubIdCollisionError extends Error {
-    readonly name = "SubIdCollisionError";
-    readonly _tag: "SubIdCollisionError";
-    constructor(id: string, declaredType: string, conflictingType: string);
-}
 /**
  * Test-only escape hatch — clears the module-level port-name registry so the
  * collision assert in `definePort` doesn't false-positive across vitest's
@@ -401,13 +58,19 @@ declare function __resetPortRegistry(): void;
  *   re-dispatched (the original dispatcher already resolved, so no caller).
  *   A rejection caused by `stop()`'s own teardown is NOT this phase — see
  *   `"discard"`.
+ * - `"interpret"` — a `Cmd.define`d handler failed outside its declared
+ *   channel (ADR 0021): it threw, returned an `Err` whose tag it does not
+ *   declare (`UndeclaredFailureError`), or returned something the engine cannot
+ *   mint (`OutcomeContractError`, `AsyncSchemaError`). No `_err` Msg is
+ *   dispatched, and the dispatch that emitted the Cmd still resolves.
  * - `"stop-save"` — the final `store.save(state)` inside `stop()` threw
  *   (`stop()` resolves regardless, so without the sink this was silent loss).
  * - `"reduce"` — the pure `update` (reducer) threw synchronously; the configured
  *   `Supervision` strategy decides what happens next, but the throw is surfaced
  *   here as data first.
  * - `"listener"` — a `runtime.subscribe(...)` listener threw during fanout.
- * - `"observer"` — a `runtime.observe(...)` observer threw during fanout.
+ * - `"observer"` — a `runtime.observe(...)` observer threw during fanout, or
+ *   the `telemetry` sink threw or rejected.
  * - `"event"` — the `events` projector or an `on(type, ...)` handler threw.
  * - `"boot"` — an `onBoot` handler threw (boot fanout, or a late registration).
  * - `"port-emit"` — a `subscribePort` listener threw during a port emission.
@@ -425,27 +88,34 @@ declare function __resetPortRegistry(): void;
  *   `"discard"`: the loss is the FILTER WORKING, not a teardown, and a host
  *   routing it (a metric, a 409 back to the caller) wants it apart from
  *   unmount-time noise. Warn-only, like every `RuntimeDiscardNotice`.
- * - `"provide"` — a `provide({ … })` graph handed to `run` as `ctx`. Two
- *   witnesses: an `acquire` failed at boot (a `ProvideFailedError`, ALSO the
- *   rejection of `ready`, so this report is the copy a sink gets rather than the
- *   only route out), and a `release` threw during `stop()`, which carries
- *   `context.provider` and has no other route out at all — the run is over.
  *
  * The phase never decides fatality — the ERROR CLASS does (`RuntimeDiscardNotice`
  * warns, everything else rethrows). A phase is attached by the report site, so a
  * consumer sink that throws while handling a `"discard"` report inherits that
  * phase; keying the warn-only path on it would make the sink's own defect vanish.
  */
-type RuntimeErrorPhase = "follow-up" | "stop-save" | "reduce" | "listener" | "observer" | "event" | "boot" | "port-emit" | "sub-cleanup" | "discard" | "identity-drop" | "provide";
+type RuntimeErrorPhase = "follow-up" | "interpret" | "stop-save" | "reduce" | "listener" | "observer" | "event" | "boot" | "port-emit" | "sub-cleanup" | "discard" | "identity-drop";
+/**
+ * What the `telemetry` sink passed to `run` receives, once per APPLIED
+ * transition. Plain data, so a recorded stream stays durable.
+ */
+interface TelemetryEvent {
+    /** This run's applied transitions so far, counted from 1. Boot is not one. */
+    readonly seq: number;
+    /** The `Msg.type` that drove the transition. */
+    readonly msgType: string;
+    /** When the transition committed, read off `run`'s `clock` (ms since epoch). */
+    readonly at: number;
+}
+/**
+ * The `telemetry` option of `run`: a fire-and-forget sink. The run never waits
+ * on it, and a throw or rejection reaches `onError` under `"observer"` without
+ * touching the run.
+ */
+type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 /** Context handed to an `OnError` sink alongside the error itself. */
 interface RuntimeErrorContext {
     readonly phase: RuntimeErrorPhase;
-    /**
-     * The provider key a `"provide"` report is about — set when a `release` threw
-     * (the run is over; the throw has nowhere else to go). Absent on the acquire
-     * report, which also rejects `ready` with a `ProvideFailedError` that names it.
-     */
-    readonly provider?: string;
 }
 /**
  * Sink for runtime failures that have no caller to reject at. Configured via
@@ -510,7 +180,7 @@ declare class DriveFailedError<S> extends Error {
 /**
  * Raised by `driveToDone` when `start`'s follow-up chain quiesces on a State
  * that is neither terminal nor `failed` AND nothing in the runtime can still
- * transition it — no live Sub (manual or dep-keyed), no in-flight Cmd. Waiting
+ * transition it — no live Sub, no in-flight Cmd. Waiting
  * past that point is not the Sub-driven contract, it is a leak: no transition is
  * coming, so the drive would hang with the runtime alive and `stop()` never
  * reached. The rejection carries the stalled State on `error.state`, sibling to
@@ -730,11 +400,90 @@ interface RuntimeRef<M extends {
      */
     dispatchOnce(msg: M): Promise<void>;
 }
+/**
+ * What an engine's `run` returns: queue a Msg, listen, wait for boot, stop.
+ * `getState` is not here — there is no State until boot runs, so it lives on
+ * the {@link BootedRunHandle} that `ready` resolves to. `E` is the machine's
+ * semantic event union (see `on`); `never` when the run projects none.
+ */
+interface RunHandle<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never> {
+    /** Put a Msg in the inbox; resolves once the engine has processed it. */
+    dispatch(msg: M): Promise<void>;
+    /** A zero-arg change notifier, fired after each applied transition. */
+    subscribe(listener: () => void): () => void;
+    /** A `(msg, state)` hook, fired after each applied transition. */
+    observe(observer: (msg: M, state: S) => void): () => void;
+    /** Fires once with the initial State — at once if boot already ran. */
+    onBoot(handler: (state: S) => void): () => void;
+    /** Subscribe to the semantic event of `type` the run's `events` projects. */
+    on<K extends E["type"]>(type: K, handler: (event: Extract<E, {
+        type: K;
+    }>) => void): () => void;
+    /** Resolves to the booted handle once boot completes. */
+    readonly ready: Promise<BootedRunHandle<S, M, E>>;
+    /** Stop the run; resolves once the engine has torn it down. */
+    stop(): Promise<void>;
+}
+/** A {@link RunHandle} whose boot has completed, so its State exists. */
+interface BootedRunHandle<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never> extends RunHandle<S, M, E> {
+    /** The current State. Total. */
+    getState(): S;
+    readonly ready: Promise<BootedRunHandle<S, M, E>>;
+}
+/**
+ * The options every engine's `run` accepts: the `ctx`, the handlers the
+ * machine runs under, an optional `store`, and the `events` projector that
+ * feeds `on`. An engine may take more; a host adapter hands only these.
+ */
+type RunOptions<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, E extends {
+    type: string;
+} = never> = CtxArg<Ctx> & RunHandlers<M, C, U, Ctx> & {
+    readonly store?: Store<S>;
+    readonly events?: (msg: M, state: S) => readonly E[];
+};
+/**
+ * An engine's `run`, seen from a host adapter: a machine and its
+ * {@link RunOptions} in, a {@link RunHandle} out. `useMachine` and
+ * `createAgentHost` take one, so they run on whichever engine the caller
+ * imported — `run` from `@demlik/tea/promise` fits it as it is.
+ */
+type EngineRun<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, E extends {
+    type: string;
+} = never> = (machine: Machine<S, M, C, U, Ctx>, opts: RunOptions<S, M, C, U, Ctx, E>) => RunHandle<S, M, E>;
+/**
+ * What the Promise engine's `run` returns, the instant it is called, while boot
+ * is still in flight: its {@link RunHandle}, widened with Ports and
+ * `dispatchOnce`. It exposes exactly the surface total before boot — queue a
+ * dispatch, subscribe, observe, wire a Port, stop. Reading State (`getState`)
+ * and waiting for quiescence (`idle`) need the initial State to exist, so they
+ * live on the {@link Runtime} that `ready` resolves to; "read State before boot"
+ * is a compile error, not a runtime throw.
+ *
+ * `subscribe` is the React-shaped change notifier (zero-arg, paired with
+ * `getState()`). `observe` is the devtools-shaped trace hook — `(msg, state)`
+ * for every applied transition; boot is delivered via `onBoot` instead, so
+ * `observe`'s `msg` is total (never `null`). `on(type, handler)` is the semantic
+ * event channel: only the public, `type`-narrowed events a machine projects,
+ * never its private Msg vocabulary. `E` defaults to `never` (no projector → `on`
+ * uncallable).
+ */
 interface BootingRuntime<S, M extends {
     type: string;
 }, E extends {
     type: string;
-} = never> extends RuntimeRef<M> {
+} = never> extends RuntimeRef<M>, RunHandle<S, M, E> {
     dispatch(msg: M, opts?: {
         readonly settle?: DispatchSettle;
     }): Promise<void>;
@@ -803,6 +552,15 @@ interface BootingRuntime<S, M extends {
     ready: Promise<Runtime<S, M, E>>;
     stop(): Promise<void>;
 }
+/**
+ * The Promise engine's booted handle — what {@link BootingRuntime}'s `ready`
+ * resolves to once boot completes. It adds the members only meaningful once the
+ * initial State exists — `getState()` (total), `idle()` (quiescence), and the
+ * `result()` / `done()` reads of the terminal State — and narrows `ready` to
+ * resolve to itself. You never construct one directly; you obtain it via
+ * `await bootingRuntime.ready`, which makes "read State before boot"
+ * unrepresentable rather than merely discouraged.
+ */
 interface Runtime<S, M extends {
     type: string;
 }, E extends {
@@ -854,9 +612,9 @@ interface Runtime<S, M extends {
  *
  * `model` and `msg` are always named. `cmd` is named only by a machine whose
  * Cmds are hand-written records rather than `Cmd.define` constructors listed
- * under `cmds`; `sub` only by one whose Sub union `subscriptions` does not
- * imply; `ctx` only by one whose handlers read a `Ctx` slice no Cmd's
- * `requirements` declares.
+ * under `cmds`; `sub` only by one that declares Subs other than the built-in
+ * `timer` (its union of `Sub<type, deps>`); `ctx` only by one whose `init`
+ * reads a `Ctx` or whose handlers are typed against one.
  */
 type MachineTypes<S, M extends {
     type: string;
@@ -912,16 +670,6 @@ type CtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
 } : {
     ctx: Ctx;
 };
-/**
- * `run`'s `ctx` field: the `Ctx` object, or a `provide` graph that builds one.
- * Conditionally optional exactly like {@link CtxArg} — a machine that reads
- * nothing from `ctx` may omit it.
- */
-type ScopedCtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
-    ctx?: Ctx | Provided<Ctx>;
-} : {
-    ctx: Ctx | Provided<Ctx>;
-};
 declare function replay<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
@@ -931,11 +679,7 @@ declare function replay<S, M extends {
 }): {
     state: S;
     cmds: C[];
-    subs: U[];
-    depSubs: {
-        index: number;
-        id: string;
-    }[];
+    subs: (U | BuiltinSub<M>)[];
 };
 declare function wrapDetached<C extends Cmd, M extends {
     type: string;
@@ -955,11 +699,11 @@ declare function tryApplyCell<S, M extends {
 }, C extends Cmd>(machine: {
     update: object;
     __form?: UpdateForm;
-}, state: S, msg: M): Result<readonly [S, readonly C[]], NoCellError>;
+}, state: S, msg: M): Outcome<readonly [S, readonly C[]], NoCellError>;
 /**
  * The refusal `tryFoldMsgs` reports: WHICH msg in the log had no handler, where.
  *
- * A plain record, not a new `Error` subclass — it is a `Result` payload, never
+ * A plain record, not a new `Error` subclass — it is an `Outcome` payload, never
  * thrown, and the actual error is the existing `NoCellError` it carries. The
  * package's thrown-error idiom (`class extends Error` + `_tag`, pinned by
  * `error-idiom.test.ts`) applies to errors raised at the runtime edge; this one
@@ -978,7 +722,7 @@ interface FoldRefusal<M> {
  * INCLUDING which message failed.
  *
  * The motivating use is "this persisted log does not replay — tell the user
- * where". A bare `Result<S, NoCellError>` cannot: the error names the msg.type
+ * where". A bare `Outcome<S, NoCellError>` cannot: the error names the msg.type
  * and the state, but a log usually contains that type many times, so the
  * INDEX is the load-bearing fact. The fold stops at the first refusal (state
  * past that point is not defined) and returns it.
@@ -991,8 +735,7 @@ declare function tryFoldMsgs<S, M extends {
 }, C extends Cmd>(machine: {
     update: object;
     __form?: UpdateForm;
-}, base: S, msgs: readonly M[]): Result<S, FoldRefusal<M>>;
-declare function settle<D extends AnyCmdDef, Ctx>(def: D, work: (cmd: CmdOf<D>, ctx: Ctx & RequirementsOf<CmdOf<D>> & PortEmitter) => Promise<Result<OkOf<D>, ErrOf<D>>>): (cmd: CmdOf<D>, ctx: Ctx & RequirementsOf<CmdOf<D>> & PortEmitter) => Promise<Settled<D>>;
+}, base: S, msgs: readonly M[]): Outcome<S, FoldRefusal<M>>;
 declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
 
-export { tryApplyCell as $, type SupervisionStrategy as A, type BootingRuntime as B, type CtxArg as C, type DepToken as D, absurd as E, type FencedStore as F, asReducer as G, defineMachine as H, IdentityDropNotice as I, definePort as J, dep as K, isFencedStore as L, type MachineTypes as M, isProvided as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, layer as T, UnknownProviderError as U, noop as V, provide as W, replay as X, schemaMigrate as Y, settle as Z, __resetPortRegistry as _, type ScopedCtxArg as a, tryFoldMsgs as a0, tryInterpret as a1, value as a2, wrapDetached as a3, type Supervision as b, type Branded as c, type DepsOf as d, DispatchDiscardedError as e, type DispatchSettle as f, DisposeTimeoutNotice as g, DriveFailedError as h, DriveStalledError as i, type FencedRead as j, type FoldRefusal as k, type OnReleaseError as l, ProvideFailedError as m, type Provided as n, type ProvidedCtx as o, type Provider as p, ProviderCycleError as q, RuntimeDiscardNotice as r, RuntimeDiscardedError as s, type RuntimeErrorContext as t, type RuntimeErrorPhase as u, type RuntimeRef as v, type Schema as w, type Scope as x, StoreConflictError as y, SubIdCollisionError as z };
+export { replay as A, type BootingRuntime as B, type CtxArg as C, DispatchDiscardedError as D, type EngineRun as E, type FencedStore as F, schemaMigrate as G, tryApplyCell as H, IdentityDropNotice as I, tryFoldMsgs as J, tryInterpret as K, wrapDetached as L, type MachineTypes as M, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type RunHandle as c, type Branded as d, type DispatchSettle as e, DisposeTimeoutNotice as f, DriveFailedError as g, DriveStalledError as h, type FencedRead as i, type FoldRefusal as j, type RunOptions as k, RuntimeDiscardNotice as l, RuntimeDiscardedError as m, type RuntimeErrorContext as n, type RuntimeErrorPhase as o, type RuntimeRef as p, type Schema as q, StoreConflictError as r, type SupervisionStrategy as s, type TelemetryEvent as t, absurd as u, asReducer as v, defineMachine as w, definePort as x, isFencedStore as y, noop as z };