@demlik/tea 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -1,10 +1,71 @@
-import { B as BootingRuntime, C as CtxArg, S as Store, O as OnError, a as Supervision } from './runtime-types-CNLmhWif.js';
-export { b as Branded, D as DispatchDiscardedError, c as DispatchSettle, d as DisposeTimeoutNotice, F as FoldRefusal, I as IdentityDropNotice, P as PortNameCollisionError, Q as QuiescenceTimeoutError, R as Runtime, e as RuntimeDiscardNotice, f as RuntimeDiscardedError, g as RuntimeErrorContext, h as RuntimeErrorPhase, i as RuntimeRef, j as Schema, k as SubIdCollisionError, l as SupervisionStrategy, _ as __resetPortRegistry, m as absurd, n as asReducer, o as defineMachine, p as definePort, q as noop, r as replay, s as schemaMigrate, t as settle, u as tryApplyCell, v as tryFoldMsgs, w as tryInterpret, x as wrapDetached } from './runtime-types-CNLmhWif.js';
-import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from './core-Co0LWkIA.js';
-export { A as AnyCmdDef, h as CmdDef, i as CmdInput, e as CmdOf, j as CmdValue, k as ContextFree, D as DepKeyedSub, l as Dispose, E as ErrOf, m as ErrorsOf, n as Identity, I as Interpret, g as InterpretDetached, o as MachineShape, p as MalformedResult, q as Needs, f as NeedsOf, N as NoCellError, r as NoCtx, O as OkOf, a as Port, P as PortEmitter, c as Reducer, d as Settled, s as SettledErr, t as SettledOk, b as SubId, u as Subscribe, v as SyncReturn, w as Tagged, x as TaggedError, T as Transitions, U as UpdateForm, y as acceptsOf, z as applyCell, B as applyCellChecked, F as describeMachine, G as detectUpdateForm, H as foldMsgs, J as foldUpdates, K as formOf, L as msgKeysOf, Q as structuralHash, V as subId } from './core-Co0LWkIA.js';
+import { B as BootingRuntime, a as ScopedCtxArg, S as Store, O as OnError, b as Supervision, R as Runtime } from './runtime-types-CMF13BBh.js';
+export { c as Branded, C as CtxArg, D as DepToken, d as DepsOf, e as DispatchDiscardedError, f as DispatchSettle, g as DisposeTimeoutNotice, h as DriveFailedError, i as DriveStalledError, j as FencedRead, F as FencedStore, k as FoldRefusal, I as IdentityDropNotice, M as MachineTypes, l as OnReleaseError, P as PortNameCollisionError, m as ProvideFailedError, n as Provided, o as ProvidedCtx, p as Provider, q as ProviderCycleError, Q as QuiescenceTimeoutError, r as RuntimeDiscardNotice, s as RuntimeDiscardedError, t as RuntimeErrorContext, u as RuntimeErrorPhase, v as RuntimeRef, w as Schema, x as Scope, y as StoreConflictError, z as SubIdCollisionError, A as SupervisionStrategy, U as UnknownProviderError, _ as __resetPortRegistry, E as absurd, G as asReducer, H as defineMachine, J as definePort, K as dep, L as isFencedStore, N as isProvided, T as layer, V as noop, W as provide, X as replay, Y as schemaMigrate, Z as settle, $ as tryApplyCell, a0 as tryFoldMsgs, a1 as tryInterpret, a2 as value, a3 as wrapDetached } from './runtime-types-CMF13BBh.js';
+import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx, P as Port, D as Dispose, o as DepKeyedSub, c as SubId } from './core-DnzqWy6u.js';
+export { A as AnyCmdDef, b as CmdDef, p as CmdInput, a as CmdOf, l as CmdValue, E as ErrOf, q as ErrorsOf, r as ExhaustiveTransitions, s as Identity, I as Interpret, h as InterpretDetached, t as MachineShape, k as MalformedResult, N as NoCellError, i as NoCtx, O as OkOf, g as PortEmitter, d as Reducer, m as Requirements, f as RequirementsOf, e as Settled, u as SettledErr, v as SettledOk, w as Subscribe, x as SyncReturn, j as Tagged, n as TaggedError, T as Transitions, U as UpdateForm, y as acceptedTypes, z as acceptsOf, B as applyCell, F as applyCellChecked, G as describeMachine, H as detectUpdateForm, J as foldMsgs, K as foldUpdates, L as formOf, Q as msgKeysOf, V as structuralHash, W as subId } from './core-DnzqWy6u.js';
+import { S as SubscribeHandler } from './types-BseNPIhr.js';
 import 'better-result';
 import 'zod';
 
