@demlik/tea 0.1.2 → 0.3.0

package/dist/retry-backoff/index.d.ts

@@ -1,4 +1,5 @@
 /**
+ * @packageDocumentation
  * @demlik/tea/retry-backoff — exponential backoff with jitter + cap, and the
  * retry-attempt state every fallible `interpret` handler folds over.
  *
@@ -20,6 +21,13 @@
  *   const delayMs = nextDelayMs(retry, policy);              // pure: rng injected at call site
  *   return [{ ...state, retry }, [{ type: "ScheduleRetry", delayMs, into: TimerFiredRetry }]];
  *
+ * and the same wiring under a wall-clock outage budget, where the failure Msg
+ * carries the instant it was observed:
+ *
+ *   // policy: { baseMs: 250, factor: 2, capMs: 4_000, maxElapsedMs: 1_050_000, jitter: "full" }
+ *   const retry = recordFailure(state.retry, msg.error, msg.at);
+ *   if (!shouldRetry(retry, policy, msg.at)) return [toGaveUp(state, retryElapsedMs(retry, msg.at)), []];
+ *
  * The reducer stays pure: `nextDelayMs` is called with the runtime's RNG only
  * at the emit boundary (or the caller defers the whole delay computation to the
  * `interpret` handler and passes `rng` there). Either way the substrate never
@@ -27,6 +35,42 @@
  *
  * NOT a substrate primitive: it depends on nothing from `../index`. It is a
  * leaf utility consumers reach via the `@demlik/tea/retry-backoff` subpath.
+ *
+ * ── THE BOUND MAY BE A DURATION, NOT ONLY A COUNT ──────────────────────────
+ * `maxAttempts` was the module's only terminal bound, and a count is the wrong
+ * bound whenever this ladder nests inside somebody else's ladder. A downstream
+ * consumer proved it in production: 4 restarts over a 250ms→4s ladder is ~3.75s
+ * of backoff, which nested under a client's own ~2.5s ladder came to roughly
+ * SIXTEEN SECONDS of total patience — against a peer that waits ~17.5 MINUTES
+ * before it gives up on the other side. A routine deploy outran the budget and
+ * killed 170 runs in 7 days that the peer would have resumed from a checkpoint.
+ *
+ * The failure a count cannot express is that the QUESTION is temporal. "How
+ * long do we tolerate an unreachable peer" has an answer in seconds, usually
+ * derived from the peer's own give-up window; what a count of attempts costs in
+ * seconds depends on how long each attempt takes, which is the carrier's
+ * business and not the policy's. So a policy may now declare `maxElapsedMs` —
+ * a wall-clock outage budget measured from the FIRST failure of the streak —
+ * instead of, or in addition to, `maxAttempts`. When both are declared, retry
+ * continues only while EVERY declared bound still permits it.
+ *
+ * TIME IS AN INPUT, NOT AN AMBIENT READ (invariant 2). The streak's origin is
+ * supplied by the caller to `recordFailure`, and `shouldRetry` is told `nowMs`;
+ * this module still never reads a clock, exactly as it never reads the RNG.
+ * The types make the wiring the only wiring that compiles: a duration-bounded
+ * policy only satisfies the `shouldRetry` overload that demands a
+ * {@link TimedRetryState} *and* a `nowMs`, so "declared an outage budget, never
+ * fed it a clock" is a type error rather than a bound that quietly never fires.
+ *
+ * A policy with NO bound at all is likewise unrepresentable by accident — the
+ * {@link RetryBudget} union has no "neither" arm; forever-retry must be spelled
+ * `unbounded: true` ({@link UnboundedRetryPolicy}).
+ *
+ * Strengthens invariant 2 (transitions are pure — the clock enters as an
+ * argument, never as a `Date.now()` inside the fold) and invariant 5
+ * (composition is by reduction — the new bound is an additive arm on the policy
+ * union and an optional argument on the verbs, so every existing count-bounded
+ * call site keeps compiling untouched).
  */
 /**
  * Jitter strategy applied to the computed backoff delay.
@@ -82,25 +126,107 @@ declare function asRng(fn: () => number, probe?: boolean): Rng;
  */
 declare const defaultRng: Rng;
 /**
- * A retry policy is pure configuration — the knobs of the backoff curve. It
- * carries no mutable state; `RetryState` does. One policy is shared across all
- * the attempts of one logical operation (often a module-scope const).
+ * The shape of the delay ladder, with no terminal bound attached — `baseMs`,
+ * `factor`, `capMs`, `jitter`. Split out from the policy because the curve and
+ * the bound answer different questions: the curve is "how fast do we come
+ * back", the bound is "when do we stop". `backoffDelay` needs only the curve.
  */
