@demlik/tea 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,476 +1,15 @@
-import { C as Cmd, P as Port, S as Sub, M as Machine, T as Transitions, R as Reducer } from './core-BmlJOvxM.js';
-export { b as ContextFree, I as Interpret, j as NoCellError, 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-BmlJOvxM.js';
+import { B as BootingRuntime, C as CtxArg, S as Store, O as OnError, a as Supervision } from './runtime-types-CukV8kMX.js';
+export { b as Branded, D as DispatchDiscardedError, l as DispatchSettle, P as PortNameCollisionError, Q as QuiescenceTimeoutError, R as Runtime, h as RuntimeDiscardNotice, i as RuntimeDiscardedError, f as RuntimeErrorContext, e as RuntimeErrorPhase, m as RuntimeRef, k as Schema, d as SubIdCollisionError, g as SupervisionStrategy, _ as __resetPortRegistry, c as absurd, p as asReducer, o as defineMachine, j as definePort, n as noop, r as replay, s as schemaMigrate, t as tryInterpret, w as wrapDetached } from './runtime-types-CukV8kMX.js';
+import { C as Cmd, S as Sub, M as Machine } from './core-42kapW0n.js';
+export { d as ContextFree, D as DepKeyedSub, e as Dispose, f as Identity, c as Interpret, I as InterpretDetached, n as NoCellError, N as NoCtx, P as Port, b as PortEmitter, R as Reducer, a as SubId, g as Subscribe, h as SyncReturn, T as Transitions, U as UpdateForm, i as applyCell, j as detectUpdateForm, k as foldMsgs, l as formOf, m as msgKeysOf, s as structuralHash, o as subId } from './core-42kapW0n.js';
 
-/**
- * @demlik/tea — TEA-faithful state machine substrate.
- *
- * This module exposes the full Locked API Surface from the PRD as types and
- * implements `defineMachine` (identity, task 1), `run` (task 2), and
- * `replay` + `tryInterpret` (task 3).
- *
- * `replay` is the pure unit-test tool: it composes `init` + `update` only,
- * never touches `Store`, never calls `interpret`, never starts subscriptions.
- *
- * `tryInterpret` is Railway sugar — wraps a fallible async function and routes
- * Ok/Err to two Msg constructors via better-result.
- */
-
-declare const ReducerBrand: unique symbol;
-type Branded<T> = T & {
-    readonly [ReducerBrand]: true;
-};
-/**
- * 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[]];
-/**
- * Thrown by `definePort` when a name has already been registered in the
- * current process. Symmetric with the `Sub.id` collision assert in
- * `reconcileSubs` — both mechanize invariant 7 (identity is explicit) at the
- * runtime layer the type system cannot reach (string names compared at
- * runtime, not at compile time).
- */
-declare class PortNameCollisionError extends Error {
-    readonly name = "PortNameCollisionError";
-    constructor(portName: 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
- * non-isolated runs. Production code MUST NOT call this; the registry is the
- * invariant-7 witness for the process lifetime.
- *
- * @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.
- *
- * The fanout phases (#277). Every fanout is throw-isolated so one bad
- * consumer never strands its siblings — and the isolated throw routes here
- * rather than to a bare `console.error`, so a sink wired to e.g. Sentry sees
- * every "no caller to reject at" failure:
- *
- * - `"listener"` — a `runtime.subscribe(...)` listener threw during the
- *   post-transition fanout.
- * - `"observer"` — a `runtime.observe(...)` observer threw during the
- *   post-transition fanout.
- * - `"event"` — the semantic-event path threw: either the `events` projector
- *   itself, or an `on(type, ...)` handler.
- * - `"boot"` — an `onBoot` handler threw (at the boot fanout, or on the
- *   immediate fire of a late post-boot registration).
- * - `"port-emit"` — a `subscribePort` listener threw during a port emission.
- * - `"sub-cleanup"` — a subscription's cleanup threw (on reconcile-removal,
- *   or during `stop()` teardown).
- */
-type RuntimeErrorPhase = "follow-up" | "stop-save" | "reduce" | "listener" | "observer" | "event" | "boot" | "port-emit" | "sub-cleanup";
-/** 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
- * `name` — a second call with the same name throws
- * `PortNameCollisionError`. If two modules need the same port, export it
- * from one module and import it from the other.
- *
- * Use ports for "data leaving the runtime selectively" — e.g. cursor
- * announcements, DOM-mutation broadcasts, telemetry events that should NOT be
- * folded into State and should NOT be observed by every transition listener.
- *
- * Strengthens invariant 7 (identity is explicit) — the runtime assert is the
- * Port-side counterpart of `SubId`'s id collision check in `reconcileSubs`.
- */
-declare function definePort<T>(name: string): Port<T>;
-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;
-}> {
-    /**
-     * 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 BootingRuntime<S, M extends {
-    type: string;
-}, 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, 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
-     * (same shape as `observe`) and isolated — one listener throw does not strand
-     * the others.
-     *
-     * Ports are for "data leaving the runtime selectively" — see `definePort`.
-     * Distinct from `observe` (every transition) and from State (the world).
-     */
-    subscribePort<T>(port: Port<T>, listener: (value: T) => void): () => void;
-    /**
-     * Emit a value on a Port from OUTSIDE an interpret handler. Same synchronous
-     * fanout discipline as `ctx.emit` inside interpret — every subscriber
-     * receives the value immediately; emitting to a port with no subscribers is
-     * a no-op; listener throws are isolated.
-     *
-     * Use this for `observe`-driven Port emission: the canonical case is one
-     * runtime publishing a state-derived signal (e.g. "am I idle?") that
-     * another runtime subscribes to via `subscribePort`. Without
-     * `runtime.emitPort`, the only way to emit a Port is from inside an
-     * `interpret` handler — which forces the reducer to spawn a "tell the
-     * outside world" Cmd on every transition that should signal. With it,
-     * `runtime.observe((msg, state) => runtime.emitPort(port, derive(state)))`
-     * keeps the reducer free of Port-plumbing Cmds and matches the "every
-     * transition is observable" contract this invariant set already commits to.
-     *
-     * Strengthens invariant 6 (runtime is small and inspectable — Port emission
-     * is no longer privileged to interpret handlers; `observe`-driven emission
-     * is structurally supported).
-     */
-    emitPort<T>(port: Port<T>, value: T): void;
-    /**
-     * 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; it resolves to the same
-     * `Runtime` object every time.
-     *
-     * 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<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"> & {
-    update: [S] extends [{
-        type: string;
-    }] ? Transitions<S, M, C> : never;
-}): Machine<S, M, C, U, Ctx>;
-declare function defineMachine<S, M extends {
-    type: string;
-}, 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 asReducer<S, M extends {
-    type: string;
-}, 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>;
-    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;
 }> {
     /**
      * Snapshot of recorded transitions, oldest first. Each entry is
-     * `{ msg, state }` exactly as the underlying `observe` callback received
-     * it — `msg` is `null` for the boot transition, a Msg for every other.
+     * `{ msg, state }`: `msg` is `null` for the boot transition (recorded via
+     * `onBoot`) and the applied Msg for every other (recorded via `observe`).
      *
      * Returns a shallow copy: the array is fresh on every call (callers may
      * iterate, slice, or replay without affecting the tracker's buffer).
@@ -494,9 +33,9 @@ interface HistoryTracker<S, M extends {
     stop(): void;
 }
 /**
- * Create a bounded history tracker over a Runtime. The tracker subscribes
- * to the runtime via `observe(...)` and retains the last `size` `(msg,
- * state)` transitions in a FIFO ring buffer.
+ * Create a bounded history tracker over a Runtime. The tracker subscribes to
+ * the runtime via `observe(...)` and retains the last `size` `(msg, state)`
+ * transitions in a FIFO ring buffer.
  *
  * @param runtime  Any `BootingRuntime<S, M>` (a full `Runtime` satisfies it).
  *                 The tracker uses only `observe`, which is total before boot —
@@ -504,28 +43,50 @@ interface HistoryTracker<S, M extends {
  *                 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
- * in-memory only, no persistence.
+ *                 always `[]`, and `stop()` is a no-op.
  */
 declare function historyTracker<S, M extends {
     type: string;
 }>(runtime: BootingRuntime<S, M>, size: number): HistoryTracker<S, M>;
-declare function replay<S, M extends {
+
+/**
+ * @demlik/tea runtime — `run`: boot + the serial dispatch loop. The pure helpers
+ * that compose against a machine without running it (`replay`, `tryInterpret`)
+ * live in `./runtime-types`.
+ */
+
+declare function run<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, E extends {
     type: string;
-}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
-    msgs: readonly M[];
-    ctx: Ctx;
-    loaded?: S | null;
-}): {
-    state: S;
-    cmds: C[];
-    subs: U[];
-};
-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>;
+} = never>(machine: Machine<S, M, C, U, Ctx>, opts: CtxArg<Ctx> & {
+    store?: Store<S>;
+    onError?: OnError;
+    /**
+     * The SEMANTIC event projector. Maps one APPLIED transition `(msg, state)`
+     * to zero-or-more public events of `E`; `[]` skips the transition. Maps the
+     * machine's PRIVATE Msg vocabulary to NAMED events — the private names never
+     * reach `on`'s `E` surface. Omit → `E = never` and `on` is uncallable. PURE.
+     */
+    events?: (msg: M, state: S) => readonly E[];
+    /**
+     * Declared policy for a reducer (`update`) throw. Always surfaced via
+     * `onError` (`phase: "reduce"`); the strategy decides what the runtime does
+     * next. Defaults to `"stop"`. See `Supervision`.
+     */
+    supervision?: Supervision<S, M>;
+    /**
+     * The run-terminality predicate — makes the run's outcome first-class. Fed to
+     * `Runtime.result()` and `Runtime.done()`. PURE. Omit → never terminal.
+     */
+    terminal?: (state: S) => boolean;
+    /**
+     * Iteration cap for `idle()`'s quiescence wait. Defaults to 100_000. Test
+     * seam only. Production code must not set it.
+     *
+     * @internal test-only
+     */
+    __idleCap?: number;
+}): BootingRuntime<S, M, E>;
 
-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 };
+export { BootingRuntime, Cmd, CtxArg, type HistoryTracker, Machine, OnError, Store, Sub, Supervision, historyTracker, run };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { PortNameCollisionError, QuiescenceTimeoutError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, tryInterpret } from './chunk-6VDCTR7N.js';
-export { Cmd, NoCellError, applyCell, detectUpdateForm, foldMsgs, formOf, msgKeysOf, subId } from './chunk-DYRKDCJI.js';
+export { DispatchDiscardedError, PortNameCollisionError, QuiescenceTimeoutError, RuntimeDiscardNotice, RuntimeDiscardedError, SubIdCollisionError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, schemaMigrate, tryInterpret, wrapDetached } from './chunk-D4NJBQAH.js';
+export { Cmd, NoCellError, applyCell, detectUpdateForm, foldMsgs, formOf, msgKeysOf, structuralHash, subId } from './chunk-PBDYW2TU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/llm-call/index.d.ts