+/**
+ * @packageDocumentation
+ * The composition seam — the layer between a battery and a door.
+ *
+ * A battery is pure state plus verbs over that state. A door holds several
+ * batteries side by side in one Model. Everything between those two facts was,
+ * until now, hand-written at every consumer: the one-key record rebuild that
+ * threads a verb's `[slice, cmds]` result back into the host state, and the
+ * statement order that decides which slice wins a derived read.
+ *
+ * Two helpers cover it, and neither is an optics kit. {@link liftSlice} is the
+ * record rebuild with the key checked by the type system; {@link readInOrder}
+ * turns a read's precedence from statement order into a value you can name,
+ * export and assert on. ADR 0001 (no off-the-shelf resilience) and ADR 0014
+ * (Effect's types, never its runtime values) between them settle why this is
+ * forty lines here rather than a dependency.
+ *
+ * Both are pure: no clock, no RNG, no storage, nothing captured. A `liftSlice`
+ * result is a fresh record and a Cmd array, so ADR 0014's journal/hash promise
+ * over a reducer's return value is untouched.
+ */
+/**
+ * Lift a battery verb's result into the host state that carries its slice.
+ *
+ * `liftSlice("resilience", state, knob.attempt(state.resilience, …))` is the
+ * `{ ...state, resilience: slice }` every consumer writes by hand, with the key
+ * checked: `key` must be a key of `S`, and the slice the verb returned must be
+ * assignable to the type that key carries — so naming the wrong field, or
+ * threading one battery's slice into another's key, is a compile error rather
+ * than a state shape nothing reads correctly.
+ *
+ * PURE — a fresh record and the verb's own Cmds, unchanged.
+ */
+declare function liftSlice<S, K extends keyof S, C>(key: K, state: S, [slice, cmds]: readonly [S[K], readonly C[]]): readonly [S, readonly C[]];
+/**
+ * One step of a composed read: the slice it consults, under the name that slice
+ * goes by. `read` returns `undefined` for "this slice has nothing to say",
+ * which is what hands the read on to the next step.
+ */
+interface ReadStep<In, Out> {
+    /** The slice this step consults — `"cache"`, `"failed"`, `"inFlight"`. */
+    readonly name: string;
+    /** What this slice says about `input`, or `undefined` to defer. */
+    readonly read: (input: In) => Out | undefined;
+}
+/**
+ * Run a composed read through `order` and return the first answer any step
+ * gives, or `absent` when every one defers.
+ *
+ * The point is that `order` is a VALUE. A derived read over three battery
+ * slices otherwise states its precedence as the order of three `if` statements,
+ * where it is invisible to the type system, unnameable in a test and one
+ * innocent-looking reshuffle away from being wrong — which is exactly the
+ * defect that escaped `classify-batch`'s per-battery test suites. Written as
+ * data, the precedence can be exported, printed and asserted on directly.
+ *
+ * PURE — it evaluates `read` in order and stores nothing.
+ */
+declare function readInOrder<In, Out>(input: In, order: readonly ReadStep<In, Out>[], absent: Out): Out;
+
 interface HistoryTracker<S, M extends {
     type: string;
 }> {
@@ -51,6 +112,135 @@ declare function historyTracker<S, M extends {
     type: string;
 }>(runtime: BootingRuntime<S, M>, size: number): HistoryTracker<S, M>;
 
+/**
+ * internal/prediction — the client-prediction ack primitive (epic #186, facet 2).
+ * Internal since #49 — not published on any subpath of its own; the
+ * client-safe barrel `src/pure/` re-exports the public surface, and the root
+ * `@demlik/tea` door publishes it.
+ *
+ * The contract the Gambetta/Valve authoritative-server netcode loop needs:
+ * **command-seq-in → last-applied-seq-out.** A client tags each predicted
+ * command/`Msg` with a monotonic `seq`; the authoritative side replies with the
+ * `lastAppliedSeq` it has processed. `partitionByAck` then splits the client's
+ * pending buffer into the inputs the server has ACKED (`seq <= lastAppliedSeq`)
+ * and those still PENDING (`seq > lastAppliedSeq`) — the un-acked tail the
+ * reconciliation pass (#214) replays over the authoritative snapshot via
+ * `foldMsgs` (#211, the client-safe barrel `src/pure/`).
+ *
+ * Deliberately **Model-shape-agnostic** (ADR 0006): the ack is a standalone
+ * value, NOT a field this module requires on the consumer's `State`. It
+ * generalizes the `lastAckedSeq`-on-the-Model + `seq`-threaded-through-the-Msg
+ * pattern vortex hand-rolled (epic #186). It is a LEAF module — pure and
+ * runtime-free, importing nothing from the tea core or host, so it can never
+ * drag `run`/the host into a client bundle.
+ *
+ * This is the read/ack side of the primitive; `tagSeq`/`nextSeq` are the write
+ * side, letting a client mint monotonic seqs from its pending buffer alone —
+ * again with no counter field on the Model.
+ *
+ * `reconcile` (the read side's payoff, #214) composes this ack partition with
+ * the pure fold seam `foldMsgs` to perform the whole Gambetta/Valve
+ * reconciliation step in one call. The `foldMsgs` import is the ONLY dependency
+ * this leaf takes, and it reaches into the pure-core leaf (`../pure/core`) — NOT
+ * the runtime root — so the module stays runtime-free and the client-safe
+ * import-graph guard (ADR 0006, #213) still holds.
+ */
+
+/**
+ * A monotonic, non-negative sequence number tagging one client-predicted
+ * command. Monotonicity is the client's contract (mint successive seqs with
+ * `nextSeq`); this module only ever *compares* seqs.
+ */
+type Seq = number;
+/** A command (or `Msg`) tagged with the `seq` the client assigned it. */
+interface SeqTagged<T> {
+    readonly seq: Seq;
+    readonly value: T;
+}
+/** Tag a command/`Msg` with its sequence number. */
+declare const tagSeq: <T>(seq: Seq, value: T) => SeqTagged<T>;
+/**
+ * The authoritative side's acknowledgement: the highest `seq` it has applied.
+ * Everything with `seq <= lastAppliedSeq` is settled; everything above is still
+ * in flight. This *is* the whole "ack from the authoritative side" — a value
+ * the consumer carries however it likes (a wire field, a message payload),
+ * never a shape this module imposes on the Model.
+ */
+interface Ack {
+    readonly lastAppliedSeq: Seq;
+}
+/** Construct an `Ack` for a last-applied sequence number. */
+declare const ack: (lastAppliedSeq: Seq) => Ack;
+/**
+ * The "nothing applied yet" cursor — the ack value for a server that has applied
+ * no client input at all. Because `nextSeq` mints **0-based** seqs and
+ * `partitionByAck` acks **inclusively** (`seq <= lastAppliedSeq`), the pre-first
+ * cursor must sit strictly *below* seq 0: `lastAppliedSeq = 0` would falsely ack
+ * the seq-0 input before the server ever saw it. `-1` is "before any seq", and
+ * `partitionByAck(buffer, NO_ACK)` therefore leaves the whole buffer PENDING.
+ *
+ * This names the boundary value on the seam so no consumer has to re-discover it
+ * as a magic number: it is the primitive's own design (0-based mint + inclusive
+ * partition) that creates the trap, so it is the primitive's job to name the
+ * escape. Pair with {@link initAck} when an {@link Ack} is wanted instead of the
+ * bare `Seq`.
+ */
+declare const NO_ACK: Seq;
+/**
+ * The `Ack` for a server that has applied nothing yet — `ack(NO_ACK)`. The `Ack`
+ * counterpart to the {@link NO_ACK} `Seq` sentinel, for a consumer that carries
+ * an `Ack` rather than a bare `lastAppliedSeq`.
+ */
+declare const initAck: () => Ack;
+/** The result of splitting a seq-tagged buffer against an ack. */
+interface AckPartition<T> {
+    /** Inputs the authoritative side has applied (`seq <= lastAppliedSeq`). */
+    readonly acked: readonly SeqTagged<T>[];
+    /** Inputs still in flight / un-acked (`seq > lastAppliedSeq`) — the replay tail. */
+    readonly pending: readonly SeqTagged<T>[];
+}
+/**
+ * Partition a buffer of seq-tagged commands into ACKED and PENDING against the
+ * authoritative `lastAppliedSeq`. Pure and total: every item lands in exactly
+ * one bucket, input order is preserved within each bucket, and the boundary
+ * `seq == lastAppliedSeq` is ACKED (inclusive `<=`). Routing is by `seq` value,
+ * not buffer position, so an out-of-order or duplicate-seq buffer partitions
+ * correctly. Accepts either an {@link Ack} or a bare `lastAppliedSeq` number, so
+ * a caller passes whichever it holds.
+ */
+declare const partitionByAck: <T>(buffer: readonly SeqTagged<T>[], ackOrSeq: Ack | Seq) => AckPartition<T>;
+/**
+ * The next sequence number to assign: one past the highest `seq` in the buffer,
+ * or `0` for an empty buffer. Lets a client mint monotonic seqs from its pending
+ * buffer alone — no counter field on the Model — and is tolerant of an unordered
+ * buffer (it takes the max, not the last element).
+ */
+declare const nextSeq: <T>(buffer: readonly SeqTagged<T>[]) => Seq;
+/**
+ * The client prediction/reconciliation helper — the Gambetta/Valve
+ * authoritative-server loop's reconcile step, generalized.
+ *
+ * Given the latest `authoritativeState` from the server, the server's
+ * `lastAppliedSeq` ack, and the client's `pending` buffer of seq-tagged inputs,
+ * it returns the corrected predicted state: drop the inputs the server has
+ * already applied (`seq <= lastAppliedSeq`) and replay ONLY the un-acked tail
+ * (`seq > lastAppliedSeq`) over the authoritative snapshot.
+ *
+ * It is **composed, not re-derived** (ADR 0006): the drop is {@link partitionByAck}
+ * (the ack primitive, #212) and the replay is `foldMsgs` (the pure fold seam,
+ * #211) — there is no second copy of the partition logic and no second copy of
+ * the fold. `lastAppliedSeq` accepts either an {@link Ack} or a bare `Seq`, so a
+ * caller passes whichever it holds, matching `partitionByAck`.
+ *
+ * Pure and host-agnostic: it takes the `machine` (which `foldMsgs` needs to
+ * dispatch `update`) but touches no `Store`, `interpret`, or subscription, and
+ * imports nothing from the runtime — so it ships through the client-safe
+ * umbrella without dragging `run` into a client bundle.
+ */
+declare function reconcile<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, authoritativeState: S, lastAppliedSeq: Ack | Seq, pending: readonly SeqTagged<M>[]): S;
+
 /**
  * @demlik/tea runtime — `run`: boot + the serial dispatch loop. The pure helpers
  * that compose against a machine without running it (`replay`, `tryInterpret`)
@@ -61,7 +251,7 @@ declare function run<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx, E extends {
     type: string;
-} = never>(machine: Machine<S, M, C, U, Ctx>, opts: CtxArg<Ctx & RequiredCtx<C>> & {
+} = never>(machine: Machine<S, M, C, U, Ctx>, opts: ScopedCtxArg<Ctx & RequiredCtx<C>> & {
     store?: Store<S>;
     onError?: OnError;
     /**
@@ -111,5 +301,580 @@ declare function run<S, M extends {
      */
     __idleCap?: number;
 }): BootingRuntime<S, M, E>;