-interface RetryPolicy {
+interface BackoffCurve {
     /** Delay for attempt 0, in milliseconds, before any jitter or cap. */
     readonly baseMs: number;
     /** Geometric growth factor. `2` doubles the delay each attempt. */
     readonly factor: number;
     /** Hard ceiling, in milliseconds. The capped exponential never exceeds this. */
     readonly capMs: number;
+    /** Jitter strategy applied to the capped exponential delay. */
+    readonly jitter: Jitter;
+}
+/**
+ * Bound by ATTEMPT COUNT — the original bound, and the right one when each
+ * attempt costs about the same and the caller is the outermost ladder.
+ *
+ * `maxElapsedMs: never` is what keeps this arm honest: a count-bounded policy
+ * is *declared* to have no outage budget, so it satisfies the clock-free
+ * `shouldRetry` overload. Add `maxElapsedMs` and it becomes a
+ * {@link DurationRetryPolicy}, which no longer does.
+ */
+interface CountBound {
     /**
      * Maximum number of attempts. `shouldRetry` allows attempts `0 .. maxAttempts-1`,
      * so `maxAttempts: 3` means "try once, then retry at most twice" (attempts 0, 1, 2).
      */
     readonly maxAttempts: number;
-    /** Jitter strategy applied to the capped exponential delay. */
-    readonly jitter: Jitter;
+    readonly maxElapsedMs?: never;
+    readonly unbounded?: never;
+}
+/**
+ * Bound by WALL-CLOCK OUTAGE DURATION, optionally also by count.
+ *
+ * `maxElapsedMs` is measured from the FIRST failure of the current streak
+ * ({@link TimedRetryState.firstFailureAtMs}), not from the last attempt: the
+ * question it answers is "how long has the far side been unreachable", which is
+ * the question a nesting caller's own patience is denominated in. Derive it
+ * from the peer's give-up window rather than restating a guess — two sides
+ * holding different answers to one ordered fact is the defect this bound
+ * exists to prevent.
+ *
+ * `maxAttempts` stays available here, and when both are present retry continues
+ * only while BOTH still permit it (see {@link shouldRetry}). Adding a count to a
+ * duration budget is a belt-and-braces guard against a pathologically fast
+ * failure loop, not a substitute for the duration.
+ */
+interface DurationBound {
+    /**
+     * Outage budget in wall-clock milliseconds. `shouldRetry` permits another
+     * attempt while `nowMs - firstFailureAtMs < maxElapsedMs`, however many
+     * attempts that takes.
+     */
+    readonly maxElapsedMs: number;
+    /** Optional secondary count bound; omitted means "no count bound". */
+    readonly maxAttempts?: number;
+    readonly unbounded?: never;
+}
+/**
+ * No bound at all — retry forever. Deliberately verbose and deliberately the
+ * only way to say it: {@link RetryBudget} has no "neither bound declared" arm,
+ * so an infinite retry loop is something a policy author must write down, never
+ * something a forgotten field produces.
+ */
+interface Unbounded {
+    readonly unbounded: true;
+    readonly maxAttempts?: never;
+    readonly maxElapsedMs?: never;
 }
+/**
+ * The terminal bound a policy declares: a count, a duration (optionally with a
+ * count), or an explicit opt-in to neither. Exactly one arm applies, and there
+ * is no arm for "I forgot".
+ */
+type RetryBudget = CountBound | DurationBound | Unbounded;
+/**
+ * A retry policy is pure configuration — the knobs of the backoff curve plus
+ * the bound that ends the retrying. It carries no mutable state; `RetryState`
+ * does. One policy is shared across all the attempts of one logical operation
+ * (often a module-scope const).
+ *
+ * `RetryPolicy` is the COUNT-bounded shape, unchanged since the module's first
+ * release: every existing `{ baseMs, factor, capMs, maxAttempts, jitter }`
+ * literal still satisfies it, `policy.maxAttempts` is still a `number` (not
+ * `number | undefined`), and `shouldRetry(state, policy)` still takes no clock.
+ * Reach for {@link DurationRetryPolicy} when the bound should be temporal, or
+ * {@link AnyRetryPolicy} when writing code generic over the bound.
+ */
+type RetryPolicy = BackoffCurve & CountBound;
+/** A curve bounded by wall-clock outage duration (and optionally by count). */
+type DurationRetryPolicy = BackoffCurve & DurationBound;
+/** A curve with the explicit opt-in to unbounded retry. */
+type UnboundedRetryPolicy = BackoffCurve & Unbounded;
+/**
+ * Any well-formed policy. The parameter type for code that must work whatever
+ * bound the caller declared — `shouldRetry`'s implementation, wrappers, and
+ * consumers that take a policy from configuration.
+ */
+type AnyRetryPolicy = BackoffCurve & RetryBudget;
 /**
  * Sensible defaults: 100ms base, doubling, capped at 30s, up to 5 attempts,
  * full jitter (the herd-avoidance default). Tuned for network calls; override
@@ -128,7 +254,7 @@ declare const defaultRetryPolicy: RetryPolicy;
  * `baseMs`. `capMs` is also the floor of the clamp, so a misconfigured
  * `capMs < baseMs` still yields a delay within `[0, capMs]`.
  */
-declare function backoffDelay(attempt: number, policy: RetryPolicy, rng?: Rng): number;
+declare function backoffDelay(attempt: number, policy: BackoffCurve, rng?: Rng): number;
 /**
  * Per-operation retry state: how many attempts have failed so far, and the most
  * recent error. `lastError` is `unknown` because the failure can be anything a
@@ -141,21 +267,72 @@ interface RetryState {
     /** The error from the most recent failure, if any. Carried, never interpreted. */
     readonly lastError?: unknown;
 }
