@demlik/tea 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,38 +1,6 @@
-type Reducer<S, M extends {
-    type: string;
-}, C extends Cmd> = {
-    [K in M["type"]]: (state: S, msg: Extract<M, {
-        type: K;
-    }>) => readonly [S, readonly C[]];
-};
-type Transitions<S extends {
-    type: string;
-}, M extends {
-    type: string;
-}, C extends Cmd> = {
-    [P in S["type"]]: {
-        [K in M["type"]]: (state: Extract<S, {
-            type: P;
-        }>, msg: Extract<M, {
-            type: K;
-        }>) => readonly [S, readonly C[]];
-    };
-};
-/**
- * Compile-time exhaustiveness assertion. Use in default branches of
- * switches over discriminated unions where every case should be handled
- * explicitly — TS narrows the type to `never` only if every variant has
- * been covered. Strengthens invariant 7 (identity is explicit).
- *
- * @example
- *   switch (msg.type) {
- *     case "a": return ...;
- *     case "b": return ...;
- *     default: return absurd(msg);  // compile error if a "c" is added
- *   }
- */
-declare function absurd(x: never): never;
-declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, readonly C[]];
+import { C as Cmd, P as Port, S as Sub, M as Machine, T as Transitions, R as Reducer } from './core-BoB6t7dB.js';
+export { b as ContextFree, I as Interpret, N as NoCtx, c as PortEmitter, a as SubId, d as Subscribe, e as SyncReturn, U as UpdateForm, f as applyCell, g as detectUpdateForm, h as foldMsgs, i as formOf, m as msgKeysOf, s as subId } from './core-BoB6t7dB.js';
+
 /**
  * @demlik/tea — TEA-faithful state machine substrate.
  *
@@ -46,84 +14,26 @@ declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, rea
  * `tryInterpret` is Railway sugar — wraps a fallible async function and routes
  * Ok/Err to two Msg constructors via better-result.
  */
