@demlik/tea 0.21.0 → 0.22.0

package/dist/{chunk-EB5OMOXX.js → chunk-7K7SEYCH.js}

@@ -1,15 +1,10 @@
-import { startLoop, builtinExtensions, liveWork } from './chunk-VM7PMFV5.js';
-import { subEntriesOf, applyCell, DriveFailedError, DriveStalledError } from './chunk-GAVLND5C.js';
-
-// src/promise/builtin-runners.ts
-function timer(sub, _ctx, dispatch) {
-  const handle = setTimeout(() => dispatch(sub.deps.msg), sub.deps.ms);
-  return () => clearTimeout(handle);
-}
-var builtinRunners = { timer };
+import { builtinRunners } from './chunk-GFGOQIEC.js';
+import { refuseFencedRunWithoutSink, startLoop, builtinExtensions, tellRun, liveWork } from './chunk-2A5XTKQQ.js';
+import { subEntriesOf, applyCell, DriveFailedError, DriveStalledError } from './chunk-A3QPMX5M.js';
 
 // src/promise/run.ts
 function run(machine, opts) {
+  refuseFencedRunWithoutSink(opts.store, opts.onError);
   const interpretMap = opts.interpret ?? {};
   const subscribeTable = opts.subscribe;
   const builtins = builtinRunners;
@@ -32,9 +27,10 @@ function run(machine, opts) {
     disposeTimeoutMs: opts.disposeTimeoutMs ?? 5e3,
     idleCap: opts.__idleCap ?? 1e5,
     extensions: builtinExtensions(machine, opts),
-    // Deferred: a runner that throws during a storeless boot fails before
-    // `startLoop` has returned the handle.
-    stopOnSubFailure: () => {
+    // A Sub failure and a halting reducer throw stop the run the same way
+    // (ADR 0033). Deferred: a runner that throws during a storeless boot fails
+    // before `startLoop` has returned the handle.
+    stopOnFailure: () => {
       queueMicrotask(() => void handle.stop());
     }
   });
@@ -103,6 +99,11 @@ async function driveToDone(handle, start, isTerminal, opts = {}) {
   }
 }
 
-export { driveToDone, run };
-//# sourceMappingURL=chunk-EB5OMOXX.js.map
-//# sourceMappingURL=chunk-EB5OMOXX.js.map
+// src/promise/tell.ts
+function tell(machine, runtime, msg) {
+  return tellRun(machine, runtime, msg);
+}
+
+export { driveToDone, run, tell };
+//# sourceMappingURL=chunk-7K7SEYCH.js.map
+//# sourceMappingURL=chunk-7K7SEYCH.js.map