+/**
+ * The outside-in stop, as a PAIR. A signal is only cancellation if something can
+ * turn "aborted" into a transition this machine understands, and the kernel has
+ * no built-in cancel Msg any more than it has a built-in terminal set — so the
+ * `signal` and the `cancel` that reads it are one option, present together or
+ * absent together. A discriminated union rather than two optional fields, on the
+ * same reasoning as `AgentCompactionConfig`: a signal with no `cancel` is a stop
+ * button wired to nothing, and that is a state worth making unrepresentable
+ * rather than checking for.
+ */
+type DriveCancellation<S, M> = {
+    readonly signal?: undefined;
+    readonly cancel?: undefined;
+} | {
+    /**
+     * Abort the run through this signal. On abort the drive dispatches
+     * `cancel`'s Msg and resolves on the State that lands — it does NOT reject,
+     * and a cancellation is never a `DriveFailedError`. Already aborted when
+     * the drive is called → the cancel Msg goes in place of `start`, so the
+     * run ends without the start's effects ever firing.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The Msg that settles this machine as cancelled, chosen off the current
+     * State exactly as `start` is. PURE. It must land a State `isTerminal`
+     * holds for — the drive resolves on the terminal predicate, not on the
+     * abort — and that State should be DURABLE, or a reload resumes the run
+     * its caller stopped.
+     */
+    readonly cancel: (state: S) => M;
+};
+/** Options for `driveToDone`. */
+type DriveToDoneOptions<S, M extends {
+    type: string;
+} = never> = DriveCancellation<S, M> & {
+    /**
+     * Marks a terminal State as a FAILURE. A State this holds for ends the drive
+     * like any terminal one — the runtime is stopped — but the drive REJECTS with
+     * `DriveFailedError` carrying it instead of resolving. A failed State is
+     * terminal by definition; it need not also satisfy `isTerminal`. Omit → the
+     * drive never rejects on State, only on a runtime error.
+     */
+    readonly failed?: (state: S) => boolean;
+};
+/**
+ * Drive a machine from `start` to its terminal State in one call, then tear the
+ * runtime down. The one-shot shape every "run this machine to done" test and
+ * caller boundary otherwise hand-wires as six steps — `await ready`, `observe`,
+ * park a promise, `dispatch(start)`, `getState()`, `stop()` — with the observer
+ * leak and the forgotten `stop` those six steps invite.
+ *
+ * Takes the handle `run()` returns (a `Runtime` extends it, so a booted one is
+ * accepted too), awaits `ready`, dispatches `start`, and resolves with the first
+ * State for which `isTerminal` holds. A machine that boots already terminal (a
+ * rehydrated finished run) resolves on its boot State and `start` is never
+ * dispatched — a finished run has nothing to set in motion. `start` may be a
+ * function of the boot State instead of a Msg: a machine rehydrated MID-run
+ * needs its resume Msg, not its start Msg, and only the boot State says which
+ * (the agent's `agent_boot` vs `agent_start` is the case in point). The
+ * observer is detached and `stop()` awaited on EVERY exit: resolve, `failed`,
+ * a stall, a boot or dispatch throw, the quiescence cap.
+ *
+ * Rejections are typed, never silent:
+ *   - `DriveFailedError<S>` when `opts.failed` marks the final State — the State
+ *     rides on `error.state`.
+ *   - `DriveStalledError<S>` when `start`'s follow-up chain quiesces on a State
+ *     that is neither terminal nor `failed` and the runtime has no live Sub and
+ *     no Cmd in flight — nothing inside it can deliver another transition, so
+ *     waiting would be a hang with the runtime leaked. The stalled State rides
+ *     on `error.state`. A machine that CAN still move is not stalled: a live Sub
+ *     (manual or dep-keyed) that delivers the terminal Msg after the dispatch
+ *     quiesces keeps the drive waiting, and it resolves on that State. What the
+ *     runtime cannot see — a dispatch from outside it after quiescence — does
+ *     not count as live; a machine that depends on one declares it as a Sub.
+ *   - `QuiescenceTimeoutError` when `start`'s follow-up chain never settles —
+ *     the SAME cap `dispatch` and `idle()` already reject on (invariant 6), not a
+ *     second clock. A livelocking machine surfaces as its own failure class.
+ *   - the boot error, or whatever `dispatch(start)` rejects with, otherwise.
+ *
+ * `isTerminal` is caller-supplied, exactly as `run()`'s `terminal` option is —
+ * the kernel has no built-in terminal-set concept and this does not add one.
+ *
+ * Cancellation is the same story: `{ signal, cancel }` stops the drive from
+ * outside, and it settles the run rather than escaping it. On abort the drive
+ * dispatches `cancel`'s Msg and RESOLVES on the terminal State that transition
+ * lands — no rejection, no `DriveFailedError`, no `AbortError`. That is the whole
+ * point of routing a stop through the Model: the outcome is durable, so a killed
+ * process resumes reading a run that ended instead of restarting one someone
+ * stopped. A cancel that THROWS is the one abort that rejects: it lands
+ * no State, so its error is what the drive has to report — and that holds
+ * whether the `cancel` function throws synchronously or the fold it produced
+ * throws later, since both leave the run with no State to settle on. A State the
+ * caller's `failed` predicate marks rejects on an abort exit exactly as it does
+ * anywhere else. In-flight effects are not recalled — a promise cannot be cancelled —
+ * so they settle to their own end and `stop()` drains them as it always did;
+ * keeping their results off the public channels is the machine's own business.
+ * Omit the pair and every path here behaves exactly as it did before.
+ *
+ * @param handle     the handle `run(machine, opts)` returned.
+ * @param start      the Msg that sets the run in motion, or a function choosing
+ *                   it off the boot State. PURE.
+ * @param isTerminal the terminal predicate over the machine's State. PURE.
+ * @param opts       an optional `failed` predicate and an optional
+ *                   `{ signal, cancel }` pair (see {@link DriveToDoneOptions}).
+ */
+declare function driveToDone<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never>(handle: BootingRuntime<S, M, E>, start: M | ((booted: S) => M), isTerminal: (state: S) => boolean, opts?: DriveToDoneOptions<S, M>): Promise<S>;
+
+/**
+ * The imperative listener target, expressed as the `add`/`remove` pair the
+ * substrate pairs into a reconciled resource. Both halves receive the SAME
+ * `listener` reference — the substrate builds it once — so `remove` can never
+ * be handed a different function than `add` saw.
+ *
+ * `add`/`remove` also receive `(sub, ctx)` so the target may be resolved from
+ * `ctx` (a runtime, a port, a DOM node looked up lazily) or keyed on the Sub
+ * (an alarm name, a channel name). Resolving the target inside `add` and
+ * closing over nothing but the listener keeps a target swap from leaking the
+ * old target's listener — same rationale as `fromEventTarget`'s captured
+ * target.
+ *
+ * `Args` is the tuple the platform invokes the listener with — `[Alarm]` for
+ * `chrome.alarms.onAlarm`, `[message, sender, sendResponse]` for
+ * `chrome.runtime.onMessage`, `[changes, areaName]` for
+ * `chrome.storage.onChanged`. The substrate builds ONE function of this exact
+ * shape and threads the IDENTICAL reference to both `add` and `remove` — so a
+ * platform that matches `removeListener` by reference (every chrome surface)
+ * removes exactly what it added. A consumer that wrapped the listener inside
+ * `add` would break reference identity (leak #2 above); carrying the native
+ * `Args` on the listener itself removes the need for any wrapper.
+ */
+interface ListenerTarget<Args extends readonly unknown[], S extends Sub, Ctx> {
+    add: (listener: (...args: Args) => void, sub: S, ctx: Ctx) => void;
+    remove: (listener: (...args: Args) => void, sub: S, ctx: Ctx) => void;
+}
+/**
+ * Build a listener-backed Sub factory whose cleanup is mandatory and derived.
+ *
+ * `Args`, `S`, `Ctx` are fixed when the target is defined — they describe the
+ * one listener topology this factory owns (the platform arg tuple, which Sub
+ * shape it filters on, what context resolves it). `M` is supplied at the
+ * subscribe cell because the same listener feeds different Msgs in different
+ * machines. Pinning `S` here (rather than at the `msgFn` step) lets
+ * `add`/`remove` read the concrete Sub's fields — `sub.alarmName`,
+ * `sub.channel` — with NO cast at the substrate edge: the narrowing happens in
+ * author-land where the Sub shape is in scope.
+ *
+ * The returned function is a `SubscribeHandler` factory in the exact shape of
+ * every other Sub factory in `src/subs/`: supply the `msgFn` projection, get a
+ * `(sub, ctx, dispatch) => cleanup` handler assignable to `machine.subscribe`.
+ * The cleanup the author NEVER writes is `() => remove(listener, sub, ctx)`,
+ * with `listener` the identical reference passed to `add`.
+ */
+declare function defineListener<Args extends readonly unknown[], S extends Sub = Sub, Ctx = unknown>(target: ListenerTarget<Args, S, Ctx>): <M>(msgFn: (sub: S, ...args: Args) => M | null) => SubscribeHandler<S, M, Ctx>;
+
+interface MinimalEvent {
+    readonly type: string;
+}
+interface MinimalMessageEvent extends MinimalEvent {
+    readonly data: unknown;
+}
+interface MinimalEventTarget {
+    addEventListener(type: string, listener: (event: MinimalEvent) => void): void;
+    removeEventListener(type: string, listener: (event: MinimalEvent) => void): void;
+}
+interface MinimalCloseEvent extends MinimalEvent {
+    readonly code: number;
+    readonly reason: string;
+}
+interface MinimalWebSocket {
+    close(code?: number, reason?: string): void;
+    onopen: ((event: MinimalEvent) => void) | null;
+    onmessage: ((event: MinimalMessageEvent) => void) | null;
+    onerror: ((event: MinimalEvent) => void) | null;
+    onclose: ((event: MinimalCloseEvent) => void) | null;
+}
+
+type BroadcastSubData = {
+    channelName: string;
+};
+declare function fromBroadcastChannel<S extends Sub & BroadcastSubData, M>(msgFn: (event: MinimalMessageEvent, sub: S) => M | null): SubscribeHandler<S, M, unknown>;
+
+type EventSourceSubData = {
+    url: string;
+};
+interface EventSourceFactoryOpts<S, M> {
+    onMessage: (data: string, sub: S) => M | null;
+    onError?: (event: MinimalEvent, sub: S) => M | null;
+    onOpen?: (sub: S) => M | null;
+}
+declare function fromEventSource<S extends Sub & EventSourceSubData, M>(opts: EventSourceFactoryOpts<S, M>): SubscribeHandler<S, M, unknown>;
+
+declare function fromEventTarget<S extends Sub, M>(getTarget: () => MinimalEventTarget, eventName: string, msgFn: (event: MinimalEvent, sub: S) => M | null): SubscribeHandler<S, M, unknown>;
+
+type IntervalSubData = {
+    intervalMs: number;
+};
+declare function fromInterval<S extends Sub & IntervalSubData, M>(msgFn: (sub: S) => M): SubscribeHandler<S, M, unknown>;
+
+declare function fromPort<S extends Sub, M, Ctx, T, RS = unknown, RM extends {
+    type: string;
+} = {
+    type: string;
+}>(selectRuntime: (ctx: Ctx) => Runtime<RS, RM>, port: Port<T>, msgFn: (value: T, sub: S) => M | null): SubscribeHandler<S, M, Ctx>;
+
+type WebSocketSubData = {
+    wsUrl: string;
+};
+interface WebSocketFactoryOpts<S, M> {
+    onMessage: (data: unknown, sub: S) => M | null;
+    onOpen?: (sub: S) => M | null;
+    onError?: (event: MinimalEvent, sub: S) => M | null;
+    onClose?: (code: number, reason: string, sub: S) => M | null;
+}
+declare function fromWebSocket<S extends Sub & WebSocketSubData, M>(opts: WebSocketFactoryOpts<S, M>): SubscribeHandler<S, M, unknown>;
+
+/** Cancels a scheduled reconnect timer (the inverse of `schedule`). */
+type CancelTimer = () => void;
+interface ReconnectingWebSocketFactoryOpts<S, M> {
+    onMessage: (data: unknown, sub: S) => M | null;
+    onOpen?: (sub: S) => M | null;
+    onError?: (event: MinimalEvent, sub: S) => M | null;
+    onClose?: (code: number, reason: string, sub: S) => M | null;
+    /**
+     * Fires when a reconnection (any open after the first) succeeds, carrying the
+     * 1-based reconnect count — the resync hook. Omitting drops reconnect events
+     * silently.
+     */
+    onReconnect?: (attempt: number, sub: S) => M | null;
+    /** First backoff delay in ms (doubles each failed attempt). Default 250. */
+    backoffBaseMs?: number;
+    /** Backoff ceiling in ms. Default 5000. */
+    backoffMaxMs?: number;
+    /** Inject the socket constructor (defaults to the global `WebSocket`); the test seam. */
+    connect?: (url: string) => MinimalWebSocket;
+    /** Inject the timer (defaults to `setTimeout`/`clearTimeout`); the test seam. */
+    schedule?: (fn: () => void, ms: number) => CancelTimer;
+}
+declare function fromReconnectingWebSocket<S extends Sub & WebSocketSubData, M>(opts: ReconnectingWebSocketFactoryOpts<S, M>): SubscribeHandler<S, M, unknown>;
+
+type TimeoutSubData = {
+    delayMs: number;
+};
+declare function fromTimeout<S extends Sub & TimeoutSubData, M>(msgFn: (sub: S) => M): SubscribeHandler<S, M, unknown>;
+
+/**
+ * The Sub the battery builds. The consumer's `Sub` union includes
+ * `ManagedResourceSub<TKey>` directly — the substrate reconciles by `id` and
+ * `type` like any other Sub.
+ */
+interface ManagedResourceSub<TKey> extends Sub<"managed_resource"> {
+    /** The lifetime key. Stable while the resource should be held; a change
+     *  retires the old resource (release) and acquires a fresh one. */
+    readonly key: TKey;
+}
+/**
+ * A battery paired with a state-gate. Self-contained: it knows its `name`
+ * (for the unique-name assert), how to derive its live Sub from a state
+ * (`subFor`), how to handle its own `subscribe`, and whether it `owns` a given
+ * Sub id.
+ *
+ * Generic in the consumer state `S`, the shared lifetime key `TKey`, and the
+ * shared `Ctx`. `Handle` is the ONLY thing erased — each battery's handle type
+ * differs (a checkpoint saver vs. a tool-call bridge) but never crosses this
+ * interface, so a `combineManagedResources` array holds entries of
+ * heterogeneous handle types with no cast. The sub type stays
+ * `ManagedResourceSub<TKey>` end to end, so the substrate's narrowed Sub flows
+ * straight in.
+ */
+interface GatedManagedResource<S, TKey, Ctx> {
+    /** The owning battery's `name`. The combinator asserts these are unique. */
+    readonly name: string;
+    /**
+     * Derive this resource's live Sub for a given state: the battery's
+     * `.sub(key)` when `when(state)` returns a key, or `null` when it returns
+     * `null` (the resource should be torn down in that state).
+     */
+    readonly subFor: (state: S) => ManagedResourceSub<TKey> | null;
+    /**
+     * This battery's own `.subscribe`. The combinator routes an incoming
+     * `managed_resource` Sub to the entry whose `owns(sub)` is true, then calls
+     * this.
+     */
+    readonly subscribe: (sub: ManagedResourceSub<TKey>, ctx: Ctx, dispatch: (msg: never) => void) => Dispose;
+    /**
+     * Does this entry own the given Sub? `sub.id === subIdFor(sub.key)` encodes
+     * the battery `name`, so a match is unambiguous.
+     */
+    readonly owns: (sub: ManagedResourceSub<TKey>) => boolean;
+}
+/**
+ * What `combineManagedResources` returns: the single managed-resource
+ * `subscribe` handler for the machine's `subscribe` record, and a `subs(state)`
+ * builder for `subscriptions(state)`.
+ */
+interface CombinedManagedResources<S, TKey, Ctx> {
+    /**
+     * Map every entry through its `when(state)`, drop the `null`s, and build the
+     * live Subs. Spread into `subscriptions(state)`. The derived list and the
+     * `subscribe` routing share one source — the entries — so they never drift.
+     */
+    readonly subs: (state: S) => ManagedResourceSub<TKey>[];
+    /**
+     * The SINGLE `subscribe.managed_resource` handler. Routes an incoming Sub to
+     * the owning battery by matching `sub.id === battery.subIdFor(sub.key)` (the
+     * id encodes the battery `name`). Throws loudly on an unrouted id — a wiring
+     * bug, never a silent no-op resource.
+     */
+    readonly subscribe: (sub: ManagedResourceSub<TKey>, ctx: Ctx, dispatch: (msg: never) => void) => Dispose;
+}
+interface DefineManagedResourceOpts<TKey, Handle, Ctx> {
+    /**
+     * A short, stable name. The Sub id is `managed:${name}:${stringify(key)}`,
+     * so two managed resources in one machine never collide and neither
+     * collides with a `fromTransport` Sub keyed on the same identity.
+     */
+    readonly name: string;
+    /**
+     * Build the resource. Runs when the Sub appears in `subscriptions(state)`.
+     * The returned Handle is the ONLY thing `release` receives — capture
+     * everything teardown needs into it. If `acquire` throws, the substrate's
+     * reconcile does NOT register the Sub and `release` is never called (no
+     * dangling half-built resource).
+     */
+    readonly acquire: (key: TKey, ctx: Ctx) => Handle;
+    /**
+     * Tear the resource down. Runs when the Sub leaves the desired set (phase
+     * exited) or when its key changes. MANDATORY — the guaranteed teardown is
+     * the reason this battery exists.
+     *
+     * May be sync or async, and an async one is really awaited: the promise is
+     * returned to the substrate, which tracks it and drains it inside `stop()`
+     * (bounded by `run({ disposeTimeoutMs })`). So `await runtime.stop()` means
+     * the release finished — the reading a host evicting an isolate acts on.
+     * MID-RUN teardown (a phase exit, a key change) is still fire-and-forget
+     * (Rule 2): the reconcile pass is synchronous by construction, so it starts
+     * the release and moves on. A rejection is never a Msg — it reaches the
+     * runtime's `onError` sink under `phase: "sub-cleanup"`.
+     */
+    readonly release: (handle: Handle) => void | Promise<void>;
+}
+/**
+ * What the battery returns: a `.sub(key)` builder for `subscriptions`, the
+ * `.subscribe` handler for the machine's `subscribe` record, a `.get(key)`
+ * accessor so Cmd handlers can reach the live Handle while the resource is
+ * held, and a `.subIdFor(key)` for tests.
+ */
+interface ManagedResourceBattery<TKey, Handle, Ctx> {
+    /**
+     * Build the Sub for `subscriptions(state)`. The consumer calls this from
+     * inside their `subscriptions` cell for the phases where the resource
+     * should be live.
+     */
+    readonly sub: (key: TKey) => ManagedResourceSub<TKey>;
+    /**
+     * Pair this battery with a state-gate, producing a self-contained entry for
+     * `combineManagedResources`. `when(state)` returns the resource's KEY when
+     * it should be live in that state, or `null` when it should be torn down.
+     *
+     * Folding "is it active?" and "what key?" into ONE declaration at the
+     * battery's own definition site is the point: a central `subscriptions(state)`
+     * list can silently forget to gate a new phase, but a per-resource gate
+     * travels with the resource. The combinator derives BOTH the active-sub list
+     * and the subscribe routing from these entries, so the two can never disagree.
+     *
+     * Generic in the consumer's state `S` (each `.gated` call binds its own `S`).
+     * The returned entry erases this battery's `Handle` — `combineManagedResources`
+     * holds entries of heterogeneous handle types with no cast — while keeping
+     * `TKey` and `Ctx` so the substrate's narrowed `ManagedResourceSub<TKey>`
+     * flows straight into the entry's `subscribe`.
+     */
+    readonly gated: <S>(when: (state: S) => TKey | null) => GatedManagedResource<S, TKey, Ctx>;
+    /**
+     * Dep-keyed entry for the machine's `subs` array. `when(state)` returns the
+     * resource's KEY when it should be held, or `null` when it should be torn
+     * down — the exact gate `.gated` takes, now producing a `DepKeyedSub` the
+     * kernel folds directly instead of an entry the `combineManagedResources`
+     * router multiplexes.
+     *
+     * This is the simplification the dep-keyed kernel unlocks: two managed
+     * resources used to COLLIDE on the single `subscribe.managed_resource` key
+     * (both subs share `type: "managed_resource"`), forcing
+     * `combineManagedResources` to route by SubId. A dep-keyed Sub has its OWN
+     * reconcile slot (its array position), so there is no shared `type` to route
+     * — each resource is one `subs` entry, no combinator, no router. `acquire` /
+     * `release` still ride the kernel's dispose-on-change / dispose-on-null
+     * reconcile, now via the dep-keyed source's `Dispose` instead of the
+     * `subscribe` cell's cleanup.
+     */
+    readonly depKeyed: <S>(when: (state: S) => TKey | null) => DepKeyedSub<S, never, Ctx>;
+    /**
+     * The `subscribe.managed_resource` handler. Drop straight into the
+     * machine's `subscribe` record. Runs `acquire` on install, holds the
+     * Handle in the battery's handle table, and returns a cleanup that runs
+     * `release` (and forgets the Handle) on reconcile-out.
+     */
+    readonly subscribe: (sub: ManagedResourceSub<TKey>, ctx: Ctx, dispatch: (msg: never) => void) => Dispose;
+    /**
+     * Accessor for the live Handle, keyed on `key`. Returns `undefined` when
+     * the resource is not currently held (no active sub for that key) — the
+     * caller decides whether that is an error. A Cmd handler wires its
+     * `ctx.getX(key)` through this, so the handler reads the SAME owner the
+     * reconciler holds, never a hand-built duplicate.
+     */
+    readonly get: (key: TKey) => Handle | undefined;
+    /** Pre-derived subId for `(key)` — handy for tests. */
+    readonly subIdFor: (key: TKey) => SubId;
+}
+/**
+ * Build the battery. One call per managed resource at the machine's host
+ * file.
+ *
+ * @example
+ *   const checkpointStore = defineManagedResource<RunId, CheckpointSaver, Ctx>({
+ *     name: "checkpoint",
+ *     acquire: (runId, ctx) =>
+ *       new CheckpointSaver({ storage: ctx.storage, bucket: ctx.bucket, runId }),
+ *     release: (saver) => saver.clear(),
+ *   });
+ *
+ *   // In the machine:
+ *   subscriptions: (state) =>
+ *     state.type === "running" ? [checkpointStore.sub(state.runId)] : [],
+ *   subscribe: { managed_resource: checkpointStore.subscribe },
+ *
+ *   // In interpret (read the live handle the reconciler holds):
+ *   start_graph: async (cmd, ctx) => {
+ *     const saver = checkpointStore.get(cmd.runId);  // same owner, no rebuild
+ *     ...
+ *   }
+ */
+declare function defineManagedResource<TKey, Handle, Ctx>(opts: DefineManagedResourceOpts<TKey, Handle, Ctx>): ManagedResourceBattery<TKey, Handle, Ctx>;
+declare function combineManagedResources<S, TKey, Ctx>(entries: readonly GatedManagedResource<S, TKey, Ctx>[]): CombinedManagedResources<S, TKey, Ctx>;
+
+/**
+ * Duplex transport. The host (DO, worker thread, in-process bus) constructs
+ * one from whatever the platform offers. `fromTransport` does not know what
+ * a WebSocket is — it knows `send`, `onMessage`, `onClose`.
+ */
+interface Transport {
+    /** Send a string frame. Best-effort; failures are logged at the boundary. */
+    send(data: string): void;
+    /**
+     * Subscribe to inbound frames. Returns a cleanup that removes the listener.
+     * The battery wires this in its Sub's subscribe handler; cleanup runs when
+     * the phase exits (the substrate's reconcileSubs).
+     */
+    onMessage(listener: (data: string) => void): () => void;
+    /**
+     * Subscribe to a one-shot close. Returns a cleanup that removes the
+     * listener. The battery dispatches `lostMsg` on close.
+     */
+    onClose(listener: () => void): () => void;
+    /** Close the underlying channel cleanly. Called by the Sub cleanup. */
+    close(): void;
+}
+/**
+ * Factory the consumer wires to a platform-specific transport. The battery
+ * passes the runtime-derived key (`runId`, or whatever identity is on the
+ * phase) so per-run transports can be addressed.
+ */
+type TransportFactory<K> = (key: K) => Transport;
+/**
+ * The Sub the battery builds. The consumer's `Sub` union includes
+ * `TransportSub<TKey>` directly — no wrapping needed, the substrate
+ * reconciles by `id` and `type` like any other Sub.
+ */
+interface TransportSub<TKey> extends Sub<"transport"> {
+    /** The phase / run identity. Stable for the lifetime of the seam. */
+    readonly key: TKey;
+}
+interface FromTransportOpts<TKey, Inbound, Outbound, M, Ctx> {
+    /**
+     * A short, stable name for this seam. The Sub id is derived from
+     * `${name}:${stringify(key)}` so two seams in the same machine (e.g.
+     * `hands` + `worker`) never collide.
+     */
+    readonly name: string;
+    /**
+     * Build the transport. The battery owns the lifetime; the factory is the
+     * platform-specific constructor (`new WebSocket(...)` adapter on a DO,
+     * `MessagePort` adapter in a worker, in-memory stub in tests).
+     */
+    readonly openTransport: (key: TKey, ctx: Ctx) => Transport;
+    /**
+     * Parse one inbound frame. The battery hands `unknown` through (boundary
+     * parse is the consumer's responsibility per invariant 8). Returning
+     * `null` drops the frame silently — useful for frames the seam doesn't
+     * recognize at this layer (e.g. transport-level keepalive).
+     */
+    readonly parseInbound: (raw: string, key: TKey) => Inbound | null;
+    /**
+     * Map a parsed inbound to a domain Msg. Returning `null` drops the
+     * dispatch (e.g. a transport-level pong that doesn't change domain state).
+     */
+    readonly onInbound: (inbound: Inbound, key: TKey) => M | null;
+    /**
+     * The Msg dispatched when the transport closes (peer gone, network
+     * dropped, normal close). ONE Msg arm, not a Sub, not a heartbeat-derived
+     * deadline — the transport's own close signal is the truth.
+     */
+    readonly lostMsg: (key: TKey) => M;
+    /**
+     * Serialize an outbound. Called by the Cmd handler the battery wires.
+     * Pure data → string at the seam boundary.
+     */
+    readonly serializeOutbound: (outbound: Outbound) => string;
+}
+/**
+ * What the battery returns: a Sub builder (for `subscriptions`), the Sub's
+ * `subscribe` handler (for `subscribe.transport`), and a `send(key, outbound)`
+ * helper the consumer's Cmd handler calls. Plus a `subIdFor` factory the
+ * consumer can use when keying related Subs (e.g. a deadline) to the same seam
+ * identity.
+ */
+interface TransportBattery<TKey, Outbound, M, Ctx> {
+    /**
+     * Build the Sub for `subscriptions(state)`. The consumer calls this from
+     * inside their `subscriptions` cell when the seam should be open.
+     */
+    readonly sub: (key: TKey) => TransportSub<TKey>;
+    /**
+     * The `subscribe.transport` handler. Drop straight into the machine's
+     * `subscribe` record — the battery wires inbound + close in one shot.
+     */
+    readonly subscribe: (sub: TransportSub<TKey>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
+    /**
+     * Outbound send. The Cmd handler calls this; the battery's handle table
+     * (built when subscribe ran) routes to the live transport. If the seam
+     * is closed (no active sub), the send is dropped honestly (logged, not
+     * thrown — the reducer already moved past caring, same shape as Rule 2
+     * fire-and-forget Cmds).
+     */
+    readonly send: (key: TKey, outbound: Outbound) => void;
+    /** Pre-derived subId for `(key)` — handy for deadline Subs keyed to the same seam. */
+    readonly subIdFor: (key: TKey) => SubId;
+    /**
+     * Pair this seam with a state-gate, producing a dep-keyed Sub for the
+     * machine's `subs` array. `when(state)` returns the seam's KEY when it
+     * should be open, or `null` when it should be torn down. The kernel derives
+     * the id from `structuralHash(key)` and reconciles the seam's lifetime — so
+     * the author neither lists this Sub in a central `subscriptions(state)` nor
+     * writes its id. Replaces `subscriptions: (s) => active(s) ? [hands.sub(...)] : []`
+     * + `subscribe: { transport: hands.subscribe }` with one `subs` entry.
+     *
+     * The `source` closes over the battery's own `subscribe` (open inbound +
+     * close, wire the handle table) using the same `ctx` the kernel passes every
+     * Sub source.
+     */
+    readonly depKeyed: <S>(when: (state: S) => TKey | null) => DepKeyedSub<S, M, Ctx>;
+}
+/**
+ * Build the battery. One call per seam at the machine's host file.
+ *
+ * @example
+ *   const handsSeam = fromTransport<RunId, HandsInbound, HandsOutbound, Msg, Ctx>({
+ *     name: "hands",
+ *     openTransport: (runId, ctx) => ctx.openHandsWs(runId),
+ *     parseInbound: (raw) => parseHandsInbound(JSON.parse(raw)),
+ *     onInbound: (inbound, runId) => ({ type: "hands_said", runId, inbound }),
+ *     lostMsg: (runId) => ({ type: "hands_lost", runId }),
+ *     serializeOutbound: (out) => JSON.stringify(out),
+ *   });
+ *
+ *   // In the machine:
+ *   subscriptions: (state) => state.type === "auditing" ? [handsSeam.sub(state.runId)] : [],
+ *   subscribe: { transport: handsSeam.subscribe },
+ *
+ *   // In interpret:
+ *   send_hands: async (cmd) => { handsSeam.send(cmd.runId, cmd.outbound); },
+ */
+declare function fromTransport<TKey, Inbound, Outbound, M, Ctx>(opts: FromTransportOpts<TKey, Inbound, Outbound, M, Ctx>): TransportBattery<TKey, Outbound, M, Ctx>;
 
-export { BootingRuntime, Cmd, CtxArg, type HistoryTracker, Machine, OnError, RequiredCtx, Store, Sub, Supervision, historyTracker, run };
+export { type Ack, type AckPartition, BootingRuntime, type CancelTimer, Cmd, type CombinedManagedResources, type DefineManagedResourceOpts, DepKeyedSub, Dispose, type DriveToDoneOptions, type EventSourceFactoryOpts, type FromTransportOpts, type GatedManagedResource, type HistoryTracker, type ListenerTarget, Machine, type ManagedResourceBattery, type ManagedResourceSub, NO_ACK, OnError, Port, type ReadStep, type ReconnectingWebSocketFactoryOpts, RequiredCtx, Runtime, ScopedCtxArg, type Seq, type SeqTagged, Store, Sub, SubId, SubscribeHandler, Supervision, type Transport, type TransportBattery, type TransportFactory, type TransportSub, type WebSocketFactoryOpts, type WebSocketSubData, ack, combineManagedResources, defineListener, defineManagedResource, driveToDone, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromTimeout, fromTransport, fromWebSocket, historyTracker, initAck, liftSlice, nextSeq, partitionByAck, readInOrder, reconcile, run, tagSeq };