@demlik/tea 0.20.0 → 0.22.0

package/dist/{run-fiBe7pOG.d.ts → run-Cnw4qXj2.d.ts}

@@ -1,6 +1,7 @@
 import { Effect, Stream, Scope } from 'effect';
-import { P as Port, C as Cmd, E as ErrorsOf, o as OkOfCmd, p as DeclaredErrorsOf, S as Sub, q as BuiltinSubType, B as BuiltinSub, M as Machine } from './core-CtvAyPpH.js';
-import { c as DispatchSettle, C as CtxArg, S as Store, O as OnError, a as Supervision, T as TelemetrySink } from './runtime-types-DEluQgGO.js';
+import { P as Port, C as Cmd, E as ErrorsOf, p as OkOfCmd, q as DeclaredErrorsOf, c as Sub, r as BuiltinSubType, B as BuiltinSub, M as Machine } from './core-DNDAEhO2.js';
+import { d as DispatchSettle, C as CtxArg, S as StoreAndOnError, c as Supervision, T as TelemetrySink } from './runtime-types-CP-ykwgf.js';
+import { P as Postable } from './loop-DReKGV1X.js';
 import * as effect_Cause from 'effect/Cause';
 import * as effect_Types from 'effect/Types';
 
@@ -35,6 +36,19 @@ declare class StoreFailed extends StoreFailed_base<{
 }> {
     get message(): string;
 }
+declare const SubFailed_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "SubFailed";
+} & Readonly<A>;
+/**
+ * A Sub failed with an error it did not map to a Msg, and that stopped the run
+ * before it reached a terminal State. `cause` is what the Sub failed with, the
+ * value `onError` heard under `"sub"`. Only `done()` fails with it.
+ */
+declare class SubFailed extends SubFailed_base<{
+    readonly cause: unknown;
+}> {
+    get message(): string;
+}
 
 /**
  * The Effect engine's run handle (#308, ruling R4.1 of #325). Its members have
@@ -68,9 +82,12 @@ interface EffectBootingRuntime<S, M extends {
     }): Effect.Effect<void, Err | Stopped | StoreFailed>;
     /** `dispatch(msg, { settle: "once" })`: one transition, no follow-up drain. */
     dispatchOnce(msg: M): Effect.Effect<void, Err | Stopped | StoreFailed>;
-    /** A zero-arg change notifier, fired after each applied transition. */
+    /**
+     * A zero-arg change notifier, fired for each applied transition after its
+     * save and before its first Cmd's handler starts.
+     */
     subscribe(listener: () => void): () => void;
-    /** A `(msg, state)` hook, fired after each applied transition. */
+    /** A `(msg, state)` hook, fired after each applied transition's Cmds. */
     observe(observer: (msg: M, state: S) => void): () => void;
     /** Fires once with the initial State — at once if boot already ran. */
     onBoot(handler: (state: S) => void): () => void;
@@ -90,15 +107,20 @@ interface EffectBootingRuntime<S, M extends {
      */
     readonly ready: Effect.Effect<EffectRuntime<S, M, E, Err>, Err | StoreFailed>;
     /**
-     * Stop the run: drain in-flight work, stop its Subs, flush the final State.
-     * Closing the run's Scope stops the run the same way, and `stop()` leaves
-     * that Scope open. So for a child under `spawn` the two differ: `stop()`
-     * does not take the child out of the host's table or tell the parent. Stop
-     * such a child with the `stop` helper.
+     * Stop the run: drain in-flight work, up to `disposeTimeoutMs`, stop its
+     * Subs, flush the final State. `stop()` interrupts every handler still in
+     * flight, so the limit is reached only by a handler that cannot be
+     * interrupted. Closing the run's Scope stops the run the same way, and
+     * `stop()` leaves that Scope open. So for a child under `spawn` the two
+     * differ: `stop()` does not take the child out of the host's table or tell
+     * the parent. Stop such a child with the `stop` helper.
      */
     stop(): Effect.Effect<void>;
 }