package/dist/chunk-7K7SEYCH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/promise/run.ts","../src/promise/tell.ts"],"names":[],"mappings":"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","file":"chunk-7K7SEYCH.js","sourcesContent":["/**\n * @demlik/tea runtime — `run`: boot a machine and drive its serial dispatch loop\n * on Promises; `driveToDone`: run one to its terminal State.\n *\n * `run` is assembly. The loop itself is `src/internal/engine/loop.ts` — a small\n * core with no special case for any built-in, shared with the Effect engine —\n * and every built-in is an extension of it (`src/internal/engine/builtins.ts`),\n * built from `run`'s options in the order both engines share.\n */\n\nimport { builtinRunners } from \"../internal/engine/builtin-runners\";\nimport {\n  builtinExtensions,\n  refuseFencedRunWithoutSink,\n} from \"../internal/engine/builtins\";\nimport {\n  type LiveWorkProbe,\n  type LoopHandler,\n  type LoopRunner,\n  liveWork,\n  type Postable,\n  startLoop,\n} from \"../internal/engine/loop\";\nimport type {\n  Dispose,\n  Interpret,\n  Machine,\n  RunHandlers,\n  Sub,\n} from \"../pure/core\";\nimport { applyCell, type Cmd, subEntriesOf } from \"../pure/core\";\nimport type {\n  BootingRuntime,\n  CtxArg,\n  Runtime,\n  StoreAndOnError,\n  Supervision,\n  TelemetrySink,\n} from \"../runtime-types\";\nimport { DriveFailedError, DriveStalledError } from \"../runtime-types\";\n\n// `ctx` is a plain object (ADR 0020): tea does no dependency injection, so\n// a handler's services are whatever the host put on it. The Cmd handlers\n// arrive here, beside the machine and never on it (#251 R1.1). `NoInfer`\n// keeps them a check against the machine's `M` / `C` rather than a second\n// inference site that could widen either.\n//\n// It is a named alias because the reference is generated from it: written inline\n// on `run`, the union in `StoreAndOnError` makes typedoc give up on the source\n// and hand back the compiler's printed type, with no comments and cut off.\n/** The options of the Promise engine's `run`. */\nexport type PromiseRunOptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n  E extends { type: string },\n> = CtxArg<Ctx> &\n  NoInfer<RunHandlers<M, C, U, Ctx>> &\n  StoreAndOnError<S> & {\n    /**\n     * The clock that stamps `at` on a `Cmd.define`d effect's settled Msg at\n     * the interpret edge, and on each `telemetry` event. Defaults to\n     * `Date.now`. Inject a fixed one for a deterministic run; a `replay` log\n     * carries its own `at`s and never reads this.\n     */\n    clock?: () => number;\n    /**\n     * The SEMANTIC event projector. Maps one APPLIED transition `(msg, state)`\n     * to zero-or-more public events of `E`; `[]` skips the transition. Maps the\n     * machine's PRIVATE Msg vocabulary to NAMED events — the private names never\n     * reach `on`'s `E` surface. Omit → `E = never` and `on` is uncallable. PURE.\n     */\n    events?: (msg: M, state: S) => readonly E[];\n    /**\n     * Declared policy for a reducer (`update`) throw. Always surfaced via\n     * `onError` (`phase: \"reduce\"`); the strategy decides what the runtime does\n     * next. Defaults to `\"stop\"`. See `Supervision`.\n     */\n    supervision?: Supervision<S, M>;\n    /**\n     * The run-terminality predicate — makes the run's outcome first-class. Fed to\n     * `Runtime.result()` and `Runtime.done()`. PURE. Omit → never terminal.\n     *\n     * `done()` resolves with a saved terminal State. When a failure closes the\n     * run short of one, it rejects with that failure, for waiting and later\n     * callers: the save's own error, a `SubFailedError`, or what a reducer threw\n     * under the `stop` strategy. A `stop()` with no failure leaves it pending.\n     */\n    terminal?: (state: S) => boolean;\n    /**\n     * A sink handed `{ seq, msgType, at }` for every applied transition —\n     * the observe-only telemetry `withTelemetry` used to add by wrapping the\n     * machine (#268). Fire-and-forget; see {@link TelemetrySink}.\n     */\n    telemetry?: TelemetrySink;\n    /**\n     * How long `stop()` waits for work it cannot interrupt before giving up\n     * on it. Defaults to 5_000ms. It bounds two waits, one after the other:\n     * the queue, where a Cmd handler may still be running, and then the\n     * teardown work that returned a Promise (an async `release` in\n     * `defineManagedResource`, an async Sub cleanup).\n     *\n     * `stop()` awaits those disposals so a host doing\n     * `await runtime.stop(); env.evict()` cannot drop the isolate mid-release —\n     * the leak the managed-resource battery exists to prevent, relocated to\n     * shutdown. The bound is what keeps a handler that never returns, or a\n     * release that never settles, from hanging the host: on expiry `stop()`\n     * reports a `DrainTimeoutNotice` or a `DisposeTimeoutNotice` (warn-only,\n     * like every `RuntimeDiscardNotice`) and resolves anyway, because `stop()`\n     * resolving is a contract (ADR 0025). The Subs are still stopped and the\n     * final save still runs. A handler `stop()` gave up on keeps running;\n     * what it returns later is dropped.\n     *\n     * tea starts no store call after `stop()` has returned. A store call\n     * already under way when `stop()` gave up is not cancelled and can\n     * finish after `stop()` has returned. On a plain store that late save\n     * can overwrite what a newer run saved; a fenced store refuses it with\n     * `StoreConflictError`. So a host that starts a new run on the same\n     * store after a `stop()` that gave up needs a fenced store. A run\n     * stopped while its `store.load()` was pending saves nothing when the\n     * load returns: `ready` resolves with the loaded State, unsaved.\n     */\n    disposeTimeoutMs?: number;\n    /**\n     * Iteration cap for `idle()`'s quiescence wait. Defaults to 100_000. Test\n     * seam only. Production code must not set it.\n     *\n     * @internal test-only\n     */\n    __idleCap?: number;\n  };\n\n/**\n * The handle `run` returns: a {@link BootingRuntime} whose `ready` resolves to a\n * {@link Run}. It does not compile as `tell`'s argument: wait for `ready`.\n */\nexport interface BootingRun<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n> extends BootingRuntime<S, M, E> {\n  ready: Promise<Run<S, M, E>>;\n}\n\n/**\n * What a {@link BootingRun}'s `ready` resolves to: a booted {@link Runtime} that\n * also carries the run's line, which is what `tell` asks for. A spread keeps the\n * line. An object built by hand cannot have one, because tea does not export its\n * key, so a {@link Runtime} that is not one of these does not compile as `tell`'s\n * argument. It fits anywhere a `Runtime` is asked for.\n */\nexport interface Run<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n> extends Runtime<S, M, E>,\n    Postable<S, M> {\n  ready: Promise<Run<S, M, E>>;\n}\n\n// === run ===\n//\n// Boot runs as the FIRST entry on the serial dispatch tail, which is how every\n// public method of the returned `BootingRuntime<S, M>` waits for it.\n//\n// Save-then-effects ordering is structural: every transition mutates state,\n// awaits `store.save(newState)`, then reconciles subscriptions, then tells\n// `subscribe` listeners, then runs `interpret` for emitted cmds, then fires\n// observers, `on` handlers and `done()` waiters. Those fire even when a Cmd\n// handler throws: the dispatch rejects with the handler's error, and each of\n// them still hears the State that was installed and saved (#311), as the\n// listeners already have. A throw in any effect\n// phase leaves the persisted state ahead of the host's belief about what\n// executed — the Railway discipline (`tryInterpret` in handlers) makes that\n// safe in practice.\n/**\n * Start a machine on the Promise engine and return its runtime. Pass the Cmd\n * handlers, the Sub runners, `ctx` and an optional `Store`; the runtime is\n * returned at once and every method waits for boot.\n *\n * Throws at once, before anything is loaded, when the store is fenced at runtime\n * and no `onError` was passed, even when the store is typed plain `Store<S>`\n * (ADR 0031).\n */\nexport function run<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n  E extends { type: string } = never,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: PromiseRunOptions<S, M, C, U, Ctx, E>,\n): BootingRun<S, M, E> {\n  // Thrown here, before the loop starts, so nothing is loaded or saved.\n  refuseFencedRunWithoutSink(opts.store, opts.onError);\n\n  // `interpret` is optional when `C extends Cmd<never>`; default a missing map\n  // to `{}` — a Cmd with no handler is skipped, invariant 6's forward progress\n  // for a miswired consumer.\n  const interpretMap = ((opts as { interpret?: Interpret<M, C, Ctx> })\n    .interpret ?? {}) as Readonly<Record<string, LoopHandler<M> | undefined>>;\n\n  // The runner for a Sub type: the one handed to `run` in `subscribe`, else\n  // the engine's built-in of that name (#270 — a user entry overrides a\n  // built-in). Looked up per start rather than merged once, so a handler table\n  // that resolves its cells lazily (`/react` reads the latest render's) is\n  // honoured.\n  const subscribeTable = (opts as { subscribe?: unknown }).subscribe as\n    | Readonly<Record<string, UserRunner<Ctx, M> | undefined>>\n    | undefined;\n  const builtins = builtinRunners as Readonly<\n    Record<string, UserRunner<Ctx, M> | undefined>\n  >;\n\n  // A Promise runner has no failure channel of its own: the one failure the\n  // engine sees is a throw while it starts, which the loop turns into a stopped\n  // run (#309). So the runner is called with the three arguments it declares.\n  function runnerFor(type: string): LoopRunner<Ctx, M> | undefined {\n    const runner = subscribeTable?.[type] ?? builtins[type];\n    if (runner === undefined) return undefined;\n    return (sub, ctx, dispatch) => runner(sub, ctx, dispatch);\n  }\n\n  const handle = startLoop<S, M, C, Ctx>({\n    init: machine.init,\n    reduce: (state, msg) => applyCell<S, M, C>(machine, state, msg),\n    subs: subEntriesOf<S>(machine),\n    runnerFor,\n    handlerFor: (type) => interpretMap[type],\n    store: opts.store,\n    // `ctx` is conditionally optional (see `CtxArg`); default the nullish case\n    // to `{}` so the handler ctx and `init(loaded, ctx)` get a value.\n    ctx: (opts.ctx ?? {}) as Ctx,\n    onError: opts.onError,\n    disposeTimeoutMs: opts.disposeTimeoutMs ?? 5_000,\n    idleCap: opts.__idleCap ?? 100_000,\n    extensions: builtinExtensions<S, M, C, E>(machine, opts),\n    // A Sub failure and a halting reducer throw stop the run the same way\n    // (ADR 0033). Deferred: a runner that throws during a storeless boot fails\n    // before `startLoop` has returned the handle.\n    stopOnFailure: () => {\n      queueMicrotask(() => void handle.stop());\n    },\n  });\n  return handle as unknown as BootingRun<S, M, E> & LiveWorkProbe;\n}\n\n/** A runner as a caller hands it to `run` in `subscribe`. */\ntype UserRunner<Ctx, M> = (\n  sub: Sub,\n  ctx: Ctx,\n  dispatch: (msg: M) => void,\n) => Dispose;\n\n/**\n * Is the runtime provably out of ways to transition on its own? True only when\n * the handle carries the `liveWork` read and it counts zero live Subs and zero\n * in-flight Cmds. A handle without the read (a wrapper that rebuilt the object\n * without spreading it) cannot be proven stalled, so the drive keeps waiting —\n * the pre-#68 contract, never a false stall.\n */\nfunction isStalled(runtime: object): boolean {\n  const probe = (runtime as Partial<LiveWorkProbe>)[liveWork];\n  if (probe === undefined) return false;\n  const live = probe();\n  return live.subs === 0 && live.cmds === 0;\n}\n\n/**\n * The outside-in stop, as a PAIR. A signal is only cancellation if something can\n * turn \"aborted\" into a transition this machine understands, and the kernel has\n * no built-in cancel Msg any more than it has a built-in terminal set — so the\n * `signal` and the `cancel` that reads it are one option, present together or\n * absent together. A discriminated union rather than two optional fields, on the\n * same reasoning as `AgentCompactionConfig`: a signal with no `cancel` is a stop\n * button wired to nothing, and that is a state worth making unrepresentable\n * rather than checking for.\n */\ntype DriveCancellation<S, M> =\n  | {\n      readonly signal?: undefined;\n      readonly cancel?: undefined;\n    }\n  | {\n      /**\n       * Abort the run through this signal. On abort the drive dispatches\n       * `cancel`'s Msg and resolves on the State that lands — it does NOT reject,\n       * and a cancellation is never a `DriveFailedError`. Already aborted when\n       * the drive is called → the cancel Msg goes in place of `start`, so the\n       * run ends without the start's effects ever firing.\n       */\n      readonly signal: AbortSignal;\n      /**\n       * The Msg that settles this machine as cancelled, chosen off the current\n       * State exactly as `start` is. PURE. It must land a State `isTerminal`\n       * holds for — the drive resolves on the terminal predicate, not on the\n       * abort — and that State should be DURABLE, or a reload resumes the run\n       * its caller stopped.\n       */\n      readonly cancel: (state: S) => M;\n    };\n\n/** Options for `driveToDone`. */\nexport type DriveToDoneOptions<\n  S,\n  M extends { type: string } = never,\n> = DriveCancellation<S, M> & {\n  /**\n   * Marks a terminal State as a FAILURE. A State this holds for ends the drive\n   * like any terminal one — the runtime is stopped — but the drive REJECTS with\n   * `DriveFailedError` carrying it instead of resolving. A failed State is\n   * terminal by definition; it need not also satisfy `isTerminal`. Omit → the\n   * drive never rejects on State, only on a runtime error.\n   */\n  readonly failed?: (state: S) => boolean;\n};\n\n/**\n * Drive a machine from `start` to its terminal State in one call, then tear the\n * runtime down. The one-shot shape every \"run this machine to done\" test and\n * caller boundary otherwise hand-wires as six steps — `await ready`, `observe`,\n * park a promise, `dispatch(start)`, `getState()`, `stop()` — with the observer\n * leak and the forgotten `stop` those six steps invite.\n *\n * Takes the handle `run()` returns (a `Runtime` extends it, so a booted one is\n * accepted too), awaits `ready`, dispatches `start`, and resolves with the first\n * State for which `isTerminal` holds. A machine that boots already terminal (a\n * rehydrated finished run) resolves on its boot State and `start` is never\n * dispatched — a finished run has nothing to set in motion. `start` may be a\n * function of the boot State instead of a Msg: a machine rehydrated MID-run\n * needs its resume Msg, not its start Msg, and only the boot State says which\n * (the agent's `agent_boot` vs `agent_start` is the case in point). The\n * observer is detached and `stop()` awaited on EVERY exit: resolve, `failed`,\n * a stall, a boot or dispatch throw, the quiescence cap.\n *\n * Use this for a deliberate host `start` Msg after boot. Subs have already\n * opened by then. A machine whose restored first move must precede their Msgs\n * returns its resume Cmds and in-flight State from init instead; do not also\n * use `start` to resume that same work.\n *\n * Rejections are typed, never silent:\n *   - `DriveFailedError<S>` when `opts.failed` marks the final State — the State\n *     rides on `error.state`.\n *   - `DriveStalledError<S>` when `start`'s follow-up chain quiesces on a State\n *     that is neither terminal nor `failed` and the runtime has no live Sub and\n *     no Cmd in flight — nothing inside it can deliver another transition, so\n *     waiting would be a hang with the runtime leaked. The stalled State rides\n *     on `error.state`. A machine that CAN still move is not stalled: a live Sub\n *     that delivers the terminal Msg after the dispatch\n *     quiesces keeps the drive waiting, and it resolves on that State. What the\n *     runtime cannot see — a dispatch from outside it after quiescence — does\n *     not count as live; a machine that depends on one declares it as a Sub.\n *   - `QuiescenceTimeoutError` when `start`'s follow-up chain never settles —\n *     the SAME cap `dispatch` and `idle()` already reject on (invariant 6), not a\n *     second clock. A livelocking machine surfaces as its own failure class.\n *   - the boot error, or whatever `dispatch(start)` rejects with, otherwise.\n *\n * `isTerminal` is caller-supplied, exactly as `run()`'s `terminal` option is —\n * the kernel has no built-in terminal-set concept and this does not add one.\n *\n * Cancellation is the same story: `{ signal, cancel }` stops the drive from\n * outside, and it settles the run rather than escaping it. On abort the drive\n * dispatches `cancel`'s Msg and RESOLVES on the terminal State that transition\n * lands — no rejection, no `DriveFailedError`, no `AbortError`. That is the whole\n * point of routing a stop through the Model: the outcome is durable, so a killed\n * process resumes reading a run that ended instead of restarting one someone\n * stopped. A cancel that THROWS is the one abort that rejects: it lands\n * no State, so its error is what the drive has to report — and that holds\n * whether the `cancel` function throws synchronously or the fold it produced\n * throws later, since both leave the run with no State to settle on. A State the\n * caller's `failed` predicate marks rejects on an abort exit exactly as it does\n * anywhere else. In-flight effects are not recalled — a promise cannot be cancelled —\n * so they settle to their own end and `stop()` drains them, up to\n * `disposeTimeoutMs`;\n * keeping their results off the public channels is the machine's own business.\n * Omit the pair and every path here behaves exactly as it did before.\n *\n * @param handle     the handle `run(machine, opts)` returned.\n * @param start      the Msg that sets the run in motion, or a function choosing\n *                   it off the boot State. PURE.\n * @param isTerminal the terminal predicate over the machine's State. PURE.\n * @param opts       an optional `failed` predicate and an optional\n *                   `{ signal, cancel }` pair (see {@link DriveToDoneOptions}).\n */\nexport async function driveToDone<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n>(\n  handle: BootingRuntime<S, M, E>,\n  start: M | ((booted: S) => M),\n  isTerminal: (state: S) => boolean,\n  opts: DriveToDoneOptions<S, M> = {},\n): Promise<S> {\n  const failed = opts.failed ?? (() => false);\n  const settles = (state: S): boolean => isTerminal(state) || failed(state);\n  let detach: (() => void) | undefined;\n  let unlisten: (() => void) | undefined;\n  try {\n    const runtime = await handle.ready;\n    // A run that rehydrated already terminal has nothing to start: resolve on\n    // the boot State without dispatching, so `start`'s Cmds are never left in\n    // flight for `stop()` to discard. Read BEFORE the signal so a run that\n    // already ended keeps the outcome it ended on — an abort arriving after the\n    // fact does not restate a finished run as cancelled.\n    const booted = runtime.getState();\n    // The one exit check every branch below shares: a State the caller's\n    // `failed` predicate marks rejects, wherever the drive reached it.\n    const outcome = (state: S): S => {\n      if (failed(state)) throw new DriveFailedError(state);\n      return state;\n    };\n    if (settles(booted)) return outcome(booted);\n    // Attach BEFORE dispatching so a terminal transition landing inside the\n    // start dispatch is caught.\n    const terminal = new Promise<S>((resolve) => {\n      detach = runtime.observe((_msg, state) => {\n        if (settles(state)) resolve(state);\n      });\n    });\n    // An abort mid-run enqueues the cancel Msg on the SAME serial tail every\n    // other dispatch uses, so it lands between transitions rather than inside\n    // one. Work already enqueued when the abort arrives still folds; work the\n    // machine would have enqueued after it does not, because the cancelled State\n    // is terminal and its verbs stop emitting. `dispatchOnce` (not `dispatch`)\n    // because the cancel has no follow-up chain to drain. Its rejection is NOT\n    // swallowed: only the cancel fold can land the terminal State on an abort,\n    // so a cancel that throws leaves `terminal` with nothing to resolve it and\n    // the drive would park forever (#170). `cancelFailed` carries that rejection\n    // into whichever race the branch below awaits.\n    let cancelFailed: Promise<never> | undefined;\n    if (opts.signal !== undefined) {\n      const { signal, cancel } = opts;\n      let onCancelError!: (error: unknown) => void;\n      cancelFailed = new Promise<never>((_resolve, reject) => {\n        onCancelError = reject;\n      });\n      // The try covers the SYNCHRONOUS call site too, not just the dispatch it\n      // returns: a caller-supplied `cancel` that throws before it ever produces\n      // a Msg would otherwise escape this listener, and a listener's throw goes\n      // nowhere — no caller frame to catch it, `terminal` still unresolved, the\n      // drive parked exactly as #170 described (#174). Both throws are the same\n      // fact — the cancel fold could not land a State — so both take the one\n      // route out through `onCancelError`.\n      const onAbort = () => {\n        try {\n          runtime.dispatchOnce(cancel(runtime.getState())).catch(onCancelError);\n        } catch (error) {\n          onCancelError(error);\n        }\n      };\n      // Already aborted → cancel INSTEAD of starting, so `start`'s effects (a\n      // model call, for the agent) never fire at all.\n      if (signal.aborted) {\n        onAbort();\n        return outcome(await Promise.race([terminal, cancelFailed]));\n      }\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n      unlisten = () => signal.removeEventListener(\"abort\", onAbort);\n    }\n    // The race lets a dispatch rejection (reducer / interpret throw, the\n    // quiescence cap) surface here instead of floating as an unhandled rejection\n    // while the terminal await parks forever.\n    const msg = typeof start === \"function\" ? start(booted) : start;\n    const started = runtime.dispatch(msg).then(() => {\n      // Quiesced. A settling State already went through the observer, so\n      // `terminal` is resolved; otherwise the wait is legitimate only while the\n      // runtime itself can still transition. With no live Sub and no Cmd in\n      // flight nothing is coming, and the wait becomes the hang #68 names.\n      const parked = runtime.getState();\n      if (!settles(parked) && isStalled(runtime)) {\n        throw new DriveStalledError(parked);\n      }\n      return terminal;\n    });\n    // `cancelFailed` rides the race for the mid-run abort: `started` cannot\n    // carry the cancel's rejection, having usually resolved long before the\n    // abort arrives.\n    const racers: Promise<S>[] = [terminal, started];\n    if (cancelFailed !== undefined) racers.push(cancelFailed);\n    return outcome(await Promise.race(racers));\n  } finally {\n    detach?.();\n    // The abort listener outlives this call unless it is removed: a signal a\n    // caller reuses across runs would otherwise accumulate one dispatch per run\n    // it has already finished.\n    unlisten?.();\n    // `stop()` resolves by contract, so awaiting it here cannot mask the error\n    // a rejecting branch above is carrying. It can delay it, by up to\n    // `disposeTimeoutMs` per wait, while a Cmd handler has not returned.\n    await handle.stop();\n  }\n}\n","import type { TellAnswer } from \"../internal/engine/loop\";\nimport { tellRun } from \"../internal/engine/tell\";\nimport type { Cmd, Machine, Sub } from \"../pure/core\";\nimport type { Run } from \"./run\";\n\nexport type { TellAnswer } from \"../internal/engine/loop\";\n\n/**\n * Put `msg` on a run's line and return at once. The answer means queued, not\n * handled: the receiver's step has not run yet, and any result comes back later\n * as its own Msg. So two machines can tell each other from their Cmd handlers\n * and neither stops. `machine` is the machine `runtime` runs.\n *\n * The answer is `\"queued\"`, `\"stopped\"` for a run that is stopping or has\n * stopped, or `\"no_cell\"` when its current State has no cell for the Msg. Msgs\n * already in line have not folded yet, so a Msg that only a queued one makes\n * acceptable answers `\"no_cell\"`.\n *\n * `runtime` is what `ready` resolved to, or a spread of it. Those carry the run's\n * line, and the type asks for it, so a `Runtime` built by hand, a fake or\n * `noopRuntime` is a compile error. So is the handle `run` returned, with a store\n * or without one: wait for `ready`. A hand-built object cast past the type has no\n * line to put a Msg on, and `tell` throws there.\n *\n * What happens after `\"queued\"` is the receiver's. Two `tell`s from one sender\n * fold in the order they were sent. A failed save or a handler's throw goes to\n * the receiver's `onError`, never back to the sender. A Msg whose cell is gone\n * by its turn is dropped without a word, and a `stop()` that gives up drops\n * what is still in line and counts it, per Msg type, in its\n * `DrainTimeoutNotice`.\n *\n * Two hand-written `await runtime.dispatch(...)` calls into each other, one from\n * each machine's Cmd handler, still stop both machines: `dispatch` waits, and\n * tea has no lock-up detector. Use `tell` there.\n *\n * ```ts\n * const answer = tell(parent, parentRun, { type: \"child_result\", id });\n * ```\n */\nexport function tell<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n  E extends { type: string } = never,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  runtime: Run<S, M, E>,\n  msg: NoInfer<M>,\n): TellAnswer {\n  return tellRun<S, M>(machine, runtime, msg);\n}\n"]}