-/** The starting state: zero attempts, no error yet. */
+/**
+ * A retry state that also knows WHEN its failure streak began — the origin a
+ * duration bound is measured from. Minted by passing the observation instant to
+ * {@link recordFailure}; there is no other way to obtain one, so a streak with
+ * an outage budget but no origin is not a value that can be written down.
+ *
+ * The origin is the FIRST failure of the streak and is preserved across
+ * subsequent failures. A success resets the streak the way it always did — by
+ * returning to `initRetry()` — which drops the origin with it, so an operation
+ * that fails occasionally never accumulates outage and pays nothing for a wide
+ * `maxElapsedMs`; only an unbroken run of failures grows toward the bound.
+ */
+interface TimedRetryState extends RetryState {
+    /** When the streak's first failure was observed (caller's clock, epoch ms). */
+    readonly firstFailureAtMs: number;
+}
+/** The starting state: zero attempts, no error yet, no streak. */
 declare function initRetry(): RetryState;
 /**
  * Record a failed attempt. PURE — returns a *new* state with `attempt`
  * incremented and `lastError` set; the input `state` is never mutated.
+ *
+ * `atMs` is the instant the failure was OBSERVED, supplied by the caller (the
+ * `interpret` handler owns the clock; this module never reads one — invariant
+ * 2). Passing it starts the streak clock on the first failure and preserves the
+ * original origin on every failure after it, yielding a {@link TimedRetryState}
+ * that a duration-bounded policy can be evaluated against. Omit it and the
+ * count-bounded behaviour is bit-for-bit what it always was.
  */
+declare function recordFailure(state: TimedRetryState, error: unknown, atMs?: number): TimedRetryState;
+declare function recordFailure(state: RetryState, error: unknown, atMs: number): TimedRetryState;
 declare function recordFailure(state: RetryState, error: unknown): RetryState;