@@ -1,15 +1,16 @@
-import { C as Cmd } from '../core-BmlJOvxM.js';
+import { C as Cmd } from '../core-42kapW0n.js';
 import { SucceedMsg, FailMsg, RunCmd, ResilientState } from '../resilient-call/index.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
 import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
 export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
 import '../cache/index.js';
-import '../types-BoUWgwSm.js';
+import '../types-KbL3W1mj.js';
 import '../circuit-breaker/index.js';
 import '../protocol-B5YmJr0d.js';
 import '../rate-limit/index.js';
 
 /**
+ * @packageDocumentation
  * @demlik/tea/llm-call — `resilient-call` + structured-output parse + a typed
  * failure variant, around a purpose-discriminated LLM invocation.
  *

package/dist/llm-call/index.js

@@ -1,14 +1,16 @@
-export { createLlmCall, liftLlmCall } from '../chunk-M6UZT7HS.js';
-import '../chunk-6GIGQT6C.js';
+export { createLlmCall, liftLlmCall } from '../chunk-FCKP6N7Y.js';
+import '../chunk-B5RAZVXW.js';
 import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-SKAMZKTE.js';
-import '../chunk-5VNWZADP.js';
-import '../chunk-2YOE5PIS.js';
-import '../chunk-SC3FAFZN.js';
-import '../chunk-IN33Q4VJ.js';
-import '../chunk-NSDFA6M6.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-RMX4EOQK.js';
+import '../chunk-Q2UM7BXU.js';
+import '../chunk-S2EGRPCM.js';
+import '../chunk-UF4MZSLT.js';
+import '../chunk-2KNLKQVN.js';
+import '../chunk-LYLDCIPH.js';
 import '../chunk-2YFLOCWX.js';
-import '../chunk-6VDCTR7N.js';
-import '../chunk-DYRKDCJI.js';
+import '../chunk-ZJ5AOYBH.js';
+import '../chunk-G5E74IJB.js';
+import '../chunk-D4NJBQAH.js';
+import '../chunk-PBDYW2TU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map