package/dist/{chunk-GAVLND5C.js → chunk-A3QPMX5M.js}

@@ -530,6 +530,15 @@ var PortNameCollisionError = class extends Error {
 function __resetPortRegistry() {
   definedPortNames.clear();
 }
+var SubFailedError = class extends Error {
+  constructor(cause) {
+    super("@demlik/tea: a Sub failed and stopped the run.");
+    this.cause = cause;
+  }
+  cause;
+  name = "SubFailedError";
+  _tag = "SubFailedError";
+};
 var QuiescenceTimeoutError = class extends Error {
   constructor(iterations) {
     super(
@@ -601,17 +610,20 @@ var DisposeTimeoutNotice = class extends RuntimeDiscardNotice {
   _tag = "DisposeTimeoutNotice";
 };
 var DrainTimeoutNotice = class extends RuntimeDiscardNotice {
-  constructor(cmdTypes, pendingCmds, timeoutMs) {
+  constructor(cmdTypes, pendingCmds, timeoutMs, droppedMsgs = {}) {
+    const dropped = Object.entries(droppedMsgs);
     super(
-      `@demlik/tea: stop() gave up waiting for the queue after ${timeoutMs}ms with ${pendingCmds} Cmd(s) still in flight` + (cmdTypes.length > 0 ? ` (${cmdTypes.map((type) => `"${type}"`).join(", ")})` : "") + ` \u2014 whatever they return, the rest of their step and the Msgs queued behind them are dropped. No store call starts after stop() has returned; one already under way can still land. Bound the handler's own IO so it returns, or raise run({ disposeTimeoutMs }).`
+      `@demlik/tea: stop() gave up waiting for the queue after ${timeoutMs}ms with ${pendingCmds} Cmd(s) still in flight` + (cmdTypes.length > 0 ? ` (${cmdTypes.map((type) => `"${type}"`).join(", ")})` : "") + (dropped.length > 0 ? ` and these Msgs queued: ${dropped.map(([type, count]) => `"${type}" x${count}`).join(", ")}` : "") + ` \u2014 whatever they return, the rest of their step and the Msgs queued behind them are dropped. No store call starts after stop() has returned; one already under way can still land. Bound the handler's own IO so it returns, or raise run({ disposeTimeoutMs }).`
     );
     this.cmdTypes = cmdTypes;
     this.pendingCmds = pendingCmds;
     this.timeoutMs = timeoutMs;
+    this.droppedMsgs = droppedMsgs;
   }
   cmdTypes;
   pendingCmds;
   timeoutMs;
+  droppedMsgs;
   name = "DrainTimeoutNotice";
   _tag = "DrainTimeoutNotice";
 };
@@ -708,11 +720,6 @@ function asReducer(reducer) {
 function replay(machine, opts) {
   const loaded = opts.loaded ?? null;
   const [initialState, initCmds] = machine.init(loaded, opts.ctx);
-  if (loaded !== null && initCmds.length > 0) {
-    throw new Error(
-      "TEA contract violation: machine.init must return [state, []] (no Cmds) when `loaded` is non-null. Init's rehydrate branch is a pure state passthrough \u2014 the migration/parse boundary, not the boot-effect hook.\n\nRoutes for boot effects:\n  - Stateless infrastructure (e.g. chrome.alarms ensure) \u2192 host module top level, outside TEA.\n  - State-conditional resume (e.g. re-attach a session) \u2192 a `boot` Msg dispatched once from the host after `run(...)` returns, handled in update.\n\nSee .patterns/tea/tea-invariants.md (Invariant 2)."
-    );
-  }
   const { state, cmds: foldedCmds } = foldUpdates(
     machine,
     initialState,
@@ -772,6 +779,6 @@ function tryInterpret(work, onOk, onErr) {
   };
 }
 
-export { AsyncSchemaError, Cmd, DispatchDiscardedError, DisposeTimeoutNotice, DrainTimeoutNotice, DriveFailedError, DriveStalledError, IdentityDropNotice, NoCellError, Outcome, OutcomeContractError, PortNameCollisionError, QuiescenceTimeoutError, Refusal, RuntimeDiscardNotice, RuntimeDiscardedError, StoreConflictError, StoreRefusedError, UndeclaredFailureError, __resetPortRegistry, absurd, acceptedTypes, acceptsOf, applyCell, applyCellChecked, asReducer, checkedStep, cmdContractOver, cmdEdge, cmdEdgeOf, defineMachine, definePort, describeError, describeMachine, desiredSub, detachWork, detachWorkOf, detectUpdateForm, foldMsgs, foldUpdates, followUps, formOf, isFencedStore, lookupCell, malformedResult, msgKeysOf, noop, refuse, replay, schemaMigrate, structuralHash, subEntriesOf, subId, subIdOf, tryApplyCell, tryFoldMsgs, tryInterpret, validateSync, without, wrapDetached };
-//# sourceMappingURL=chunk-GAVLND5C.js.map
-//# sourceMappingURL=chunk-GAVLND5C.js.map
+export { AsyncSchemaError, Cmd, DispatchDiscardedError, DisposeTimeoutNotice, DrainTimeoutNotice, DriveFailedError, DriveStalledError, IdentityDropNotice, NoCellError, Outcome, OutcomeContractError, PortNameCollisionError, QuiescenceTimeoutError, Refusal, RuntimeDiscardNotice, RuntimeDiscardedError, StoreConflictError, StoreRefusedError, SubFailedError, UndeclaredFailureError, __resetPortRegistry, absurd, acceptedTypes, acceptsOf, applyCell, applyCellChecked, asReducer, checkedStep, cmdContractOver, cmdEdge, cmdEdgeOf, defineMachine, definePort, describeError, describeMachine, desiredSub, detachWork, detachWorkOf, detectUpdateForm, foldMsgs, foldUpdates, followUps, formOf, isFencedStore, lookupCell, malformedResult, msgKeysOf, noop, refuse, replay, schemaMigrate, structuralHash, subEntriesOf, subId, subIdOf, tryApplyCell, tryFoldMsgs, tryInterpret, validateSync, without, wrapDetached };
+//# sourceMappingURL=chunk-A3QPMX5M.js.map
+//# sourceMappingURL=chunk-A3QPMX5M.js.map