-type Cmd<T extends string = string> = {
-    type: T;
-};
-declare const Cmd: {
-    /**
-     * The empty Cmd array. Typed `readonly never[]` so it's assignable to any
-     * `readonly C[]` for any `C extends Cmd`. Use in `init` returns and
-     * Transitions cells that emit zero effects:
-     *
-     *   init: (loaded) => [loaded ?? initial, Cmd.none],
-     *   tick: (state) => [state, Cmd.none],
-     *
-     * Elm's `Cmd.none` analogue. Cultural signal alongside the runtime help:
-     * `[state, Cmd.none]` reads as intent ("this transition emits nothing"),
-     * `[state, []]` reads as "empty array of what".
-     *
-     * Frozen at runtime so a downstream consumer can't `.push()` into the
-     * shared reference.
-     */
-    readonly none: readonly never[];
-    /**
-     * Flat concat of cmd arrays. Use when a cell composes effects from
-     * multiple conditional sources:
-     *
-     *   return [next, Cmd.batch(
-     *     Cmd.whenDefined(state.queueItemId, (id) => ({ type: "complete", id })),
-     *     Cmd.when(state.windowId !== undefined, { type: "close_window", windowId }),
-     *     [{ type: "detach_debugger", tabId: state.tabId }],
-     *   )];
-     *
-     * `<const C>` keeps inline cmd literals' discriminants narrow (same
-     * rationale as `when` / `whenDefined` above).
-     */
-    readonly batch: <const C extends Cmd>(...arrs: readonly (readonly C[])[]) => readonly C[];
-    /**
-     * Emit `cmd` wrapped in a single-element array iff `cond` is true.
-     * Otherwise return the empty array. Spreads cleanly into the cmds array
-     * returned by a Transitions cell.
-     *
-     * `const C` (TypeScript 5.0+) keeps the inferred `type:` discriminator
-     * literal narrow when called with an object literal — so `Cmd.when(b,
-     * { type: "x", ... })` infers as `{ type: "x", ... }`, not `{ type:
-     * string, ... }`, and stays assignable to a discriminated-union arm
-     * without `as const` at the call site.
-     */
-    readonly when: <const C extends Cmd>(cond: boolean, cmd: C) => readonly C[];
-    /**
-     * If `value` is defined, call `build(value)` and emit the resulting cmd
-     * wrapped in a single-element array. If `value` is `undefined`, return
-     * the empty array. `value` is narrowed to `T` inside `build`.
-     *
-     * `const C` on the return type keeps the callback's object-literal
-     * `type:` field narrow (see `when` above for the full rationale).
-     */
-    readonly whenDefined: <T, const C extends Cmd>(value: T | undefined, build: (value: T) => C) => readonly C[];
-};
-type SubId = string & {
-    readonly __brand: "SubId";
+
+declare const ReducerBrand: unique symbol;
+type Branded<T> = T & {
+    readonly [ReducerBrand]: true;
 };
 /**
- * Construct a `SubId` from a string. Use this everywhere a Sub literal is
- * built — including ids derived from runtime data (`subId(\`ws:${auditId}\`)`).
- * The brand is structural, not nominal, so dynamic ids are permitted; the
- * constructor's job is to make the identity decision explicit at every call
- * site so the type system can catch accidental raw-string drift.
+ * Compile-time exhaustiveness assertion. Use in default branches of
+ * switches over discriminated unions where every case should be handled
+ * explicitly — TS narrows the type to `never` only if every variant has
+ * been covered. Strengthens invariant 7 (identity is explicit).
  *
- * Strengthens invariant 7 (identity is explicit).
+ * @example
+ *   switch (msg.type) {
+ *     case "a": return ...;
+ *     case "b": return ...;
+ *     default: return absurd(msg);  // compile error if a "c" is added
+ *   }
  */
-declare function subId(s: string): SubId;
-type Sub<T extends string = string> = {
-    id: SubId;
-    type: T;
-};
-interface Port<T> {
-    readonly __brand: "port";
-    readonly name: string;
-    readonly __t?: T;
-}
+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 the `Sub.id` collision assert in
@@ -144,6 +54,85 @@ declare class PortNameCollisionError extends Error {
  * @internal test-only
  */
 declare function __resetPortRegistry(): void;
+/**
+ * Which otherwise-unattributable runtime path produced an error.
+ *
+ * - `"follow-up"` — a follow-up Msg an interpret handler returned rejected
+ *   when re-dispatched. The original dispatcher already resolved, so this
+ *   rejection has no caller; without the sink it was swallowed.
+ * - `"stop-save"` — the final `store.save(state)` inside `stop()` threw.
+ *   `stop()` resolves regardless (its contract), so without the sink this was
+ *   silent loss of the last write.
+ * - `"reduce"` — the pure `update` (reducer) threw synchronously while folding
+ *   a Msg. #71's reentrancy brand makes a reducer provably synchronous, so this
+ *   throw is catchable in the dispatch loop; the configured `Supervision`
+ *   strategy decides what the runtime does next (`stop` / `escalate` /
+ *   `restart`), but the failure is ALWAYS surfaced here as data first.
+ */
+type RuntimeErrorPhase = "follow-up" | "stop-save" | "reduce";
+/** Context handed to an `OnError` sink alongside the error itself. */
+interface RuntimeErrorContext {
+    readonly phase: RuntimeErrorPhase;
+}
+/**
+ * Sink for runtime failures that have no caller to reject at. Configured via
+ * `run(machine, { onError })`. Should be total — a throw inside the sink is
+ * itself surfaced via `defaultOnError`, so the sink can never re-introduce a
+ * silent failure.
+ */
+type OnError = (error: unknown, context: RuntimeErrorContext) => void;
+/** The three declared reducer-throw supervision strategies. */
+type SupervisionStrategy = "stop" | "escalate" | "restart";
+/**
+ * Declared supervision policy for a reducer (`update`) throw, configured at
+ * `run(machine, { supervision })`.
+ *
+ * - `{ strategy: "stop" }` — halt + surface (the safe default; also the bare
+ *   shorthand `"stop"`).
+ * - `{ strategy: "escalate" }` — surface + propagate, runtime stays live (also
+ *   the bare shorthand `"escalate"`).
+ * - `{ strategy: "restart", rehydrate }` — surface, then re-init from the
+ *   host-supplied last-known-good `S` and keep folding. `rehydrate` receives
+ *   the failing `(state, msg, error)` so the host can log / pick a snapshot;
+ *   it MUST return a valid `S` synchronously (the reducer is synchronous, so
+ *   recovery is too — no suspension across the single-writer slot).
+ *
+ * The bare-string shorthands (`"stop"` / `"escalate"`) are accepted for the two
+ * strategies that need no host data; `restart` MUST be the object form because
+ * it carries the `rehydrate` callback.
+ */
+type Supervision<S, M extends {
+    type: string;
+}> = "stop" | "escalate" | {
+    readonly strategy: "stop";
+} | {
+    readonly strategy: "escalate";
+} | {
+    readonly strategy: "restart";
+    /**
+     * Host-provided rehydration to last-known-good state. Invoked by the core
+     * when the reducer throws; its return value becomes the new state and the
+     * transition continues from there. Receives the pre-throw `state`, the
+     * `msg` that triggered the throw, and the thrown `error` so the host can
+     * route by cause.
+     */
+    readonly rehydrate: (state: S, msg: M, error: unknown) => S;
+};
+/**
+ * Raised by `idle()` when the quiescence wait hits its iteration cap without
+ * the dispatch tail stabilizing. Replaces the old silent fall-through-resolve
+ * (which made "the loop quiesced" indistinguishable from "we gave up"):
+ * `idle()` now REJECTS with this so a livelocking machine surfaces instead of
+ * masquerading as quiescent.
+ *
+ * Mechanizes invariant 6 (no silent failures) at the runtime layer — the same
+ * role `PortNameCollisionError` plays for invariant 7.
+ */
+declare class QuiescenceTimeoutError extends Error {
+    readonly iterations: number;
+    readonly name = "QuiescenceTimeoutError";
+    constructor(iterations: number);
+}
 /**
  * Define a typed port. `name` is metadata (shown in devtools / debug logs);
  * port identity is by reference. Each definePort call must use a unique
@@ -159,78 +148,88 @@ declare function __resetPortRegistry(): void;
  * Port-side counterpart of `SubId`'s id collision check in `reconcileSubs`.
  */
 declare function definePort<T>(name: string): Port<T>;
-/**
- * Augmentation injected onto `ctx` inside Cmd handlers. Handlers receive
- * `ctx & PortEmitter` so they can call `ctx.emit(port, value)` synchronously.
- * Subscribers registered via `runtime.subscribePort(port, listener)` receive
- * the value immediately.
- *
- * Emitting to a port with no subscribers is a no-op (does not throw).
- */
-interface PortEmitter {
-    emit<T>(port: Port<T>, value: T): void;
-}
-type Interpret<M extends {
-    type: string;
-}, C extends Cmd, Ctx> = {
-    [K in C["type"]]: (cmd: Extract<C, {
-        type: K;
-    }>, ctx: Ctx & PortEmitter) => Promise<M | void>;
-};
-type Subscribe<M extends {
-    type: string;
-}, U extends Sub, Ctx> = {
-    [K in U["type"]]: (sub: Extract<U, {
-        type: K;
-    }>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-};
-type Machine<S, M extends {
-    type: string;
-}, C extends Cmd, U extends Sub, Ctx> = {
-    /**
-     * Boot the runtime. Called once by `run(...)` with whatever `Store.load()`
-     * returned: `null` on fresh boot, the persisted state on rehydrate.
-     *
-     * **Contract:** when `loaded !== null`, init MUST return `[loaded, []]` —
-     * no Cmds. Init's rehydrate branch is the migration / parse boundary, not
-     * the boot-effect hook. See Invariant 2 in `.patterns/tea/tea-invariants.md`.
-     *
-     * Boot effects routes:
-     *   - Stateless infrastructure → host module top, outside TEA.
-     *   - State-conditional resume → a `boot` Msg the host dispatches once
-     *     after `run(...)` returns.
-     *
-     * Violations are caught at runtime by `replay` (which throws with a
-     * pointer to the alternatives).
-     */
-    init: (loaded: S | null, ctx: Ctx) => readonly [S, readonly C[]];
-    update: Reducer<S, M, C> | ([S] extends [{
-        type: string;
-    }] ? Transitions<S, M, C> : never);
-    subscriptions?: (state: S) => readonly U[];
-    subscribe?: Subscribe<M, U, Ctx>;
-} & ([C] extends [Cmd<never>] ? {
-    interpret?: Interpret<M, C, Ctx>;
-} : {
-    interpret: Interpret<M, C, Ctx>;
-});
 interface Store<S> {
     load(): Promise<unknown>;
     save(state: S): Promise<void>;
     migrate(raw: unknown): S | null;
 }
+type DispatchSettle = "quiescent" | "once";
 interface RuntimeRef<M extends {
     type: string;
 }> {
-    dispatch(msg: M): Promise<void>;
+    /**
+     * Put a Msg in the runtime's inbox and resolve once it has been processed.
+     *
+     * Runs to QUIESCENCE by default (issue #50): the returned promise settles
+     * only after the dispatched Msg AND every follow-up Msg its `interpret`
+     * handlers (transitively) returned have drained off the serial tail. This is
+     * the safe default — `await dispatch(msg)` means "the consequences have run",
+     * not "one transition fired and the rest are racing". Pass
+     * `{ settle: "once" }` (or call `dispatchOnce`) for the rare single-step
+     * case where the caller will await the tail itself.
+     *
+     * Rejection ordering: the ONE dispatched transition's own failure (a reducer
+     * / save / sub-start / interpret throw) surfaces first, on this promise. If
+     * that transition succeeds but the follow-up chain never stabilizes, the
+     * quiescent drain rejects with `QuiescenceTimeoutError` (same cap and same
+     * no-silent-give-up contract as `idle()` — issue #51). Follow-up Msg
+     * rejections themselves route to the `onError` sink, never here.
+     */
+    dispatch(msg: M, opts?: {
+        readonly settle?: DispatchSettle;
+    }): Promise<void>;
+    /**
+     * Dispatch `msg` and resolve after exactly ONE transition's effects settle,
+     * WITHOUT draining the follow-up chain. Equivalent to
+     * `dispatch(msg, { settle: "once" })`.
+     *
+     * This is the old (pre-#50) `dispatch` behavior, kept as an explicit escape
+     * hatch: a caller that wants to interleave its own work between the first
+     * transition and its follow-ups, then `await runtime.idle()` itself. Prefer
+     * plain `dispatch` (run-to-quiescence) unless you specifically need the
+     * single step — the un-awaited follow-up chain is exactly the footgun #50
+     * removed from the default.
+     */
+    dispatchOnce(msg: M): Promise<void>;
 }
-interface Runtime<S, M extends {
+interface BootingRuntime<S, M extends {
     type: string;
-}> extends RuntimeRef<M> {
-    dispatch(msg: M): Promise<void>;
-    getState(): S;
+}, E extends {
+    type: string;
+} = never> extends RuntimeRef<M> {
+    dispatch(msg: M, opts?: {
+        readonly settle?: DispatchSettle;
+    }): Promise<void>;
+    dispatchOnce(msg: M): Promise<void>;
     subscribe(listener: () => void): () => void;
-    observe(observer: (msg: M | null, state: S) => void): () => void;
+    observe(observer: (msg: M, state: S) => void): () => void;
+    /**
+     * Subscribe to the INITIAL State — the boot transition the old `observe`
+     * `msg === null` arm carried (#47). Fires exactly once: immediately if boot
+     * has already completed when `onBoot` is called (so a late subscriber never
+     * misses it), otherwise on the boot fanout. Returns a cleanup that detaches
+     * the handler (a no-op once it has fired).
+     *
+     * This is where the boot case the `observe` firehose used to fold in went
+     * once `observe`'s `msg` became total: a consumer that needs to seed a view
+     * from the initial State wires `onBoot`; a consumer that only folds events
+     * (the common case) wires `observe` (or `on`) and is no longer handed a boot
+     * arm to skip.
+     */
+    onBoot(handler: (state: S) => void): () => void;
+    /**
+     * Subscribe to a SEMANTIC event of `type` (#47). Typed narrowing: the handler
+     * receives exactly the `E` member whose `type` matches `K`, so a consumer
+     * built on `on("TurnSettled", …)` never touches another event's shape and —
+     * critically — never references the machine's PRIVATE Msg names. Returns a
+     * cleanup that detaches the handler. Multiple handlers per type are
+     * supported; fanout is synchronous and throw-isolated (same discipline as
+     * `observe`). Fires only when the machine's `events` projector (wired on
+     * `run`) emits an event of that type for a transition.
+     */
+    on<K extends E["type"]>(type: K, handler: (event: Extract<E, {
+        type: K;
+    }>) => void): () => void;
     /**
      * Subscribe to a typed Port. Returns a cleanup function that removes the
      * listener. Multiple listeners per port are supported; fanout is synchronous
@@ -263,26 +262,119 @@ interface Runtime<S, M extends {
      */
     emitPort<T>(port: Port<T>, value: T): void;
     /**
-     * Resolves after boot completes — i.e. after `store.load()` (if any), `init`,
-     * `store.save()` of the initial state, `reconcileSubs`, `interpret` of any
-     * init-emitted cmds, and the initial listener / observer fanout. Rejects with
-     * the boot error if boot fails (the same error every subsequent `dispatch`
-     * call rejects with).
+     * Resolves to the booted `Runtime<S, M>` after boot completes — i.e. after
+     * `store.load()` (if any), `init`, `store.save()` of the initial state,
+     * `reconcileSubs`, `interpret` of any init-emitted cmds, and the initial
+     * listener / observer fanout. Rejects with the boot error if boot fails (the
+     * same error every subsequent `dispatch` call rejects with).
+     *
+     * This is the ONLY way to obtain a `Runtime<S, M>` — and a `Runtime` is the
+     * only handle whose `getState()` is total. Awaiting `ready` is therefore the
+     * single gate between "boot in flight" and "State exists":
+     *
+     * ```ts
+     * const runtime = await run(machine, opts).ready;
+     * runtime.getState(); // total — never throws-before-boot
+     * ```
      *
      * Idempotent — subsequent reads return the same settled promise. The runtime
-     * holds exactly one `ready` promise per `run()` call.
+     * holds exactly one `ready` promise per `run()` call; it resolves to the same
+     * `Runtime` object every time.
      *
-     * Closes the v1 boot-await gap previously documented in `stepBootEffects`:
-     * components that need synchronous initial state under a store (e.g.,
-     * `useSyncExternalStore` consumers) can `await runtime.ready` instead of
-     * `runtime.dispatch(noopMsg)`.
+     * Closes issue #45 (the `getState()` lie) and the v1 boot-await gap once
+     * documented in `stepBootEffects`: components that need synchronous initial
+     * state under a store (e.g. `useSyncExternalStore` consumers) await `ready`
+     * for the booted runtime instead of dispatching a no-op Msg.
      *
      * Expresses canon §2.3 (the `init` contract — boot is a named, awaitable
      * moment). Strengthens invariant 6 (runtime is small and inspectable).
      */
-    ready: Promise<void>;
+    ready: Promise<Runtime<S, M, E>>;
     stop(): Promise<void>;
 }
+interface Runtime<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never> extends BootingRuntime<S, M, E> {
+    /**
+     * The current State. TOTAL — never throws. Obtaining a `Runtime` requires
+     * awaiting `ready`, which only resolves AFTER boot has run `init` and set the
+     * initial State; a `Runtime` therefore always has a State to return. (Before
+     * #45 this was declared on the synchronously-returned handle and threw under
+     * a store until boot finished — the type lied. It no longer does.)
+     */
+    getState(): S;
+    /**
+     * Resolves to this same `Runtime` once boot completes. Idempotent.
+     */
+    ready: Promise<Runtime<S, M, E>>;
+    /**
+     * Resolves once the runtime has reached QUIESCENCE — every dispatched Msg AND
+     * every follow-up Msg an interpret handler returned has been processed, with
+     * no further step pending on the serial tail.
+     *
+     * Since #50, plain `dispatch(msg)` already runs to quiescence (it awaits this
+     * same drain after its own transition), so a caller rarely needs `idle()`
+     * directly. `idle()` is still the right tool to (a) settle follow-ups left in
+     * flight by a `dispatchOnce` / `dispatch(msg, { settle: "once" })` single
+     * step, or (b) wait out a follow-up chain kicked off by a Sub or by boot
+     * `init` cmds where there was no `dispatch` call to await. It chains onto the
+     * current tail and re-checks until the tail stops advancing, draining the
+     * entire transitive follow-up chain.
+     *
+     * Idempotent and re-entrant-safe: each call reads the live tail; a tail that
+     * advanced during the await (a follow-up landed) is awaited again until
+     * stable. Tail rejections are NOT surfaced here — a failing dispatch
+     * surfaces on its OWN returned promise (and follow-up rejections route to
+     * the `onError` sink). The ONE rejection `idle()` itself produces is a
+     * `QuiescenceTimeoutError` when the wait hits its iteration cap without the
+     * tail stabilizing: that replaces the old silent fall-through-resolve so a
+     * livelocking machine is distinguishable from a genuinely quiesced one
+     * (invariant 6 — no silent failures).
+     *
+     * Use `idle()` for runtime-internal follow-ups; a poll is still correct when
+     * waiting on an EXTERNAL event (a WS reply) the runtime cannot enqueue itself.
+     *
+     * Strengthens invariant 6 (runtime is small and inspectable — quiescence is a
+     * first-class awaitable moment, not a poll the consumer re-derives).
+     */
+    idle(): Promise<void>;
+    /**
+     * The terminal State of the run, or `undefined` while it is still in flight.
+     * A run is "terminal" exactly when the `terminal` predicate passed to `run()`
+     * returns `true` for the current State; with no predicate supplied a run is
+     * never terminal and this always returns `undefined`.
+     *
+     * This is the FIRST-CLASS result read (issue #46): the outcome of running the
+     * thing, off the State the machine already owns — NOT scraped off the
+     * `observe` firehose by matching an internal Msg name (`resilient_ok`) and
+     * racing a state-clear. The consumer reads the run's product (e.g. an agent's
+     * `state.output`) off the returned `S`, with no coupling to the machine's
+     * private retry / loop vocabulary.
+     *
+     * Total — never throws (a `Runtime` always has a State; see `getState`).
+     */
+    result(): S | undefined;
+    /**
+     * Resolves with the terminal State the first time the run reaches a terminal
+     * State (per the `terminal` predicate passed to `run()`). If the run is
+     * ALREADY terminal when `done()` is called, resolves immediately with the
+     * current State; otherwise resolves on the transition that first makes
+     * `terminal` hold.
+     *
+     * The awaitable companion to `result()` — "wait for the run to finish, then
+     * hand me what it produced" in one call, instead of polling `result()` or
+     * hand-rolling an `observe` loop that watches for a private terminal Msg.
+     * With no `terminal` predicate supplied the run is never terminal, so this
+     * promise never resolves (a non-terminating machine has no result to await).
+     *
+     * Idempotent and multi-caller safe: every call observes the live State, so a
+     * call made after the run already terminated resolves at once, and concurrent
+     * callers all settle on the same terminal transition.
+     */
+    done(): Promise<S>;
+}
 declare function defineMachine<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(m: Omit<Machine<S, M, C, U, Ctx>, "update"> & {
@@ -295,12 +387,66 @@ declare function defineMachine<S, M extends {
 }, C extends Cmd, U extends Sub, Ctx>(m: Omit<Machine<S, M, C, U, Ctx>, "update"> & {
     update: Reducer<S, M, C>;
 }): Machine<S, M, C, U, Ctx>;
-declare function run<S, M extends {
+declare function asReducer<S, M extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
+}, C extends Cmd>(reducer: Reducer<S, M, C>): Branded<Reducer<S, M, C>>;
+type CtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
+    ctx?: Ctx;
+} : {
     ctx: Ctx;
+};
+declare function run<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: CtxArg<Ctx> & {
     store?: Store<S>;
-}): Runtime<S, M>;
+    onError?: OnError;
+    /**
+     * The SEMANTIC event projector (#47). Maps one APPLIED transition `(msg,
+     * state)` to zero-or-more public events of the machine-level union `E`.
+     * Returning `[]` skips the transition (it produced no event the consumer's
+     * `on(type, …)` cares about). This is where a machine maps its PRIVATE Msg
+     * vocabulary (a retry plumbing's `resilient_ok`, a tool loop's
+     * `agent_tool_ok`) to NAMED events — the private names live only inside this
+     * closure and never reach `on`'s `E` surface. Omit → the run has no event
+     * surface (`E = never`) and `on` is uncallable.
+     *
+     * PURE — called inside the dispatch loop on the freshly-folded `(msg,
+     * state)`; it must not read the clock, mutate, or throw (a throw is
+     * isolated like an observer throw, never stranding the transition).
+     */
+    events?: (msg: M, state: S) => readonly E[];
+    /**
+     * Declared policy for when the pure `update` (reducer) throws. The reducer
+     * throw is always surfaced via `onError` (`phase: "reduce"`); the strategy
+     * decides what the runtime does next. Defaults to `"stop"` — the explicit,
+     * safe choice (surface + halt, never a silent resume). See `Supervision`.
+     */
+    supervision?: Supervision<S, M>;
+    /**
+     * The run-terminality predicate — what makes the run's outcome first-class
+     * (issue #46). Returns `true` for a State the run has finished in (e.g. an
+     * agent's `state.run.phase === "done"`). The runtime feeds it to
+     * `Runtime.result()` (the terminal State, or `undefined` in flight) and
+     * `Runtime.done()` (resolves with the terminal State when it first holds).
+     *
+     * PURE — the runtime calls it inside the dispatch loop on the freshly-folded
+     * State; it must not read the clock, mutate, or throw. Omit → the run is
+     * never terminal: `result()` always returns `undefined` and `done()` never
+     * resolves (the right behavior for a machine with no natural completion).
+     */
+    terminal?: (state: S) => boolean;
+    /**
+     * Iteration cap for `idle()`'s quiescence wait. Defaults to 100_000. Test
+     * seam only — lets a livelock test trip the `QuiescenceTimeoutError` reject
+     * path in a handful of iterations instead of 100k. Production code must not
+     * set it.
+     *
+     * @internal test-only
+     */
+    __idleCap?: number;
+}): BootingRuntime<S, M, E>;
 interface HistoryTracker<S, M extends {
     type: string;
 }> {
@@ -335,11 +481,15 @@ interface HistoryTracker<S, M extends {
  * to the runtime via `observe(...)` and retains the last `size` `(msg,
  * state)` transitions in a FIFO ring buffer.
  *
- * @param runtime  Any `Runtime<S, M>`. The tracker uses only `observe`.
- * @param size     Buffer cap. `size <= 0` produces a tracker whose
- *                 snapshot is always `[]` (the observer is still attached
- *                 but pushes a no-op; cheaper to skip the tracker entirely
- *                 in that case).
+ * @param runtime  Any `BootingRuntime<S, M>` (a full `Runtime` satisfies it).
+ *                 The tracker uses only `observe`, which is total before boot —
+ *                 attach it to the synchronous `run()` handle to record the
+ *                 boot transition.
+ * @param size     Buffer cap. `size <= 0` produces an inert no-op tracker:
+ *                 no observer is attached to the runtime, `snapshot()` is
+ *                 always `[]`, and `stop()` is a no-op. (Prefer skipping the
+ *                 tracker entirely in that case — this arm just makes a
+ *                 non-positive `size` harmless rather than an error.)
  *
  * Memory cost: O(size × avg(msg + state size)). For audit-extension's
  * inspector use case (size 100, audit state ~5KB), ~500KB max — held
@@ -347,7 +497,7 @@ interface HistoryTracker<S, M extends {
  */
 declare function historyTracker<S, M extends {
     type: string;
-}>(runtime: Runtime<S, M>, size: number): HistoryTracker<S, M>;
+}>(runtime: BootingRuntime<S, M>, size: number): HistoryTracker<S, M>;
 declare function replay<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
@@ -361,4 +511,4 @@ declare function replay<S, M extends {
 };
 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 { Cmd, type HistoryTracker, type Interpret, type Machine, type Port, type PortEmitter, PortNameCollisionError, type Reducer, type Runtime, type RuntimeRef, type Store, type Sub, type SubId, type Subscribe, type Transitions, __resetPortRegistry, absurd, defineMachine, definePort, historyTracker, noop, replay, run, subId, tryInterpret };
+export { type BootingRuntime, type Branded, Cmd, type CtxArg, type DispatchSettle, type HistoryTracker, Machine, type OnError, Port, PortNameCollisionError, QuiescenceTimeoutError, Reducer, type Runtime, type RuntimeErrorContext, type RuntimeErrorPhase, type RuntimeRef, type Store, Sub, type Supervision, type SupervisionStrategy, Transitions, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, tryInterpret };

package/dist/index.js

@@ -1,3 +1,4 @@
-export { Cmd, PortNameCollisionError, __resetPortRegistry, absurd, defineMachine, definePort, historyTracker, noop, replay, run, subId, tryInterpret } from './chunk-CMG2KMWX.js';
+export { PortNameCollisionError, QuiescenceTimeoutError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, tryInterpret } from './chunk-MMH7CW5K.js';
+export { Cmd, applyCell, detectUpdateForm, foldMsgs, formOf, msgKeysOf, subId } from './chunk-QLA76GIT.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map