+/**
+ * How long the current failure streak has lasted, in milliseconds. PURE.
+ *
+ * The honest number for a give-up log — a count of attempts says nothing about
+ * how much patience it actually spent. Clamped at 0 so a caller's clock going
+ * backwards (NTP step, a rehydrated state whose origin is from a different
+ * host) reads as "no outage yet" rather than a negative duration.
+ */
+declare function retryElapsedMs(state: TimedRetryState, nowMs: number): number;
 /**
  * Whether another attempt is permitted under `policy`. PURE.
  *
- * `attempt` is the number of failures recorded so far (= the index of the next
- * attempt). We may retry while that index is below `maxAttempts`, i.e. attempts
- * `0 .. maxAttempts-1` are allowed and the `maxAttempts`-th is refused.
+ * Every bound the policy DECLARES must still permit the attempt; a bound it
+ * does not declare is not consulted. Concretely:
+ *
+ *   - `maxAttempts` — `attempt` is the number of failures recorded so far (= the
+ *     index of the next attempt); we may retry while that index is below
+ *     `maxAttempts`, i.e. attempts `0 .. maxAttempts-1` are allowed and the
+ *     `maxAttempts`-th is refused. Unchanged.
+ *   - `maxElapsedMs` — we may retry while `nowMs - firstFailureAtMs` is below
+ *     the budget, *however many attempts that takes*. A streak's first failure
+ *     measures a zero-length outage and is therefore always retried, unless the
+ *     budget is itself `0` (the "no patience" setting).
+ *   - `unbounded: true` — always permitted.
+ *
+ * The overloads are the wiring contract. A count-bounded or explicitly
+ * unbounded policy needs no clock, so the two-argument call every existing
+ * caller already writes keeps type-checking. A policy carrying `maxElapsedMs`
+ * matches only the second overload, which demands a {@link TimedRetryState} and
+ * a `nowMs` — so declaring an outage budget and then never feeding it a clock
+ * fails to compile instead of silently producing a bound that never fires.
  */
-declare function shouldRetry(state: RetryState, policy: RetryPolicy): boolean;
+declare function shouldRetry(state: RetryState, policy: BackoffCurve & (CountBound | Unbounded), nowMs?: number): boolean;
+declare function shouldRetry(state: TimedRetryState, policy: AnyRetryPolicy, nowMs: number): boolean;
 /**
  * The delay to wait before the next attempt, given the current state. PURE.
  *
@@ -163,6 +340,6 @@ declare function shouldRetry(state: RetryState, policy: RetryPolicy): boolean;
  * attempt index, so the delay grows with each recorded failure. `rng` is
  * injected for determinism, same contract as `backoffDelay`.
  */
-declare function nextDelayMs(state: RetryState, policy: RetryPolicy, rng?: Rng): number;
+declare function nextDelayMs(state: RetryState, policy: BackoffCurve, rng?: Rng): number;
 
-export { type Jitter, type RetryPolicy, type RetryState, type Rng, asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, shouldRetry };
+export { type AnyRetryPolicy, type BackoffCurve, type CountBound, type DurationBound, type DurationRetryPolicy, type Jitter, type RetryBudget, type RetryPolicy, type RetryState, type Rng, type TimedRetryState, type Unbounded, type UnboundedRetryPolicy, asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, retryElapsedMs, shouldRetry };

package/dist/retry-backoff/index.js

@@ -1,3 +1,3 @@
-export { asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, shouldRetry } from '../chunk-5VNWZADP.js';
+export { asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, retryElapsedMs, shouldRetry } from '../chunk-Q2UM7BXU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/retry-to-success/index.js