-/** The Effect engine's booted handle — what `ready` succeeds with. */
+/**
+ * The Effect engine's booted handle. `ready` on a real run succeeds with an
+ * {@link EffectRun}, which is one of these and carries what `tell` asks for.
+ */
 interface EffectRuntime<S, M extends {
     type: string;
 }, E extends {
@@ -109,10 +131,53 @@ interface EffectRuntime<S, M extends {
     readonly ready: Effect.Effect<EffectRuntime<S, M, E, Err>, Err | StoreFailed>;
     /** Succeeds once every dispatched Msg and its follow-ups are processed. */
     idle(): Effect.Effect<void>;
-    /** The terminal State, or `undefined` while the run is in flight. */
+    /**
+     * The saved terminal State, or `undefined` while its save is pending or failed.
+     * Without a store, answers as soon as State is set. A run a failure closed
+     * reads `undefined` here; `done()` says why.
+     */
     result(): S | undefined;
-    /** Succeeds with the terminal State the first time the run reaches one. */
-    done(): Effect.Effect<S>;
+    /**
+     * Succeeds with the terminal State only once it is saved. When a failure
+     * closes the run short of a terminal State, it fails with that failure, for
+     * waiting and later callers: a failed terminal save with `StoreFailed`
+     * (`operation: "save"`), a Sub failure with `SubFailed`, and a reducer throw
+     * under the `stop` strategy with a defect, the thrown value itself. The defect
+     * is outside the error channel, so `Effect.catchTags` does not see it and
+     * `Effect.catchDefect` or the fiber's `Exit` does. The Msgs already in line
+     * fold first, so one of them reaching a terminal State makes that State the
+     * answer. A terminal State already saved keeps its answer whatever fails
+     * after it. A `stop()` with no failure leaves this waiting. Without a store,
+     * answers as soon as State is set.
+     */
+    done(): Effect.Effect<S, StoreFailed | SubFailed>;
+}
+/**
+ * The handle `run` yields: an {@link EffectBootingRuntime} whose `ready` succeeds
+ * with an {@link EffectRun}. It does not compile as `tell`'s argument: wait for
+ * `ready`.
+ */
+interface EffectBootingRun<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never, Err = never> extends EffectBootingRuntime<S, M, E, Err> {
+    readonly ready: Effect.Effect<EffectRun<S, M, E, Err>, Err | StoreFailed>;
+}
+/**
+ * What an {@link EffectBootingRun}'s `ready` succeeds with: a booted
+ * {@link EffectRuntime} that also carries the run's line, which is what `tell`
+ * asks for. A spread keeps the line. An object built by hand cannot have one,
+ * because tea does not export its key, so an {@link EffectRuntime} that is not one
+ * of these does not compile as `tell`'s argument. It fits anywhere an
+ * `EffectRuntime` is asked for.
+ */
+interface EffectRun<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never, Err = never> extends EffectRuntime<S, M, E, Err>, Postable<S, M> {
+    readonly ready: Effect.Effect<EffectRun<S, M, E, Err>, Err | StoreFailed>;
 }
 
 /**
@@ -164,7 +229,7 @@ type EffectInterpret<M extends {
  * A Sub maps the errors it expects into Msgs itself, the way an Elm `Sub msg`
  * carries no error type: `Stream.catchTag("Closed", () => Stream.make({ type:
  * "disconnected" }))`. A stream that still fails reaches the error sink under
- * `"sub"` and stops the run: the run's Scope closes with that failure (#309).
+ * `"sub"` and stops the run (#309), and `done()` fails with `SubFailed`.
  */
 type EffectRunner<M extends {
     type: string;
@@ -227,9 +292,7 @@ type EffectRunOptions<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, E extends {
     type: string;
-}, I, B> = CtxArg<Ctx> & InterpretOption<C, I> & SubscribeOption<U, B> & {
-    readonly store?: Store<S>;
-    readonly onError?: OnError;
+}, I, B> = CtxArg<Ctx> & InterpretOption<C, I> & SubscribeOption<U, B> & StoreAndOnError<S> & {
     /** Stamps `at` on minted Msgs and telemetry. Defaults to `Date.now`. */
     readonly clock?: () => number;
     /** Projects each applied transition to the public events `on` serves. */
@@ -240,7 +303,18 @@ type EffectRunOptions<S, M extends {
     readonly terminal?: (state: S) => boolean;
     /** A fire-and-forget sink for every applied transition. */
     readonly telemetry?: TelemetrySink;
-    /** How long `stop()` waits for async teardown. Defaults to 5_000ms. */
+    /**
+     * How long `stop()` waits for the queue, and then for async teardown,
+     * before giving up on each. Defaults to 5_000ms. `stop()` interrupts every
+     * handler here, so the first wait ends early unless a handler cannot be
+     * interrupted.
+     *
+     * A store call is not interrupted. tea starts none after `stop()` has
+     * returned, but one already under way when `stop()` gave up can finish
+     * after it. On a plain store that late save can overwrite what a newer
+     * run saved; a fenced store refuses it. So a host that starts a new run on
+     * the same store after a `stop()` that gave up needs a fenced store.
+     */
     readonly disposeTimeoutMs?: number;
 };
 /**
@@ -256,11 +330,19 @@ type EffectRunOptions<S, M extends {
  * dispatch after stop fails with `Stopped`. The handle's `stop()` does the
  * same.
  *
- * A Sub whose Stream fails with an error it did not map to a Msg stops the
- * run the other way round: the engine closes that Scope with the failure.
+ * A Sub whose Stream fails with an error it did not map to a Msg stops this run
+ * alone. The run forks its own child of that scope and closes only the child,
+ * so the rest of the scope stays open, and `done()` fails with `SubFailed`. A
+ * handler or runner that reads `Scope.Scope` gets that child, so what it acquires
+ * is released with the run. With no `onError`, the default sink still rethrows
+ * the failure and ends the process. A reducer throw under the default `stop`
+ * strategy closes that same child, so the run stops and `done()` fails with
+ * what was thrown, as a defect (ADR 0033).
  *
  * A fenced store is fenced here exactly as on the Promise engine: the check is
- * one of the built-ins both engines run.
+ * one of the built-ins both engines run. A run on a store that is fenced at
+ * runtime with no `onError` dies at start, before anything is loaded, even when
+ * the store is typed plain `Store<S>` (ADR 0031).
  *
  * ```ts
  * const program = Effect.gen(function* () {
@@ -284,6 +366,6 @@ declare function run<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, I extends EffectInterpret<M, C> = EffectInterpret<M, C, never>, B extends EffectSubscribe<M, U> = EffectSubscribe<M, U, never>, E extends {
     type: string;
-} = never>(machine: Machine<S, M, C, U, Ctx>, opts: EffectRunOptions<S, M, C, U, Ctx, E, I, B>): Effect.Effect<EffectBootingRuntime<S, M, E, CellErrors<C, I>>, never, Scope.Scope | InterpretServices<I> | SubscribeServices<B>>;
+} = never>(machine: Machine<S, M, C, U, Ctx>, opts: EffectRunOptions<S, M, C, U, Ctx, E, I, B>): Effect.Effect<EffectBootingRun<S, M, E, CellErrors<C, I>>, never, Scope.Scope | InterpretServices<I> | SubscribeServices<B>>;
 
-export { type CellErrors as C, type EffectRuntime as E, type InterpretServices as I, StoreFailed as S, type EffectBootingRuntime as a, type EffectInterpret as b, type EffectInterpretCell as c, type EffectRunOptions as d, type EffectRunner as e, type EffectSubscribe as f, Stopped as g, type SubscribeServices as h, type SubscribeOption as i, run as r };
+export { type CellErrors as C, type EffectRun as E, type InterpretServices as I, Stopped as S, type EffectBootingRun as a, type EffectBootingRuntime as b, type EffectInterpret as c, type EffectInterpretCell as d, type EffectRunOptions as e, type EffectRunner as f, type EffectRuntime as g, type EffectSubscribe as h, StoreFailed as i, SubFailed as j, type SubscribeServices as k, type SubscribeOption as l, run as r };

package/dist/{runtime-types-DEluQgGO.d.ts → runtime-types-CP-ykwgf.d.ts}

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-CtvAyPpH.js';
+import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-DNDAEhO2.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
@@ -98,12 +98,15 @@ declare function __resetPortRegistry(): void;
  *   run stops — on the Effect engine by closing its Scope with the failure. A
  *   Sub that expects an error maps it to a Msg itself; there is no hook for it
  *   here.
- * - `"discard"` — work lost to a teardown the host asked for. Two witnesses,
- *   both carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
- *   handlers were still awaiting (`RuntimeDiscardedError`), and a Msg that
- *   arrived DURING `stop()`'s drain and so could not be delivered
- *   (`DispatchDiscardedError`), and teardown work that did not settle inside
- *   `disposeTimeoutMs` (`DisposeTimeoutNotice`). The one phase that is a
+ * - `"discard"` — work lost to a teardown the host asked for. Four witnesses,
+ *   each carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
+ *   handlers were still awaiting (`RuntimeDiscardedError`), a Msg that
+ *   arrived DURING `stop()`'s drain, or from a handler `stop()` gave up on, and
+ *   so could not be delivered (`DispatchDiscardedError`), a drain that did not
+ *   finish inside `disposeTimeoutMs`, which also counts the Msgs that were still
+ *   queued (`DrainTimeoutNotice`), and teardown work that did not settle inside
+ *   `disposeTimeoutMs`
+ *   (`DisposeTimeoutNotice`). The one phase that is a
  *   LIFECYCLE report rather than a failure: legal, merely lossy.
  * - `"identity-drop"` — the `Identity` filter dropped a message addressed to a
  *   different instance (`IdentityDropNotice`). Its own phase rather than
@@ -144,6 +147,14 @@ interface RuntimeErrorContext {
  * `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.
+ *
+ * Optional, except beside a fenced store (see {@link StoreAndOnError}): there it
+ * does not compile without one, and a run whose store is fenced at runtime is
+ * refused at start without one, whatever its type says. With no
+ * sink a `RuntimeDiscardNotice` is warned, and every other failure is rethrown on
+ * a fresh macrotask, which ends a Node process and every run in it. That includes
+ * a failing Sub (`"sub"`). A host running several machines in one process passes
+ * a sink that decides what one run's failure means for the rest.
  */
 type OnError = (error: unknown, context: RuntimeErrorContext) => void;
 /** The three declared reducer-throw supervision strategies. */
@@ -159,6 +170,14 @@ type SupervisionStrategy = "stop" | "escalate" | "restart";
 type Supervision<S, M extends {
     type: string;
 }> = "stop" | "escalate" | {
+    /**
+     * The default. A reducer throw stops the run by itself, the same stop a
+     * Sub failure starts: the Msgs already in line fold, then the Subs close,
+     * the final save runs and, on the Effect engine, the run's own Scope
+     * closes, so a run `spawn` started leaves the host's table and its
+     * `notify` runs. `done()` fails with the throw. A later `stop()` from the
+     * host does nothing more.
+     */
     readonly strategy: "stop";
 } | {
     readonly strategy: "escalate";
@@ -173,6 +192,17 @@ type Supervision<S, M extends {
      */
     readonly rehydrate: (state: S, msg: M, error: unknown) => S;
 };
+/**
+ * What `done()` rejects with once a Sub's failure the Sub did not map to a Msg
+ * has stopped the run, which can then never reach a terminal State. `cause` is
+ * what the Sub failed with, the same value `onError` heard under `"sub"`.
+ */
+declare class SubFailedError extends Error {
+    readonly cause: unknown;
+    readonly name = "SubFailedError";
+    readonly _tag: "SubFailedError";
+    constructor(cause: unknown);
+}
 /**
  * Raised by `idle()` when the quiescence wait hits its iteration cap without the
  * dispatch tail stabilizing — `idle()` REJECTS rather than silently resolving,
@@ -237,7 +267,8 @@ declare abstract class RuntimeDiscardNotice extends Error {
 /**
  * Reported to the `OnError` sink under `phase: "discard"` when `stop()` is
  * called while `interpret` handlers are still awaiting. The host is dropping
- * its only handle on that work: `stop()` drains the tail, but the listeners,
+ * its only handle on that work: `stop()` drains the tail, up to
+ * `disposeTimeoutMs`, but the listeners,
  * observers and event handlers that would have consumed the resulting
  * transitions are gone, so the Cmds' results reach nobody.
  *
@@ -294,12 +325,57 @@ declare class DisposeTimeoutNotice extends RuntimeDiscardNotice {
     readonly _tag: "DisposeTimeoutNotice";
     constructor(pendingDisposals: number, timeoutMs: number);
 }
+/**
+ * Reported to the `OnError` sink under `phase: "discard"` when `stop()`'s wait
+ * for the queue hits `disposeTimeoutMs` (ADR 0025): a Cmd handler, a save or
+ * detached work had not returned.
+ *
+ * `stop()` resolves by contract, so it gives up on that work instead of waiting
+ * for it without limit. It then stops the Subs and runs the final save as it
+ * always does. The work it gave up on is not recalled — a Promise cannot be
+ * cancelled — so a handler may still be running after `stop()` has returned.
+ * Whatever it returns later is dropped, and so are the Msgs queued behind it.
+ * The rest of its step's Cmds are skipped: no handler starts for them, and they
+ * get no notice of their own. None of it is saved.
+ *
+ * `droppedMsgs` is how a host learns what it lost. It counts the Msgs queued
+ * behind the stuck work when `stop()` gave up, per Msg type: Msgs handed to
+ * `dispatch` or `tell`, and those a handler or a Sub sent. It carries types and
+ * counts only, never a payload, so a sink can log it. It is read once and does
+ * not change. A Msg it counts is not reported again: if the handler returns
+ * late, a `dispatch` caller's promise rejects with a `DispatchDiscardedError`,
+ * and a Msg with no caller reaches the sink no second time. If the handler
+ * never returns, those promises never settle, and this count is the only word.
+ *
+ * tea starts no store call after `stop()` has returned. A store call already
+ * under way when `stop()` gave up is not cancelled and can finish afterwards;
+ * on a plain store that late save can overwrite what a newer run saved, and a
+ * fenced store refuses it.
+ *
+ * `cmdTypes` names the Cmd of each handler call still awaiting, one entry per
+ * call. `pendingCmds` counts those plus any detached work, the same count
+ * `RuntimeDiscardedError` carries.
+ */
+declare class DrainTimeoutNotice extends RuntimeDiscardNotice {
+    readonly cmdTypes: readonly string[];
+    readonly pendingCmds: number;
+    readonly timeoutMs: number;
+    readonly droppedMsgs: Readonly<Record<string, number>>;
+    readonly name = "DrainTimeoutNotice";
+    readonly _tag: "DrainTimeoutNotice";
+    constructor(cmdTypes: readonly string[], pendingCmds: number, timeoutMs: number, droppedMsgs?: Readonly<Record<string, number>>);
+}
 /**
  * The rejection of a dispatch that arrived DURING `stop()`'s drain — an in-flight
  * interpret handler's follow-up Msg, a detached handler's terminal Msg, or a Sub
  * that is still live because subs are torn down only after the drain. The stop
  * barrier is absolute (the Msg is refused, never folded), so this names the loss.
  *
+ * It is also the rejection of the work `stop()` gave up on (see
+ * `DrainTimeoutNotice`): a Msg a stuck handler produces after `stop()` has
+ * returned, and a Msg that was accepted before `stop()` and was still queued
+ * behind that handler.
+ *
  * It is the SECOND witness of `RuntimeDiscardedError`'s fact, and it is why the
  * drain window is a distinct runtime state rather than a plain `stopped` flag:
  * a Msg refused inside the window was discarded BY the teardown, while the same
@@ -431,6 +507,38 @@ interface DeletableStore<S> extends Store<S> {
 }
 /** Narrow a `Store<S>` to a {@link FencedStore} — what `run` uses to decide. */
 declare function isFencedStore<S>(store: Store<S>): store is FencedStore<S>;
+/**
+ * A `Store<S>` whose type says it is not fenced. A plain `Store<S>` fits it and
+ * a {@link FencedStore} does not. It is what lets {@link StoreAndOnError} tell the
+ * two apart, because a `FencedStore` is otherwise also a `Store`.
+ */
+type UnfencedStore<S> = Store<S> & {
+    readonly fenced?: never;
+};
+/**
+ * The `store` and `onError` options of a run: a fenced store needs an `onError`,
+ * and the mistake does not compile (ADR 0031).
+ *
+ * Losing a fence is routine for a host that moves runs between processes, and
+ * with no `onError` the default sink rethrows the conflict and ends the process,
+ * along with every other run in it. A conflict can reach the sink at any save
+ * with no caller to reject at: `"stop-save"` from `stop()`, `"follow-up"` from a
+ * Msg a Sub or a Cmd sent. So the sink is required at the type, not left to be
+ * remembered.
+ *
+ * It reads a store's declared type. A fenced store first assigned to a variable
+ * typed plain `Store<S>` has given that type up, so it compiles with no
+ * `onError`. Both engines then refuse it at start, before anything is loaded:
+ * the Promise engine's `run` throws, and the Effect engine's dies. A JavaScript
+ * caller is refused the same way.
+ */
+type StoreAndOnError<S> = {
+    readonly store?: UnfencedStore<S>;
+    readonly onError?: OnError;
+} | {
+    readonly store: Store<S>;
+    readonly onError: OnError;
+};
 /**
  * Thrown when a fenced save finds a version other than the one it expected —
  * another live writer has this run.
@@ -518,9 +626,12 @@ interface RunHandle<S, M extends {
 } = never> {
     /** Put a Msg in the inbox; resolves once the engine has processed it. */
     dispatch(msg: M): Promise<void>;
-    /** A zero-arg change notifier, fired after each applied transition. */
+    /**
+     * A zero-arg change notifier, fired for each applied transition after its
+     * save and before its first Cmd's handler starts.
+     */
     subscribe(listener: () => void): () => void;
-    /** A `(msg, state)` hook, fired after each applied transition. */
+    /** A `(msg, state)` hook, fired after each applied transition's Cmds. */
     observe(observer: (msg: M, state: S) => void): () => void;
     /** Fires once with the initial State — at once if boot already ran. */
     onBoot(handler: (state: S) => void): () => void;
@@ -545,15 +656,15 @@ interface BootedRunHandle<S, M extends {
 }
 /**
  * The options every engine's `run` accepts: the `ctx`, the handlers the
- * machine runs under, an optional `store`, and the `events` projector that
- * feeds `on`. An engine may take more; a host adapter hands only these.
+ * machine runs under, an optional `store` with the `onError` a fenced one needs,
+ * and the `events` projector that feeds `on`. An engine may take more; a host
+ * adapter hands only these.
  */
 type RunOptions<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, E extends {
     type: string;
-} = never> = CtxArg<Ctx> & RunHandlers<M, C, U, Ctx> & {
-    readonly store?: Store<S>;
+} = never> = CtxArg<Ctx> & RunHandlers<M, C, U, Ctx> & StoreAndOnError<S> & {
     readonly events?: (msg: M, state: S) => readonly E[];
 };
 /**
@@ -594,12 +705,16 @@ interface BootingRuntime<S, M extends {
     }): Promise<void>;
     dispatchOnce(msg: M): Promise<void>;
     /**
-     * Register a zero-arg change notifier, fired for every applied transition
-     * with the fold's State already committed — `getState()` inside the listener
-     * reads it, not the State before. A `dispatch` issued from the listener is
-     * SCHEDULED onto the serial tail behind the fold that fired it, never folded
-     * re-entrantly and never discarded, so it needs no `setTimeout(fn, 0)`
-     * deferral; two listeners issuing in order fold in that order.
+     * Register a zero-arg change notifier, fired once for every applied
+     * transition, after its save and before its first Cmd's handler starts, so a
+     * view shows the State while that State's Cmds run. `getState()` inside the
+     * listener reads the new State, not the State before. A failed save fires
+     * nothing. The listener does not mean the Cmds are done: `observe`, `on` and
+     * `done()` hear after them. A `dispatch` issued from the listener is SCHEDULED
+     * onto the serial tail behind the fold that fired it, never folded re-entrantly
+     * and never discarded, so it needs no `setTimeout(fn, 0)` deferral; it folds
+     * ahead of what that fold's Cmds return, and two listeners issuing in order
+     * fold in that order.
      */
     subscribe(listener: () => void): () => void;
     /**
@@ -695,19 +810,30 @@ interface Runtime<S, M extends {
      */
     idle(): Promise<void>;
     /**
-     * The terminal State of the run, or `undefined` while in flight — "terminal"
+     * The saved 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.
+     * firehose by matching an internal Msg name. With a store, returns `undefined`
+     * until the current State's save succeeds, including after a failed save.
+     * Without a store, answers as soon as State is set. Total — never throws, so a
+     * run a failure closed reads `undefined` here; `done()` says why.
      */
     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.
+     * Resolves with the terminal State only once it is saved (per the `terminal`
+     * predicate). If ALREADY saved and terminal, resolves immediately; otherwise
+     * on that terminal commit. Rejects with the save failure if a terminal State
+     * cannot be saved, for both waiting and later callers. When a failure closes
+     * the run short of a terminal State, it rejects for both waiting and later
+     * callers too: with `SubFailedError` for a Sub failure the Sub did not map to
+     * a Msg, and with what was thrown for a reducer throw under the `stop`
+     * strategy. It answers that only after the Msgs already in line have folded,
+     * because one of them can still reach a terminal State, and then the State is
+     * the answer. A `stop()` with no failure leaves it pending. Without a store,
+     * answers as soon as State is set. The awaitable companion to `result()`. With
+     * no predicate this resolves never, and rejects only on those failures.
+     * Idempotent and multi-caller safe.
      */
     done(): Promise<S>;
 }
@@ -794,7 +920,9 @@ type CtxArg<Ctx> = [Record<never, never>] extends [Ctx] ? {
  * Cmds emitted, and the Subs that would be running.
  *
  * It composes `init(loaded ?? null, ctx)` and then `update(state, msg)` for each
- * Msg. No Cmd handler is called, no `Store` is touched and no Sub is started.
+ * Msg. Restored init may change State and emit Cmds; those Cmds are collected
+ * alongside update Cmds. No handler, Store or Sub runner is called.
+ * Recorded traces instead use `replayTrace` to fold their captured post-init State.
  *
  * `subs` is each `machine.subs` entry that is on at the final state, as its
  * runner would see it: `{ id, type, deps }`, the id derived exactly as the
@@ -884,4 +1012,4 @@ declare function tryFoldMsgs<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 { defineMachine as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, definePort as G, isFencedStore as H, IdentityDropNotice as I, noop as J, refuse as K, replay as L, type Migrated as M, schemaMigrate as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, tryApplyCell as U, tryFoldMsgs as V, tryInterpret as W, wrapDetached as X, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type DispatchSettle as c, type RunHandle as d, type Branded as e, DispatchDiscardedError as f, DisposeTimeoutNotice as g, DriveFailedError as h, DriveStalledError as i, type FencedRead as j, type FoldRefusal as k, type MachineTypes as l, Refusal as m, type RunOptions as n, RuntimeDiscardNotice as o, RuntimeDiscardedError as p, type RuntimeErrorContext as q, type RuntimeErrorPhase as r, type RuntimeRef as s, type Schema as t, StoreConflictError as u, StoreRefusedError as v, type SupervisionStrategy as w, type TelemetryEvent as x, absurd as y, asReducer as z };
+export { tryInterpret as $, type TelemetryEvent as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, absurd as G, asReducer as H, IdentityDropNotice as I, defineMachine as J, definePort as K, isFencedStore as L, type Migrated as M, noop as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type StoreAndOnError as S, type TelemetrySink as T, type UnfencedStore as U, refuse as V, replay as W, schemaMigrate as X, tryApplyCell as Y, tryFoldMsgs as Z, __resetPortRegistry as _, type BootedRunHandle as a, wrapDetached as a0, type Store as b, type Supervision as c, type DispatchSettle as d, type RunHandle as e, type Branded as f, DispatchDiscardedError as g, DisposeTimeoutNotice as h, DrainTimeoutNotice as i, DriveFailedError as j, DriveStalledError as k, type FencedRead as l, type FoldRefusal as m, type MachineTypes as n, Refusal as o, type RunOptions as p, RuntimeDiscardNotice as q, RuntimeDiscardedError as r, type RuntimeErrorContext as s, type RuntimeErrorPhase as t, type RuntimeRef as u, type Schema as v, StoreConflictError as w, StoreRefusedError as x, SubFailedError as y, type SupervisionStrategy as z };