@@ -1,4 +1,4 @@
-import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-5VNWZADP.js';
+import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-Q2UM7BXU.js';
 
 // src/retry-to-success/index.ts
 var RetryExhaustedError = class extends Error {

package/dist/runtime-types-gsog27b6.d.ts

@@ -0,0 +1,337 @@
+import { P as Port, C as Cmd, S as Sub, M as Machine, T as Transitions, R as Reducer, I as InterpretDetached, b as PortEmitter } from './core-42kapW0n.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
+ * identity-typed constructors `defineMachine` / `asReducer`, and the pure tools
+ * `replay` (compose without running) and `tryInterpret` (Railway).
+ */
+
+declare const ReducerBrand: unique symbol;
+type Branded<T> = T & {
+    readonly [ReducerBrand]: true;
+};
+/**
+ * Compile-time exhaustiveness assertion for default branches of switches over
+ * discriminated unions narrowed by hand (Sub handlers, message-bridge
+ * dispatchers, port fanouts) — TS narrows the operand to `never` only if every
+ * variant is covered, so adding one produces a compile error at the `absurd(x)`
+ * site. 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 `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).
+ */
+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
+ * non-isolated runs. Production code MUST NOT call this.
+ *
+ * @internal test-only
+ */
+declare function __resetPortRegistry(): void;
+/**
+ * Which otherwise-unattributable runtime path produced an error. Every fanout is
+ * throw-isolated so one bad consumer never strands its siblings, and the
+ * isolated throw routes to the `OnError` sink rather than a bare `console.error`.
+ *
+ * - `"follow-up"` — a follow-up Msg an interpret handler returned rejected when
+ *   re-dispatched (the original dispatcher already resolved, so no caller).
+ * - `"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.
+ * - `"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.
+ * - `"sub-cleanup"` — a subscription's cleanup threw (reconcile-removal or
+ *   `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 the default sink, so it 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, at
+ * `run(machine, { supervision })`. 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,
+ * which MUST return a valid `S` synchronously (the reducer is synchronous, so
+ * recovery is too — no suspension across the single-writer slot).
+ */
+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 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 — `idle()` REJECTS rather than silently resolving,
+ * so a livelocking machine surfaces instead of masquerading as quiescent.
+ * Mechanizes invariant 6 at the runtime layer, the role `PortNameCollisionError`
+ * plays for invariant 7.
+ */
+declare class QuiescenceTimeoutError extends Error {
+    readonly iterations: number;
+    readonly name = "QuiescenceTimeoutError";
+    readonly _tag: "QuiescenceTimeoutError";
+    constructor(iterations: number);
+}
+/**
+ * Define a typed port. `name` is metadata (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`. Use ports for "data leaving
+ * the runtime selectively" (cursor announcements, DOM-mutation broadcasts,
+ * telemetry) that should NOT be folded into State. Strengthens invariant 7.
+ */
+declare function definePort<T>(name: string): Port<T>;
+interface Store<S> {
+    load(): Promise<unknown>;
+    save(state: S): Promise<void>;
+    migrate(raw: unknown): S | null;
+}
+interface Schema<S> {
+    safeParse(raw: unknown): {
+        success: true;
+        data: S;
+    } | {
+        success: false;
+    };
+}
+/**
+ * Build a `Store.migrate` from a schema (job 1) and an optional thin `upcast`
+ * (job 2). `upcast` maps a recognized-but-OLD raw shape forward into the shape
+ * the schema validates; it defaults to identity (no version migration yet).
+ *
+ * Never throws — a shape the schema rejects returns `null`, the substrate's
+ * fresh-boot path, per the `Store.migrate` contract. An `upcast` that itself
+ * throws on a corrupt blob is caught and collapses to `null` (same posture).
+ */
+declare function schemaMigrate<S>(schema: Schema<S>, upcast?: (raw: unknown) => unknown): (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 processed. Runs to
+     * QUIESCENCE by default: settles only after the dispatched Msg AND every
+     * transitive interpret follow-up has drained. Pass `{ settle: "once" }` (or
+     * call `dispatchOnce`) for the single-step case.
+     *
+     * Rejection ordering: the ONE dispatched transition's own failure surfaces
+     * first, here. If it succeeds but the follow-up chain never stabilizes, the
+     * quiescent drain rejects with `QuiescenceTimeoutError`. 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" })`. Prefer plain `dispatch` unless you will
+     * `await runtime.idle()` yourself; the un-awaited follow-up chain is the
+     * footgun the quiescent default removed.
+     */
+    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. Fires exactly once:
+     * immediately if boot already completed (so a late subscriber never misses
+     * it), otherwise on the boot fanout. Returns a cleanup (a no-op once fired).
+     */
+    onBoot(handler: (state: S) => void): () => void;
+    /**
+     * Subscribe to a SEMANTIC event of `type`. The handler receives exactly the
+     * `E` member whose `type` matches `K`, so a consumer never touches another
+     * event's shape and never references the machine's PRIVATE Msg names. Multiple
+     * handlers per type; fanout is synchronous and throw-isolated. Fires only when
+     * the machine's `events` projector (wired on `run`) emits that type.
+     */
+    on<K extends E["type"]>(type: K, handler: (event: Extract<E, {
+        type: K;
+    }>) => void): () => void;
+    /**
+     * Subscribe to a typed Port. Multiple listeners per port; fanout is synchronous
+     * and isolated. Ports are for "data leaving the runtime selectively" (see
+     * `definePort`) — distinct from `observe` (every transition) and State.
+     */
+    subscribePort<T>(port: Port<T>, listener: (value: T) => void): () => void;
+    /**
+     * Emit a value on a Port from OUTSIDE an interpret handler — same synchronous
+     * fanout as `ctx.emit`. The canonical use is `observe`-driven emission (one
+     * runtime publishing a state-derived signal another subscribes to via
+     * `subscribePort`) without spawning a "tell the outside world" Cmd per
+     * transition.
+     */
+    emitPort<T>(port: Port<T>, value: T): void;
+    /**
+     * Resolves to the booted `Runtime<S, M>` after boot completes (or rejects with
+     * the boot error). This is the ONLY way to obtain a `Runtime` — and a
+     * `Runtime` is the only handle whose `getState()` is total. Awaiting `ready` is
+     * 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 — the same settled promise, resolving to the same `Runtime`, comes
+     * back on every read. Expresses canon §2.3 (boot is a named, awaitable moment).
+     */
+    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.
+     */
+    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 transitive interpret follow-up has been processed, with no further step
+     * pending on the tail. Since plain `dispatch` already runs to quiescence, this
+     * is mainly for follow-ups left by a `dispatchOnce` single step, or a chain
+     * kicked off by a Sub / boot `init` cmds with no `dispatch` to await.
+     *
+     * Idempotent and re-entrant-safe. Tail rejections are NOT surfaced here (a
+     * failing dispatch surfaces on its OWN promise; follow-up rejections route to
+     * `onError`). The one rejection `idle()` produces is `QuiescenceTimeoutError`
+     * on hitting the iteration cap — so a livelock stays distinguishable from a
+     * genuine quiesce (invariant 6). A poll is still correct when waiting on an
+     * EXTERNAL event the runtime cannot enqueue itself.
+     */
+    idle(): Promise<void>;
+    /**
+     * The terminal State of the run, or `undefined` while in flight — "terminal"
+     * per the `terminal` predicate passed to `run()` (no predicate → never
+     * terminal → always `undefined`). The first-class result read: the run's
+     * product off the State the machine already owns, NOT scraped off the `observe`
+     * firehose by matching an internal Msg name. Total — never throws.
+     */
+    result(): S | undefined;
+    /**
+     * Resolves with the terminal State the first time the run reaches one (per the
+     * `terminal` predicate). If ALREADY terminal, resolves immediately; otherwise
+     * on the transition that first makes `terminal` hold. The awaitable companion
+     * to `result()`. With no predicate this never resolves. Idempotent and
+     * multi-caller safe.
+     */
+    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 replay<S, M 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[];
+    depSubs: {
+        index: number;
+        id: string;
+    }[];
+};
+declare function wrapDetached<C extends Cmd, M extends {
+    type: string;
+}, Allowed extends M, Ctx>(handler: InterpretDetached<C, Allowed, Ctx>): (cmd: C, ctx: Ctx & PortEmitter, dispatch?: (msg: M) => void) => Promise<void>;
+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 { type BootingRuntime as B, type CtxArg as C, type DispatchSettle as D, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, __resetPortRegistry as _, type Supervision as a, type Branded as b, absurd as c, SubIdCollisionError as d, type RuntimeErrorPhase as e, type RuntimeErrorContext as f, type SupervisionStrategy as g, definePort as h, type Schema as i, type RuntimeRef as j, defineMachine as k, asReducer as l, noop as n, replay as r, schemaMigrate as s, tryInterpret as t, wrapDetached as w };

package/dist/saga/index.d.ts

@@ -1,8 +1,9 @@
-import { C as Cmd } from '../core-BoB6t7dB.js';
+import { C as Cmd } from '../core-42kapW0n.js';
 import { QueueItem } from '../work-queue/index.js';
-import '../index.js';
+import '../runtime-types-gsog27b6.js';
 
 /**
+ * @packageDocumentation
  * @demlik/tea/saga — a forward-then-compensate transaction over an ordered list
  * of reversible steps.
  *

package/dist/saga/index.js

@@ -1,5 +1,5 @@
-import { queueAdapter } from '../chunk-HJO6VNQI.js';
-import '../chunk-TGG26XMK.js';
+import { queueAdapter } from '../chunk-MU6MCIAC.js';
+import '../chunk-FV3Z5MBE.js';
 
 // src/saga/index.ts
 function isCommitted(state) {