@demlik/tea 0.1.0 → 0.1.2

package/dist/do/index.d.ts

@@ -1,9 +1,1676 @@
-import { Store, SubId, Sub } from '../index.js';
+import { Store, Runtime, BootingRuntime } from '../index.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-CO9Uh971.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-CO9Uh971.js';
+import { RetryPolicy, Rng } from '../retry-backoff/index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
+import { AgentTurn, AgentState, AgentMachineMsg, AgentEvent, AgentStatus } from '../agent/index.js';
+import '../fan-out/index.js';
+import '../work-queue/index.js';
+import '../llm-call/index.js';
+import '../resilient-call/index.js';
+import '../cache/index.js';
+import '../types-B-8bcAp8.js';
+import '../circuit-breaker/index.js';
+import '../deadline/index.js';
+import '../protocol-B5YmJr0d.js';
+import '../rate-limit/index.js';
+import '../monitored-run/index.js';
+import '../snapshot/index.js';
+
+/**
+ * @demlik/tea/do — `stepHost`, the HTTP-PULL control carrier (#92).
+ *
+ * ## Carrier selection — pick by WHO INITIATES the message
+ *
+ * `stepHost` is a SIBLING to {@link acceptCommandSocket}, never a replacement.
+ * Both carriers commonly run together in ONE Durable Object; choose between
+ * them per *plane*, by who sends the next message:
+ *
+ *   - **Pull (this file — `stepHost` over `/step`)** — the CONTROL plane. One
+ *     driver (the hands) initiates every message: it asks for the next tool,
+ *     runs it, posts the result, asks again. There is exactly one outstanding
+ *     question at a time and the DO is COLD between steps — nothing is owed
+ *     while no request is in flight. Hibernation is the resting state, not a
+ *     failure: each POST wakes the DO, advances the run one step from its
+ *     durable checkpoint, and lets it hibernate again.
+ *   - **Push (`acceptCommandSocket` / `sseHub` — WS + SSE)** — the VIEW /
+ *     fan-out plane. The DO initiates UNSOLICITED messages: broadcast a frame
+ *     to every connected client, stream a live dashboard, push an event no
+ *     client asked for. A long-lived socket is the right carrier because the
+ *     sender is the DO, not a polling client.
+ *
+ * The rule in one line: **pull when the client drives a cold-between-steps
+ * control loop; push when the DO drives unsolicited fan-out.** A hibernating
+ * agent whose only traffic is "run the next tool" wants pull — that is the case
+ * Binclusive #1812 / #1814 adopted this carrier for.
+ *
+ * ## Why pull is hibernation-correct
+ *
+ * The WS push carrier keeps a socket open across steps; if the DO evicts, the
+ * socket dies (or, with #91's `acceptDurableCommandSocket`, survives but still
+ * holds an in-flight round-trip the heap forgot). The pull carrier holds NO
+ * cross-step state in the heap. Every `/step` POST is a FRESH request that:
+ *
+ *   1. **validates** the per-run capability token (constant-time compare),
+ *   2. **re-arms** the eviction-safe give-up alarm via `ctx.storage.setAlarm`
+ *      (the DO-native alarm API — the `do_alarm` Sub was dropped, see the
+ *      `host.ts` header; the alarm is a host concern, not a machine Sub),
+ *   3. **settles** the posted tool result IDEMPOTENTLY through
+ *      `idempotent-intake` — a re-POSTed result is absorbed exactly once and
+ *      the duplicate replays the same next step,
+ *   4. **resumes** the run from its durable checkpoint (the #68 event-sourced
+ *      store / #91 in-flight ledger) by dispatching the settle and running to
+ *      DISPATCH-QUIESCENCE,
+ *   5. **returns** the next step (the next tool call) — or the terminal output
+ *      read off `runtime.result()` — and lets the DO HIBERNATE.
+ *
+ * No warm loop is held between responses. The durable checkpoint IS the loop's
+ * continuation; the heap is disposable.
+ *
+ * ## It is ASSEMBLY over bricks tea already ships
+ *
+ *   - `idempotent-intake` (`createIntake`) — the dedupe-by-key receive-once
+ *     settle. The posted result's `callId` is the idempotency key, so a
+ *     re-POST lands as a duplicate and replays the cached decision.
+ *   - `poller` primitives (`retry-backoff`) — the hands-side {@link runStepLoop}
+ *     pull loop: absolute deadline + backoff + dedupe-by-callId.
+ *   - the #68/#91 durable checkpoint — read by the consumer's `resume` callback
+ *     (it dispatches the settle into the runtime, whose `doEventSourcedStore`
+ *     rebuilt state from the log on this cold wake).
+ *
+ * This file owns NONE of those primitives — it wires them into the `/step`
+ * request/response contract and the token lifecycle.
+ */
+
+/**
+ * The tool result the hands POST back for the step they just executed. `callId`
+ * matches the step the previous response handed out (it is BOTH the correlation
+ * id and the idempotency key — a re-POST carries the same `callId` and is
+ * absorbed once). `result` is the opaque tool output `R`.
+ */
+interface StepResult<R> {
+    readonly callId: string;
+    readonly result: R;
+}
+/**
+ * A `/step` request. `token` is the per-run capability (validated
+ * constant-time). `runId` names the run. `posted` is the result of the
+ * previously-returned step, or `null` on the FIRST request (no step has been
+ * handed out yet, so there is nothing to settle).
+ */
+interface StepRequest<R> {
+    readonly token: string;
+    readonly runId: string;
+    readonly posted: StepResult<R> | null;
+}
+/**
+ * The next tool call to execute — the "continue" arm of a `/step` response.
+ * `callId` is the correlation/idempotency id the hands echo back in the next
+ * request's `posted`. `tool` + `input` describe the call (opaque to the host).
+ */
+interface NextStep<I> {
+    readonly callId: string;
+    readonly tool: string;
+    readonly input: I;
+}
+/**
+ * A `/step` response — a discriminated union on `done`:
+ *   - `{ done: false, step }` — execute `step`, POST its result, ask again.
+ *   - `{ done: true, output }` — the run is terminal; `output` is its result.
+ */
+type StepResponse<I, O> = {
+    readonly done: false;
+    readonly step: NextStep<I>;
+} | {
+    readonly done: true;
+    readonly output: O;
+};
+/**
+ * Mint a fresh per-run capability token: 32 random bytes, hex-encoded. Uses the
+ * Web Crypto `crypto.getRandomValues` available in the Workers runtime (and in
+ * Node's test runtime via the global `crypto`). Persist the returned string in
+ * DO storage keyed by runId; hand the SAME string to the hands once, at run
+ * start.
+ */
+declare function mintRunToken(randomBytes?: (n: number) => Uint8Array): string;
+/**
+ * Constant-time string equality. Returns `true` iff `a` and `b` are
+ * byte-for-byte equal, in time that depends ONLY on `a.length` — never on WHERE
+ * the first mismatch is. A length mismatch still returns `false`, but the
+ * comparison loop always runs `a.length` iterations against a same-length view,
+ * so the early-exit timing oracle a naive `===` leaks is closed.
+ *
+ * The XOR-accumulate idiom: fold every position's difference into one
+ * accumulator and test it once at the end. No `break`, no short-circuit.
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * The DO-native alarm slice `stepHost` re-arms. A real `DurableObjectStorage`
+ * satisfies this structurally; a test supplies a fake (no live Workers runtime).
+ * Only `setAlarm` is needed — the give-up deadline is re-armed on every step so
+ * a run abandoned mid-loop (the hands stop POSTing) is eventually evicted by the
+ * alarm firing, not left resident forever.
+ */
+interface AlarmStorage {
+    setAlarm(scheduledTime: number): void | Promise<void>;
+}
+/** The minimal `ctx` slice `stepHost` reads — just the alarm-bearing storage. */
+interface StepCtx {
+    readonly storage: AlarmStorage;
+}
+/**
+ * The run-specific operations `stepHost` orchestrates. The consumer implements
+ * these against its runtime + storage; `stepHost` never reaches into the agent
+ * machine itself (that lives in `../agent`, off-limits to this carrier).
+ */
+interface StepEngine<R, I, O> {
+    /**
+     * The persisted capability token for `runId`, or `null` if the run is
+     * unknown. Read from DO storage. `stepHost` compares the request token
+     * against this constant-time.
+     */
+    tokenFor(runId: string): Promise<string | null> | string | null;
+    /**
+     * Settle the posted tool result into the run, then RESUME from the durable
+     * checkpoint: dispatch the settle and run to DISPATCH-QUIESCENCE (e.g.
+     * `await runtime.dispatch(settleMsg)` — dispatch drains the follow-up chain
+     * by default, #50). Called at most once per distinct
+     * `callId` — `stepHost` dedupes re-POSTs via `idempotent-intake` BEFORE
+     * calling this, so the side effect runs exactly once. On the first request
+     * (`posted === null`) `stepHost` skips settle and calls {@link nextStep}
+     * directly to hand out the first step.
+     */
+    resume(runId: string, posted: StepResult<R>): Promise<void> | void;
+    /**
+     * Read the next step the run is now waiting on — the next tool call — off the
+     * resumed runtime's durable state, or `null` if the run has reached its
+     * terminal State (then {@link terminalOutput} supplies the output).
+     */
+    nextStep(runId: string): Promise<NextStep<I> | null> | NextStep<I> | null;
+    /**
+     * Read the run's terminal output (off `runtime.result()`). Only called when
+     * {@link nextStep} returned `null`.
+     */
+    terminalOutput(runId: string): Promise<O> | O;
+}
+/** Tuning for `stepHost`'s give-up alarm. */
+interface StepHostConfig {
+    /**
+     * How far ahead, in ms, to re-arm the give-up alarm on every step. A run that
+     * stops POSTing for longer than this is abandoned and the alarm fires (the
+     * consumer's `alarm()` handler tears the run down). Defaults to 5 minutes.
+     */
+    readonly giveUpAfterMs?: number;
+}
+/**
+ * A structured `/step` outcome `stepHost` returns — the response body plus the
+ * HTTP status the consumer's route should send. Kept transport-agnostic (no
+ * `Response`) so the same handler is unit-testable without a live `fetch`.
+ */
+type StepOutcome<I, O> = {
+    readonly status: 200;
+    readonly body: StepResponse<I, O>;
+} | {
+    readonly status: 401 | 404;
+    readonly body: {
+        readonly error: string;
+    };
+};
+/**
+ * Build the `/step` handler for a DO that drives one or more runs over the pull
+ * carrier. Returns `handle(request, now)` — call it from the DO's `/step`
+ * route, map the `StepOutcome` to a `Response`, and let the DO hibernate.
+ *
+ * The handler is STATELESS between calls except for its `idempotent-intake`
+ * dedupe ledger, which the consumer should itself persist alongside the run's
+ * checkpoint if cross-eviction dedupe of an identical re-POST is required; the
+ * in-isolate ledger here dedupes re-POSTs within one activation (the common
+ * "the hands' POST timed out and got retried" case), and the underlying
+ * `resume` is itself idempotent against the durable checkpoint, so a re-POST
+ * that crosses an eviction re-settles harmlessly.
+ *
+ * @param ctx    the DO state slice (alarm-bearing storage)
+ * @param engine the run-specific operations
+ * @param config alarm tuning
+ */
+declare function stepHost<R, I, O>(ctx: StepCtx, engine: StepEngine<R, I, O>, config?: StepHostConfig): {
+    handle(request: StepRequest<R>, now: number): Promise<StepOutcome<I, O>>;
+};
+/** The `/step` transport the hands POST through (injected; faked in tests). */
+type StepTransport<R, I, O> = (request: StepRequest<R>) => Promise<StepResponse<I, O>>;
+/** Execute one tool call and produce its result (the consumer's hands). */
+type ExecuteStep<I, R> = (step: NextStep<I>) => Promise<R> | R;
+/** Tuning for {@link runStepLoop}. */
+interface RunStepLoopConfig {
+    /**
+     * Absolute wall-clock deadline (ms epoch). The loop stops asking once `now()`
+     * reaches it, surfacing a `deadline_exceeded` outcome. Mirrors the poller's
+     * absolute-deadline contract (a resumed loop honors the SAME moment).
+     */
+    readonly deadlineMs: number;
+    /** Backoff policy for FAILED `/step` POSTs. Defaults to `defaultRetryPolicy`. */
+    readonly retry?: RetryPolicy;
+    /** Clock, injected for determinism. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** `(ms) => Promise` sleep, injected for determinism. Defaults to real sleep. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Backoff jitter RNG, injected for determinism. Defaults to `Math.random`. */
+    readonly rng?: Rng;
+}
+/** The terminal outcome of a full {@link runStepLoop} drive. */
+type StepLoopOutcome<O> = {
+    readonly kind: "done";
+    readonly output: O;
+} | {
+    readonly kind: "deadline_exceeded";
+} | {
+    readonly kind: "gave_up";
+    readonly error: unknown;
+};
+/**
+ * Drive the pull loop to completion. Starting from `{ posted: null }`, POST
+ * `/step`, and for each non-terminal response execute the step and POST its
+ * result, until the response is terminal (`done: true`) — then return its
+ * output.
+ *
+ * Resilience composed from `poller`'s primitives:
+ *   - **absolute deadline** — `config.deadlineMs`. Before each POST the loop
+ *     checks `now() >= deadlineMs` and stops with `deadline_exceeded` rather
+ *     than asking forever.
+ *   - **backoff** — a FAILED POST (transport reject) is retried on the
+ *     `retry-backoff` curve; once `shouldRetry` is exhausted the loop stops
+ *     with `gave_up`. A success resets the retry counter.
+ *   - **dedupe** — a step whose `callId` was already executed in THIS drive is
+ *     not re-executed; its prior result is re-POSTed. Closes the "the host
+ *     re-handed the same step after a duplicate settle" path (the host side is
+ *     idempotent; the hands match it).
+ */
+declare function runStepLoop<R, I, O>(token: string, runId: string, transport: StepTransport<R, I, O>, execute: ExecuteStep<I, R>, config: RunStepLoopConfig): Promise<StepLoopOutcome<O>>;
+
+/**
+ * `@demlik/tea/do` — the durable-timer / alarm-carrier port (#180).
+ *
+ * Every native-DO grain that wants a wall-clock tick hand-rolls the SAME
+ * eviction-safe pattern: compute the next absolute deadline off the live state,
+ * push it to `ctx.storage.setAlarm`, and — when the DO `alarm()` lifecycle hook
+ * fires — map that fire back to a Msg, then re-arm off the post-fire state. The
+ * `raft/do.ts` election/heartbeat deadline does it (`rearmAlarm` + `onAlarm`),
+ * and the vortex arena tick (`room.ts` `armTick` + `onTick`) replicates the
+ * exact shape for the 18 Hz game clock. The two old `do_alarm`/`do_ws` Subs were
+ * dropped (see `./index`'s historical note) because `toMachine` fixes the agent
+ * machine's Sub type to `DeadlineSub`, so they could never union into a grain's
+ * Sub set — leaving the alarm re-arm a HOST concern with no first-class home.
+ *
+ * {@link durableTimer} is that home: a tiny, transport- and Msg-agnostic helper
+ * that owns the three repeated responsibilities and nothing else —
+ *
+ *   1. **Compute-next-deadline → `setAlarm`.** {@link DurableTimer.rearm} calls
+ *      the injected {@link DurableTimerConfig.nextDeadline}, and arms the alarm
+ *      at the returned absolute epoch-ms target.
+ *   2. **Idle-when-no-work.** `nextDeadline` returns `null` when there is nothing
+ *      to schedule (an empty room, a node with no pending election/heartbeat),
+ *      and `rearm` then arms NOTHING — the DO is allowed to go idle / hibernate
+ *      instead of spinning the alarm forever. Re-arming is a positive act gated
+ *      on real work, never an unconditional reschedule.
+ *   3. **Fire → Msg → re-arm.** {@link DurableTimer.onAlarm} is the body the DO
+ *      `alarm()` hook calls: it runs the injected {@link DurableTimerConfig.onFire}
+ *      (the consumer dispatches its timer Msg there — a `Tick`, a re-derived
+ *      deadline Msg) and THEN re-arms off the now-advanced state. Re-arm always
+ *      follows the fire, so a still-active grain keeps ticking and an idle one
+ *      stops by construction.
+ *
+ * **Eviction-safe across hibernation.** A DO alarm is the one timer that
+ * survives eviction (an isolate `setInterval` dies the moment the isolate
+ * sleeps), so the same `durableTimer` re-armed on a cold wake resumes the
+ * schedule that a never-evicted instance would have held. The recovery contract
+ * is just: after the host rebuilds state (`store.load()` → `replay`), call
+ * {@link DurableTimer.rearm} once — it recomputes `nextDeadline` off the
+ * recovered state and re-arms (or idles) identically to the live path. The timer
+ * holds no in-memory schedule of its own; the deadline is always a pure function
+ * of the persisted state, which is what makes the cold-wake re-arm correct.
+ *
+ * **Dependency-injected / testable.** The alarm arrives as a {@link AlarmStorage}
+ * port — the SAME minimal `setAlarm` slice `stepHost` already takes (a real
+ * `DurableObjectStorage` satisfies it structurally; a test supplies a fake with
+ * no live Workers runtime), mirroring how `event-sourced-store.ts` takes its
+ * storage. `nextDeadline` and `onFire` are injected thunks, so the whole timer
+ * unit-tests with a faked alarm + a faked clock and no `cloudflare:workers`
+ * import. See `.patterns/tea-do/recovery.md` for the cold-wake replay contract
+ * the re-arm rides on.
+ */
+
+/**
+ * The construction inputs for {@link durableTimer} — the impure edges the grain
+ * injects, kept out of the pure reducer exactly like raft/do's
+ * `RaftGrainCtx`/room's `ArenaPorts`.
+ */
+interface DurableTimerConfig {
+    /**
+     * The DO alarm carrier. `setAlarm(atMs)` schedules the next fire at an
+     * absolute epoch-ms target. A real `DurableObjectStorage` satisfies this
+     * structurally; a test supplies a fake. Only `setAlarm` is read — never the
+     * whole `DurableObjectStorage`.
+     */
+    readonly alarm: AlarmStorage;
+    /**
+     * Compute the next absolute deadline (epoch ms) off the live state, or `null`
+     * when there is no work to schedule. Returning `null` is the idle signal:
+     * {@link DurableTimer.rearm} arms nothing and the DO is free to hibernate.
+     *
+     * Called fresh on every `rearm` (including the post-fire re-arm and the
+     * cold-wake re-arm), so it MUST read live state / the injected clock each call
+     * — that freshness is what keeps the schedule a pure function of the persisted
+     * state and the re-arm eviction-safe. Examples:
+     *   - raft: `node.subs(state, now())[0]?.atMs ?? null` (election XOR heartbeat).
+     *   - vortex: `connectionCount() > 0 ? now() + TICK_INTERVAL_MS : null`.
+     */
+    nextDeadline(): number | null | Promise<number | null>;
+    /**
+     * Run the timer's effect when the alarm fires — the consumer dispatches its
+     * timer Msg here (a `Tick`, a re-derived deadline Msg) and persists/broadcasts
+     * as its grain requires. {@link DurableTimer.onAlarm} awaits this BEFORE it
+     * re-arms, so the re-arm sees the post-fire state.
+     */
+    onFire(): void | Promise<void>;
+}
+/**
+ * The activated durable timer. Two methods, both idempotent to call from the
+ * host edge:
+ *   - {@link DurableTimer.rearm} — recompute + (re-)arm or idle. Call it once
+ *     after cold-wake recovery, and after any state transition that can change
+ *     whether/when the next deadline should fire.
+ *   - {@link DurableTimer.onAlarm} — the DO `alarm()` body: fire, then re-arm.
+ */
+interface DurableTimer {
+    /**
+     * Recompute {@link DurableTimerConfig.nextDeadline} off the live state and arm
+     * the alarm at it — or, when it returns `null`, arm nothing (idle). Safe to
+     * call repeatedly; arming the same absolute target twice is a harmless
+     * overwrite on the DO alarm API.
+     */
+    rearm(): Promise<void>;
+    /**
+     * The body the DO `alarm()` lifecycle hook delegates to: run
+     * {@link DurableTimerConfig.onFire}, then {@link DurableTimer.rearm} off the
+     * post-fire state. A still-active grain keeps ticking; an idle one (its
+     * `nextDeadline` now `null`) stops here.
+     */
+    onAlarm(): Promise<void>;
+}
+/**
+ * Build a {@link DurableTimer} over an injected alarm carrier, a next-deadline
+ * computation, and a fire handler. The returned timer owns the
+ * compute-next-deadline → `setAlarm` → `alarm()` → fire → re-arm loop and holds
+ * no schedule of its own (the deadline is always recomputed from live state),
+ * which is what makes it eviction-safe across hibernation.
+ */
+declare function durableTimer(config: DurableTimerConfig): DurableTimer;
+
+/**
+ * @demlik/tea/do — event-sourced persistence mode for a Durable Object actor.
+ *
+ * `doStore` (sibling, `./index`) is the DEFAULT and stays snapshot-only: it
+ * writes the whole `S` blob to one cell on every transition and reads it back
+ * on boot. That is byte-for-byte unchanged by this file.
+ *
+ * `doEventSourcedStore` is the OPT-IN alternative. Instead of (only)
+ * checkpointing the latest state, it:
+ *
+ *   1. APPENDS each applied `Msg` to an append-only log in `DurableObjectStorage`
+ *      (one cell per event, monotonically keyed).
+ *   2. Takes a PERIODIC SNAPSHOT every `snapshotEvery` events (count-based
+ *      retention — mirrors Akka `RetentionCriteria.snapshotEvery`) so the log
+ *      that must replay on the next activation is bounded. A grain that needs
+ *      replay bounded by ELAPSED TIME/TICKS rather than raw event count drives
+ *      `snapshotNow()` instead (or alongside) — see that method.
+ *   3. On activation REBUILDS state by FOLDING the log on top of the latest
+ *      snapshot. The fold is the substrate's own `replay` — `init(snapshot)`
+ *      then one reducer step per logged Msg. `replay` returns Cmds as data and
+ *      never interprets them, so **side effects are suppressed on replay**
+ *      (recovery.md). This is the same primitive `foldEvents` / the recorder
+ *      use; it is reused here, not reinvented (ADR 0003: "the fold already
+ *      exists; wire it to Store").
+ *
+ * The "recovered/ready" signal (recovery.md `RecoveryCompleted`) is delivered
+ * exactly once per activation via `onReady`, EVEN for a fresh actor with an
+ * empty log, and is documented to be idempotent (it may fire again on a later
+ * activation, so the handler must tolerate repeats).
+ *
+ * Integration with the cooperating DO:
+ *
+ *   const es = doEventSourcedStore(storage, machine, ctx, {
+ *     snapshotEvery: 100,
+ *     parse,                       // optional boundary parse for the snapshot
+ *     onReady: (state) => { ... }, // optional, idempotent end-of-recovery hook
+ *   });
+ *   const runtime = run(machine, { ctx, store: es.store });
+ *   // Append every applied Msg to the log. `observe` delivers only applied
+ *   // Msgs now (#47) — boot has no event, so there is no `null` arm to skip.
+ *   runtime.observe((msg) => { es.append(msg); });
+ *   await runtime.ready; // store.load() has folded; onReady has fired once.
+ *
+ * A time/tick-driven grain (e.g. one that derives simulation ticks between
+ * sparse intents) bounds its cold-wake replay by ELAPSED TIME rather than event
+ * count by calling `es.snapshotNow()` on its own cadence — every N derived ticks
+ * or on a wall-clock interval — so a quiet span that never trips `snapshotEvery`
+ * is still snapshotted before its replay tail grows unbounded (#190):
+ *
+ *   // in the grain's tick loop, after the turn's appends have settled:
+ *   if (tick % SNAPSHOT_EVERY_TICKS === 0) await es.snapshotNow();
+ */
+
+/**
+ * Options for {@link doEventSourcedStore}.
+ */
+interface EventSourcedOptions<S, M> {
+    /**
+     * Take a snapshot every N appended events (count-based retention, mirrors
+     * Akka `RetentionCriteria.snapshotEvery`). A snapshot bounds how many events
+     * replay on the next activation — it never changes the fold's result, only
+     * its length (recovery.md). Must be >= 1. Default 100.
+     */
+    readonly snapshotEvery?: number;
+    /**
+     * Boundary parse for the persisted SNAPSHOT cell (the `S` blob). Same
+     * contract as `doStore`'s `parse`: returns `S` on a recognized shape, `null`
+     * on an unrecognized one (boot fresh), and must NOT throw. Default accepts
+     * any non-null, non-array object as `S`.
+     */
+    readonly parse?: (raw: unknown) => S | null;
+    /**
+     * Boundary parse for a persisted EVENT (one logged `Msg`). Returns the `M` on
+     * a recognized shape; returning `null` DROPS the event from replay (use for a
+     * removed Msg variant). Must NOT throw. Default accepts any object carrying a
+     * string `type` as `M`.
+     */
+    readonly parseEvent?: (raw: unknown) => M | null;
+    /**
+     * End-of-recovery hook (recovery.md `RecoveryCompleted`). Fires EXACTLY ONCE
+     * per activation, after the fold completes, carrying the recovered state —
+     * even when the log was empty (fresh actor). It may fire again on a later
+     * activation, so it MUST be idempotent. Side effects that belong "once after
+     * recovery" go here, never in the reducer (the reducer re-runs on every
+     * replay).
+     */
+    readonly onReady?: (state: S) => void;
+    /** Cell-key overrides (rarely needed; for coexisting actors in one DO). */
+    readonly keys?: {
+        readonly snapshot?: string;
+        readonly meta?: string;
+        readonly eventPrefix?: string;
+    };
+}
+/**
+ * One persisted log entry handed to a {@link EventSourcedStore.readEvents}
+ * consumer: the monotonic `seq` the event was appended under, paired with the
+ * decoded `event`. `seq` is the store's own append counter (the key the event
+ * lives under), so it both orders the stream and bounds an {@link EventLogRange}.
+ */
+interface PersistedEvent<M> {
+    /** The append sequence number this event was logged under (1-based, gap-free). */
+    readonly seq: number;
+    /** The decoded `Msg`, parsed through the store's `parseEvent` boundary. */
+    readonly event: M;
+}
+/**
+ * Optional inclusive bounds for {@link EventSourcedStore.readEvents}. Both ends
+ * are inclusive and match against the event's `seq`; omitting an end leaves it
+ * unbounded. `{ fromSeq: 5, toSeq: 10 }` yields seqs 5..10; `{}` (or no
+ * argument) yields the whole log.
+ */
+interface EventLogRange {
+    /** Lowest `seq` to include (inclusive). Default: the first event. */
+    readonly fromSeq?: number;
+    /** Highest `seq` to include (inclusive). Default: the last event. */
+    readonly toSeq?: number;
+}
+/**
+ * The handle returned by {@link doEventSourcedStore}: a `Store<S>` to hand to
+ * `run(...)`, plus the append + recovery surface the cooperating DO drives.
+ */
+interface EventSourcedStore<S, M> {
+    /**
+     * The `Store<S>` to pass as `run(machine, { ctx, store })`. Its `load()`
+     * performs the fold (snapshot + log replay); its `save(state)` is the
+     * count-based snapshot writer. `migrate` forwards to `parse`.
+     */
+    readonly store: Store<S>;
+    /**
+     * Append one applied `Msg` to the log. Call from `runtime.observe` for every
+     * non-null msg. Resolves once the event is durably written. Triggers a
+     * snapshot when the event count crosses a `snapshotEvery` boundary.
+     */
+    append(msg: M): Promise<void>;
+    /**
+     * Take a snapshot NOW, independent of the count-based `snapshotEvery` trigger
+     * (a time/tick-based retention trigger, #190). The count-based trigger bounds
+     * the replay tail by raw EVENT COUNT; a grain that derives many state
+     * transitions per logged event (e.g. simulation ticks between sparse intents)
+     * needs the tail bounded by ELAPSED TIME instead — so it calls `snapshotNow()`
+     * on its own cadence (every N derived ticks, or on a wall-clock interval) to
+     * checkpoint the current folded state without injecting filler events purely
+     * to advance the counter.
+     *
+     * It checkpoints the latest state the substrate handed `save()` at the current
+     * highest sequence, then advances the count-based baseline (`snapshotEvery`
+     * counts afresh from here, so a manual snapshot defers the next automatic one).
+     *
+     * Returns `true` if a snapshot was written, `false` on a no-op: nothing has
+     * been applied yet (fresh actor), or no new event exists since the last
+     * snapshot (already current). Like the count-based path, it pairs the held
+     * state with the highest sequence, so the caller MUST invoke it between
+     * settled transitions — after the turn's `append()`s have resolved — never
+     * mid-transition (the same boundary discipline `append`'s own snapshot relies
+     * on). Resolves once the snapshot is durably written.
+     */
+    snapshotNow(): Promise<boolean>;
+    /**
+     * Stream the persisted event log in `seq` order, optionally bounded by an
+     * inclusive {@link EventLogRange}. This is the PUBLIC read side of the
+     * event-sourced write model — the surface replay / projection / audit
+     * consumers (CQRS reads, recovery.md / projections.md) read through, instead
+     * of mirroring the store's private `@@es/evt/` key convention.
+     *
+     * The log is APPEND-ONLY and is never truncated by snapshotting (a snapshot
+     * only bounds the *replay* tail, never the log), so this yields EVERY event
+     * in range — including ones a snapshot already folds. Each entry carries its
+     * `seq`, so a consumer can resume from a known offset (`{ fromSeq }`) or read
+     * a window (`{ fromSeq, toSeq }`). An empty (or fully out-of-range) log yields
+     * nothing. Events whose `parseEvent` returns `null` (a retired Msg variant)
+     * are dropped, identical to the recovery fold.
+     *
+     * Read-only: it never appends, snapshots, or mutates store state, so streaming
+     * the log can never perturb the live actor.
+     */
+    readEvents(range?: EventLogRange): AsyncIterable<PersistedEvent<M>>;
+}
+/**
+ * Build an event-sourced `Store<S>` over `DurableObjectStorage`.
+ *
+ * The substrate calls `store.load()` once at boot — that is where the fold
+ * happens — and `store.save(state)` after every transition — that is where the
+ * count-based snapshot is taken. The cooperating DO additionally calls
+ * `append(msg)` from `runtime.observe` to grow the log.
+ *
+ * `machine` and `ctx` are required because the fold is `replay(machine, {
+ * loaded: snapshot, msgs: log, ctx })` — the same pure reducer the live runtime
+ * uses, so the rebuilt state is identical to the never-evicted state by
+ * construction. `ctx` is only used to satisfy `init`'s signature during the
+ * fold; an event-sourced machine's `init` rehydrate branch is a pure
+ * passthrough (TEA invariant 2), so the fold touches nothing in `ctx`.
+ */
+declare function doEventSourcedStore<S, M extends {
+    type: string;
+}, Ctx, C extends Cmd = Cmd, U extends Sub = Sub>(storage: DurableObjectStorage, machine: Machine<S, M, C, U, Ctx>, ctx: Ctx, opts?: EventSourcedOptions<S, M>): EventSourcedStore<S, M>;
+
+/**
+ * @demlik/tea/do — CQRS projections as a first-class seam.
+ *
+ * TODAY (`./host`), "Model → views" is ad-hoc: `sseHub` is a hand-rolled
+ * sink-set fanning `runtime.observe` events out. It re-derives a common shape:
+ * subscribe to `observe`, fold each update into a private view, push the view
+ * at a sink. (The run's terminal output was once another such observe-driven
+ * read model — `captureLastTurn` — but that is now modelled first-class on the
+ * write model itself as `state.output` / `runtime.result()`, #46.)
+ *
+ * This file names that shape. A `Projection<Model, View>` is the canon's
+ * "one write model, many projections" contract made concrete on the tea
+ * substrate (`.patterns/tea-do/projections.md`):
+ *
+ *   1. ONE WRITE MODEL, MANY PROJECTIONS. The write model is the agent's `run()`
+ *      State (`Model`) plus its `Msg` stream. Each projection is an INDEPENDENT
+ *      `(events|Model) → view` derivation into its OWN read model, with its own
+ *      id-scoped offset. Adding a projection never touches the write model or
+ *      any other projection — it only registers another consumer of `observe`.
+ *
+ *   2. OFFSET-RESUME + IDEMPOTENT APPLY ARE ONE UNIT. A durable projection
+ *      tracks an EXCLUSIVE offset — the last applied position. On restart it
+ *      resumes STRICTLY AFTER the stored offset (never ±1); at-least-once
+ *      delivery means the same update may be re-presented, so `apply` must be
+ *      idempotent (an upsert of the derived view, never a blind increment).
+ *      WHEN the offset is committed relative to the view write IS the delivery
+ *      semantic (`.patterns/tea-do/delivery-semantics.md`):
+ *        - commit AFTER the view write  → at-least-once  (may reprocess)
+ *        - commit in the SAME step      → exactly-once   (the default here)
+ *      We persist offset-with-view as one unit (a single `OffsetView` cell), so
+ *      a durable projection is exactly-once by construction; the at-least-once
+ *      replay window is still exercised because `drive()` may re-present an
+ *      update at/below the stored offset (boot reconcile, double-observe), and
+ *      the exclusive-offset guard makes that a no-op.
+ *
+ *   3. A VIEW IS ALWAYS REBUILDABLE. Clearing the view and resetting the offset
+ *      to the start (`rebuild`) replays the `Msg`/`Model` stream from zero. The
+ *      live view and the rebuilt view are equal by construction — both are the
+ *      same pure `apply` fold over the same ordered updates.
+ *
+ * Relationship to `./host`: `sseHub` is re-expressed here as ONE projection
+ * (`sseProjection`) WITHOUT changing its public API — `host.sseHub()` keeps
+ * working for existing callers (it is the volatile, offset-free case: a live
+ * SSE stream has no durable read model to resume).
+ *
+ * Relationship to `./event-sourced-store`: a durable projection resumes over
+ * the SAME append-only event log `doEventSourcedStore` (#68) writes. The fold
+ * is the projection's `apply`, scoped to the projection's offset — independent
+ * of the write model's snapshot/replay. This file does NOT import the store; it
+ * is offset-shaped so a consumer can wire either the live `observe` stream or a
+ * replay over the log into the same `apply`.
+ */
+/** A projection's identity: `name` (the view) + `key` (the instance). */
+interface ProjectionId {
+    readonly name: string;
+    readonly key: string;
+}
+/** Render a `ProjectionId` to its canonical `name-key` string. */
+declare function projectionIdString(id: ProjectionId): string;
+/**
+ * One unit the projection driver presents to a projection's `apply`. Mirrors
+ * the `(msg, model)` pair `runtime.observe` fans out, plus the exclusive
+ * `offset` the driver assigns. `msg === null` is the boot update (no event).
+ */
+interface ProjectionUpdate<Model, Msg> {
+    /** The applied event, or `null` on the boot update (initial state). */
+    readonly msg: Msg | null;
+    /** The post-transition write-model state. */
+    readonly model: Model;
+    /**
+     * The exclusive position of this update in the ordered stream — monotonic,
+     * 1-based; 0 is the boot update (the `NoOffset` start). The stored offset is
+     * EXCLUSIVE: re-presenting an update whose offset is `<=` the stored offset
+     * must be a no-op (the at-least-once replay window). Do NOT ±1 it.
+     */
+    readonly offset: number;
+}
+/**
+ * A named CQRS projection: an independent fold of the write model's
+ * `(Msg|Model)` stream into a private `View`, plus a sink to publish it.
+ *
+ * @typeParam Model The write-model state (`run()`'s `S`).
+ * @typeParam Msg   The write-model event (`run()`'s `M`).
+ * @typeParam View  The read model this projection derives.
+ */
+interface Projection<Model, Msg extends {
+    type: string;
+}, View> {
+    /** This projection's id (offset-isolation unit). */
+    readonly id: ProjectionId;
+    /** The seed view for a fresh or rebuilt run (the `NoOffset` start). */
+    readonly initial: View;
+    /**
+     * The per-envelope reducer: derive the next view from the previous view and
+     * one update. Pure; MUST be idempotent — re-applying an update at the same
+     * offset yields the same view (upsert the derived value, never a blind
+     * increment). Returning the SAME view reference (or an equal one) for an
+     * update the view does not care about is the canonical "skip".
+     */
+    apply(view: View, update: ProjectionUpdate<Model, Msg>): View;
+    /**
+     * The sink — publish the derived view. SSE frame, durable cell, report row.
+     * Fired by the driver after `apply` produces a new view. A throwing `emit` is
+     * isolated by the driver (it must not strand sibling projections).
+     */
+    emit(view: View): void;
+}
+/**
+ * A live, running projection instance: the projection's current `View`, its
+ * exclusive stored `offset`, and the `present`/`reset` operations the driver
+ * (or a rebuild) calls.
+ */
+interface ProjectionRunner<Model, Msg extends {
+    type: string;
+}, View> {
+    readonly id: ProjectionId;
+    /** The current derived view (the read model). */
+    view(): View;
+    /**
+     * The exclusive stored offset — the position of the LAST applied update.
+     * Resume reads strictly after this; `0` is the `NoOffset` start.
+     */
+    offset(): number;
+    /**
+     * Present one update to the projection. At-least-once entry point:
+     *   - if `update.offset <= storedOffset` the update was already applied →
+     *     NO-OP (idempotent replay window; offset stays, view stays, no emit).
+     *   - otherwise fold via `apply`, advance the offset TO `update.offset`, and
+     *     `emit` the new view. Offset-and-view advance together (one unit) →
+     *     exactly-once: the stored offset always matches the folded view.
+     * Returns true iff the update was applied (false on the no-op replay).
+     */
+    present(update: ProjectionUpdate<Model, Msg>): boolean;
+    /**
+     * Clear the view to `initial` and the offset to 0 — the canonical rebuild
+     * reset (offset-tracking.md: "resetting it to NoOffset is the view-rebuild
+     * operation"). After `reset`, re-presenting the full stream rebuilds the view.
+     */
+    reset(): void;
+}
+/**
+ * Build a {@link ProjectionRunner} for a projection, starting from a stored
+ * offset (default 0 = `NoOffset`, a fresh run). The view is seeded to
+ * `projection.initial`; the caller resumes by presenting updates strictly after
+ * `startOffset` (the driver's offset guard enforces exclusivity even if an
+ * already-applied update is re-presented).
+ *
+ * `emitOnStart`/`emitOnReset` default false: a fresh runner holds `initial` but
+ * does not push it at the sink until the first real update lands (an SSE client
+ * that just connected wants the next event, not a replay of the seed).
+ */
+declare function runProjection<Model, Msg extends {
+    type: string;
+}, View>(projection: Projection<Model, Msg, View>, startOffset?: number): ProjectionRunner<Model, Msg, View>;
+/**
+ * A driver over a set of projections sharing one write-model stream. Holds the
+ * monotonic offset counter; presents each observed update to every registered
+ * runner independently.
+ */
+interface ProjectionRegistry<Model, Msg extends {
+    type: string;
+}> {
+    /** Register a projection; returns its live runner. */
+    register<View>(projection: Projection<Model, Msg, View>, startOffset?: number): ProjectionRunner<Model, Msg, View>;
+    /**
+     * Present one update to EVERY registered runner. Each folds independently; an
+     * `apply`/`emit` throw in one runner is caught so it cannot strand the others
+     * (errors-are-data: a broken projection is dropped from THIS update, not
+     * allowed to corrupt siblings). Returns the offset assigned to this update.
+     */
+    dispatch(msg: Msg | null, model: Model): number;
+    /** The current monotonic offset (the last dispatched update's position). */
+    offset(): number;
+    /** The registered runners (introspection / tests). */
+    runners(): readonly ProjectionRunner<Model, Msg, unknown>[];
+}
+/** Build an empty {@link ProjectionRegistry}. */
+declare function projectionRegistry<Model, Msg extends {
+    type: string;
+}>(): ProjectionRegistry<Model, Msg>;
+/**
+ * Wire a {@link ProjectionRegistry} to a runtime's transition stream. The boot
+ * update (the initial state, offset 0) is presented via `onBoot`; every applied
+ * transition (offset 1, 2, …) via `observe` — together they reproduce the
+ * "every transition including boot" stream the single `observe(msg | null)`
+ * channel used to carry, now that `observe`'s `msg` is total (#47). The registry
+ * still assigns its monotonic exclusive offset (boot → 0, first Msg → 1).
+ * Returns a cleanup that detaches both subscriptions.
+ *
+ * Typed structurally against `{ observe, onBoot }` so it accepts any
+ * `Runtime<Model, Msg>` without importing the substrate's `Runtime` (types-only
+ * boundary).
+ */
+declare function driveProjections<Model, Msg extends {
+    type: string;
+}>(registry: ProjectionRegistry<Model, Msg>, runtime: {
+    observe(observer: (msg: Msg, model: Model) => void): () => void;
+    onBoot(handler: (model: Model) => void): () => void;
+}): () => void;
+/**
+ * Rebuild a projection's view by folding an ordered event stream from the
+ * `NoOffset` start. The runner is seeded to `projection.initial` (the implicit
+ * boot / `NoOffset` state), then each `updates[i]` is presented at offset
+ * `i + 1` — so the FIRST event (`updates[0]`) lands at offset 1 and is folded,
+ * exactly mirroring the live driver, which assigns the first applied `Msg`
+ * offset 1 (the boot observe is offset 0 and never enters this list). Returns
+ * the rebuilt runner whose `view()` equals the live runner's view for the same
+ * ordered stream.
+ *
+ * Pass the ordered events only; do NOT prepend a boot (`msg === null`) entry.
+ * With the `i + 1` offsets a leading boot entry would be applied at offset 1
+ * like any event (the seed already covers the `NoOffset` start), not skipped —
+ * the offset-0 skip that drops the boot is the live driver's, not this fold's.
+ *
+ * This is the rebuild-equivalence oracle: a view cleared and replayed from the
+ * stream equals the live view.
+ */
+declare function rebuildProjection<Model, Msg extends {
+    type: string;
+}, View>(projection: Projection<Model, Msg, View>, updates: readonly {
+    readonly msg: Msg | null;
+    readonly model: Model;
+}[]): ProjectionRunner<Model, Msg, View>;
+
+/**
+ * @demlik/tea/do — the minimum-viable Durable-Object HOST for a `@demlik/tea`
+ * `createAgent` runtime.
+ *
+ * `doStore` (in `./index`) is the durability half. This file is the rest of the
+ * boilerplate a DO consumer hand-rolls every time it drives a tea agent over a
+ * remote transport: the deferred-tool gateway, auto-boot on rehydrate, the
+ * command-runner WS accept, the runtime→SSE plumbing, and a clean read of a
+ * run's terminal output. Each export below names exactly the hand-rolled piece
+ * it deletes from the consumer.
+ *
+ * ## The transport model: ONE Sub type, gateway-bridged I/O
+ *
+ * `createAgent().toMachine()` fixes the machine's Sub type to `DeadlineSub` —
+ * the agent owns the retry + watchdog timers and nothing else. That is the
+ * WHOLE Sub model for a DO-hosted agent, and it is coherent because the
+ * transport deliberately does NOT live in the Sub system:
+ *
+ *   - Inbound WebSocket frames are bridged straight into `gateway.settle(...)`
+ *     from the DO's `webSocketMessage` lifecycle method — a direct dispatch,
+ *     not a Sub.
+ *   - The per-tool deadline is a `setTimeout` inside the gateway — a timer, not
+ *     a DO alarm.
+ *
+ * The deferred-tool gateway owns each tool round-trip as a Promise the interpret
+ * cell awaits; the transport bridges results into `dispatch` from outside the
+ * Sub system. The agent's Sub type stays exactly `DeadlineSub` — there is no
+ * competing DO-native Sub variant to union in, and the host needs none. This is
+ * the single transport model for `@demlik/tea/do` (#52); see
+ * `.patterns/tea/durable-actors.md` for the host-layer north star.
+ */
+
+/**
+ * The deferred-tool gateway. `R` is the consumer's tool-result type (what
+ * `agent_tool_ok` carries).
+ *
+ *   - `await(callId, send, deadlineMs)` — register the round-trip, fire `send`,
+ *     return the Promise the reply (or the deadline) settles. Idempotent per
+ *     `callId`: a second call for an in-flight id returns the SAME promise
+ *     without re-firing `send` (the boot-reconcile re-fire is a no-op at the
+ *     gateway, mirroring the agent's idempotent boot).
+ *   - `settle(callId, result)` — the transport calls this on a reply; resolves
+ *     the awaited promise. A settle for an unknown / already-settled id is a
+ *     no-op (the callId guard the consumer used to keep in its pending Map).
+ *   - `fail(callId, reason)` — settle the round-trip as an error on demand
+ *     (e.g. a transport-level close). Same unknown-id no-op.
+ *   - `inFlight()` — the callIds with an open round-trip (tests / introspection).
+ *
+ * The deadline → reject path is what makes "timeout is data": the tool cell's
+ * `catch` maps the rejection to `agent_tool_err`, recorded on the conversation,
+ * never a hang.
+ */
+interface DeferredGateway<R> {
+    await(callId: string, send: () => void, deadlineMs: number): Promise<R>;
+    settle(callId: string, result: R): void;
+    fail(callId: string, reason: string): void;
+    inFlight(): readonly string[];
+}
+/**
+ * Build a deferred-tool gateway. No clock / RNG captured at construction — the
+ * deadline is per-call (`await(..., deadlineMs)`), so one gateway serves every
+ * tool family with its own timeout.
+ *
+ * Deletes from the consumer: the `pending` Map, the `Pending` interface, the
+ * `awaitClient` method, the `forceTimeout` plumbing, and the `deliverResult`
+ * callId-guard body — all of it collapses to this object plus the tool cell's
+ * `await` + try/catch.
+ */
+declare function deferredGateway<R>(): DeferredGateway<R>;
+/** A `callId`-keyed durable round-trip: maps the gateway's string id to the
+ *  ledger's monotonic delivery id so a `settle(callId)` finds the owed entry. */
+interface DurableDeferredGateway<R> extends DeferredGateway<R> {
+    /** The ledger recorder this gateway feeds (for `surviving()` on activation). */
+    readonly recorder: PendingEffectsRecorder<{
+        callId: string;
+    }>;
+}
+/**
+ * Wrap a `DeferredGateway<R>` so every round-trip is also recorded in a durable
+ * `PendingEffectsRecorder`. The in-memory gateway is the fast path; the recorder
+ * is the durability slice.
+ *
+ *   - `recordOwed(callId, event)` — fires from `await`, BEFORE `send`, carrying
+ *     the `effect_owed` event the consumer must persist (then deliver).
+ *   - `recordConfirmed(callId, event)` — fires from `settle`/`fail` for a known
+ *     id, carrying the `effect_confirmed` event to persist.
+ *   - `reissue(callId, send, deadlineMs)` — re-arm a surviving round-trip on
+ *     activation. Idempotent: the gateway's own `await` returns the open promise
+ *     without re-firing `send` for an in-flight `callId`, so re-issuing an id
+ *     that is somehow still pending is a no-op (mirrors the boot-reconcile
+ *     re-fire). The effect is already owed, so no second `effect_owed` is
+ *     recorded.
+ *
+ * The effect payload the ledger stores is the `callId` (the correlation key the
+ * consumer round-trips); the consumer maps it back to its tool-call context.
+ */
+declare function durableDeferredGateway<R>(inner: DeferredGateway<R>, recorder: PendingEffectsRecorder<{
+    callId: string;
+}>, hooks: {
+    recordOwed(callId: string, event: EffectOwed<{
+        callId: string;
+    }>): void;
+    recordConfirmed(callId: string, event: EffectConfirmed): void;
+}): DurableDeferredGateway<R>;
+/**
+ * The typed cold-wake resume port `bootResume` fires through — the agent's
+ * `AgentBootPort` (issue #60) generalized to any DO-hosted machine (issue #231).
+ *
+ * - `isResumable(state)` — true iff the rehydrated State is mid-loop and needs a
+ *   resume dispatch. False on a fresh boot, which makes `bootResume` a no-op.
+ * - `resumeMsg(now)` — the TYPED constructor for the single resume Msg (never a
+ *   hand-built `{ type: … }` literal); the `agentBootMsg` shape lifted out so a
+ *   non-agent grain supplies its own boot Msg constructor.
+ */
+interface ResumePort<S, M extends {
+    type: string;
+}> {
+    readonly isResumable: (state: S) => boolean;
+    readonly resumeMsg: (now: number) => M;
+}
+/**
+ * After `runtime.ready`, derive the single resume Msg from the rehydrated State
+ * via `port` and dispatch it exactly once — the generalized AgentBoot. On a
+ * fresh (non-rehydrated) machine `port.isResumable` is false and this is a
+ * no-op. Call once right after building the runtime; it standardizes the
+ * hand-written `if (isResumable(state)) await runtime.dispatch(bootMsg(now()))`
+ * every DO-hosted machine otherwise re-derives.
+ *
+ * `await ready` is the single boot gate (issue #45): `getState()` is total only
+ * on the booted `Runtime`, so state cannot be inspected before boot populates
+ * it. `now` is injected (the sole boot clock read) so a test can pin it.
+ */
+declare function bootResume<S, M extends {
+    type: string;
+}, E extends {
+    type: string;
+} = never>(booting: BootingRuntime<S, M, E>, port: ResumePort<S, M>, now?: () => number): Promise<void>;
+/**
+ * True iff an agent slice loaded from storage is mid-loop (running + awaiting
+ * tools) — the resumable case `agent_boot` re-fires.
+ *
+ * The resumability question IS "is the run suspended on tools?" — so this
+ * delegates to the agent's own typed `status` channel (issue #49) rather than
+ * re-deriving the private `run.phase` / `conversation.awaiting` shape by hand.
+ * The host no longer leaks the agent's internal slice structure; a change to
+ * `Awaiting` surfaces as a compile error in `status`, not a silent break here.
+ */
+declare function agentIsResumable<Stage, P extends string, O extends Record<P, unknown>, R>(state: AgentState<Stage, P, O, R>): boolean;
+/**
+ * The AGENT specialization of {@link bootResume} (issue #231): after
+ * `runtime.ready`, self-dispatch `agent_boot` iff the rehydrated slice is
+ * resumable, a no-op on a fresh DO. Wires the agent slice's `agentIsResumable`
+ * predicate + the agent-owned `agentBootMsg` typed port (issue #60) into the
+ * generalized helper, so the resume dispatch lives in ONE place — see
+ * `bootResume`'s docblock for the boot-gate / init-purity rationale.
+ *
+ * `now` is injected (the host's only clock read for boot) so a test can pin it.
+ */
+declare function autoBoot<Stage, P extends string, O extends Record<P, unknown>, R, E extends {
+    type: string;
+} = never>(booting: BootingRuntime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, E>, now?: () => number): Promise<void>;
+/**
+ * Accept a command-runner WebSocket on the DO's `fetch`. Adds the server end to
+ * `clients`, wires `message` → `onFrame(data)` (string frames only) and
+ * `close` → deregister, and returns the 101 upgrade Response.
+ *
+ * The consumer's `onFrame` parses the frame and calls `gateway.settle(callId,
+ * result)` — the inbound bridge. Deletes the consumer's `acceptClient` method.
+ */
+declare function acceptCommandSocket(clients: Set<WebSocket>, onFrame: (data: string) => void): Response;
+/**
+ * Broadcast a JSON frame to every connected command-runner socket. A dead
+ * socket is skipped (dropped on its own `close` event). Lifts the consumer's
+ * fan-out loop in `sendCommand`.
+ */
+declare function broadcast(clients: Set<WebSocket>, frame: unknown): void;
+/**
+ * The slice of `DurableObjectState` the durable carrier needs: the Hibernation
+ * API accept + the registry of hibernatable sockets. A real `DurableObjectState`
+ * satisfies this structurally; a test supplies a fake (no live Workers runtime
+ * needed to exercise the accept/registry seam).
+ */
+interface HibernatableCtx {
+    acceptWebSocket(ws: WebSocket): void;
+    getWebSockets(): WebSocket[];
+}
+/**
+ * Accept a command-runner WebSocket using the Cloudflare **Hibernation API** so
+ * the socket survives DO eviction. Unlike {@link acceptCommandSocket}, this does
+ * NOT attach an isolate-resident `message` listener (that listener is what dies
+ * on eviction) — instead `ctx.acceptWebSocket(server)` hands the socket to the
+ * runtime, which re-creates the DO and calls its `webSocketMessage(ws, data)`
+ * lifecycle method on the next inbound frame. The consumer routes that method to
+ * its `onFrame` (which calls `carrier.settle(callId, result)`).
+ *
+ * Returns the 101 upgrade Response. There is no `clients` registry to keep — the
+ * live sockets are `ctx.getWebSockets()` (see {@link broadcastHibernatable}),
+ * which the runtime repopulates after a wake.
+ */
+declare function acceptDurableCommandSocket(ctx: HibernatableCtx): Response;
+/**
+ * Broadcast a JSON frame to every hibernatable command-runner socket. The live
+ * set is read from `ctx.getWebSockets()` (the runtime repopulates it after a
+ * wake), NOT a resident `Set<WebSocket>` — so it is correct immediately after an
+ * eviction, before any other lifecycle method has run. A dead socket is skipped.
+ */
+declare function broadcastHibernatable(ctx: HibernatableCtx, frame: unknown): void;
+/**
+ * The durable command carrier — a {@link DurableDeferredGateway} whose every
+ * tool round-trip is also a durable owed effect.
+ *
+ * A consumer's tool interpret cell still calls `carrier.await(callId, send,
+ * deadlineMs)` and awaits the Promise (mapping Ok/Err to `agent_tool_ok` /
+ * `agent_tool_err`) — the SAME fast path as the volatile gateway. The addition
+ * is durability: `await` hands the consumer an `effect_owed` event (via
+ * `recordOwed`) to PERSIST before the send, and `settle`/`fail` hand it an
+ * `effect_confirmed` (via `recordConfirmed`) to persist. On the next activation
+ * the consumer reads its persisted ledger events back and calls
+ * {@link reissueSurvivingEffects} to re-fire the survivors.
+ *
+ * It extends `DurableDeferredGateway` (so it is a drop-in for the gateway the
+ * interpret cell already awaits) and exposes the underlying `recorder` for a
+ * host that wants to read `surviving()` directly.
+ */
+interface DurableCommandCarrier<R> extends DeferredGateway<R> {
+    /** The ledger recorder backing this carrier (for `surviving()` introspection). */
+    readonly recorder: PendingEffectsRecorder<{
+        callId: string;
+    }>;
+}
+/**
+ * Build a durable command carrier over a (volatile) `DeferredGateway<R>` and a
+ * `PendingEffectsRecorder`. Thin assembly over {@link durableDeferredGateway}:
+ * it names the #91 piece — "the command carrier whose round-trips survive
+ * eviction" — and keeps the recorder reachable for the activation-time re-emit.
+ *
+ *   - `inner` — the volatile gateway whose in-isolate Promise the interpret cell
+ *     awaits (typically `deferredGateway<R>()`).
+ *   - `recorder` — the durable-effects recorder (typically
+ *     `pendingEffectsLedger({ events, lastId })` rehydrated from the persisted
+ *     log on a wake, or a fresh `pendingEffectsLedger()` on a cold boot).
+ *   - `hooks.recordOwed` / `hooks.recordConfirmed` — the persist callbacks the
+ *     consumer points at its event log (so the ledger survives eviction).
+ *
+ * The carrier never persists anything itself (it does not own the consumer's
+ * log) — it hands the consumer the events, faithful to "persist the intent
+ * before deliver".
+ */
+declare function durableCommandCarrier<R>(inner: DeferredGateway<R>, recorder: PendingEffectsRecorder<{
+    callId: string;
+}>, hooks: {
+    recordOwed(callId: string, event: EffectOwed<{
+        callId: string;
+    }>): void;
+    recordConfirmed(callId: string, event: EffectConfirmed): void;
+}): DurableCommandCarrier<R>;
+/**
+ * RE-EMIT ON ACTIVATION (the #91 wake path). Given a durable carrier whose
+ * recorder was rehydrated from the persisted ledger events (e.g.
+ * `durableCommandCarrier(deferredGateway(), pendingEffectsLedger({ events }),
+ * …)` on a wake), re-fire every owed-but-unconfirmed round-trip via
+ * `reissue(callId)` — the consumer's "re-send the command frame for this
+ * `callId`" callback. The survivors are read straight off the carrier's own
+ * recorder (`recorder.surviving()`), which folded the restore log at
+ * construction — the carrier is the single source of the in-flight set, so the
+ * caller does not re-fold the log here.
+ *
+ * Idempotent by construction:
+ *   - the ledger's monotonic `deliveryId` is the dedup key the RECEIVER uses, so
+ *     a late/duplicate reply for an already-resolved round-trip is absorbed
+ *     (at-least-once delivery — see `survivingEffects`);
+ *   - re-issuing the SAME survivor twice within one activation re-sends once —
+ *     if `reissue` routes through the carrier's `await`, the gateway returns the
+ *     open Promise for an in-flight `callId` without re-firing `send`.
+ *
+ * Returns the `callId`s re-emitted (oldest-first by id) — the host can log /
+ * assert the re-emit set. On a fresh or fully-confirmed carrier this is empty
+ * (nothing re-fired).
+ *
+ * Call this once, right after the runtime's boot gate resolves (alongside
+ * {@link autoBoot}): `autoBoot` re-fires the agent's own `agent_boot`;
+ * `reissueSurvivingEffects` re-fires the in-flight TOOL round-trips. Together
+ * they restore a suspended run's full in-flight state after a wake.
+ */
+declare function reissueSurvivingEffects<R>(carrier: DurableCommandCarrier<R>, reissue: (callId: string) => void): readonly string[];
+/**
+ * A set of SSE sinks plus the plumbing to fan an event out to all of them and
+ * to open a `text/event-stream` Response wired to a fresh sink.
+ *
+ * The consumer:
+ *   1. holds one `SseHub<E>` per DO,
+ *   2. calls `hub.emit(event)` from its Msg→event mapping (driven off
+ *      `runtime.observe`), and
+ *   3. returns `hub.open()` from the `/sse` route.
+ *
+ * `register(sink)` exists for tests: subscribe a sink directly and observe the
+ * exact event sequence a live client would receive (a live `text/event-stream`
+ * fights vitest-pool-workers teardown). Deletes the consumer's `sseSinks` set,
+ * `openSse`, `emitSse`, and `onSseEvent`.
+ */
+interface SseHub<E> {
+    emit(event: E): void;
+    open(): Response;
+    register(sink: (event: E) => void): () => void;
+}
+/** Build an SSE hub for event type `E` (the consumer's domain event shape). */
+declare function sseHub<E>(): SseHub<E>;
+/**
+ * Express an {@link SseHub} as a {@link Projection}. The projection's view is
+ * the latest emitted SSE event (or `null` before the first); `apply` maps each
+ * write-model update to an event via `toEvent` and emits it through `hub.emit`,
+ * so the SSE stream is driven by the SAME hub `sseHub()` returns — no API
+ * change for the `/sse` route (`hub.open()`) or any existing caller.
+ *
+ *   - `toEvent(msg, model)` returns the SSE event for this update, or `null` to
+ *     skip it (the view stays, nothing is emitted).
+ *   - `name`/`key` default to `"sse"`/`"main"`; override for a second SSE view.
+ *
+ * @example
+ *   const hub = sseHub<MyEvent>();
+ *   const registry = projectionRegistry<MyState, MyMsg>();
+ *   registry.register(sseProjection(hub, (msg) =>
+ *     msg?.type === "turn_done" ? { kind: "turn", ... } : null,
+ *   ));
+ *   driveProjections(registry, runtime); // SSE is now one projection
+ *   // /sse route unchanged:
+ *   return hub.open();
+ */
+declare function sseProjection<Model, Msg extends {
+    type: string;
+}, E>(hub: SseHub<E>, toEvent: (msg: Msg | null, model: Model) => E | null, id?: {
+    name?: string;
+    key?: string;
+}): Projection<Model, Msg, E | null>;
+/**
+ * Wire an {@link SseHub} to a runtime's semantic {@link AgentEvent} stream (#47).
+ * For each event `type` the runtime can emit, subscribes via `runtime.on` and
+ * pushes `toFrame(event)` at the hub (returning `null` skips that event). The
+ * runtime MUST have been built with `run(machine, { events: agentEvents() })`,
+ * which is what makes `on` deliver the `AgentEvent`s. Returns a cleanup that
+ * detaches every subscription.
+ *
+ * This is the runtime→SSE adapter expressed over the typed event channel: no
+ * `observe` firehose, no private-Msg coupling. `hub.open()` and every existing
+ * `sseHub` caller are unchanged — only the SOURCE of `hub.emit` moves from a
+ * hand-rolled Msg switch to `on`.
+ *
+ * @example
+ *   const hub = sseHub<MyFrame>();
+ *   const runtime = await run(machine, { ctx, events: agentEvents() }).ready;
+ *   const off = sseFromAgentEvents(runtime, hub, (e) =>
+ *     e.type === "RunDone" ? { kind: "done", output: e.output } : null,
+ *   );
+ *   // /sse route unchanged:
+ *   return hub.open();
+ */
+declare function sseFromAgentEvents<R, Frame>(runtime: {
+    on<K extends AgentEvent<R>["type"]>(type: K, handler: (event: Extract<AgentEvent<R>, {
+        type: K;
+    }>) => void): () => void;
+}, hub: SseHub<Frame>, toFrame: (event: AgentEvent<R>) => Frame | null): () => void;
+/**
+ * What the consumer supplies to {@link createAgentHost} — the domain mappings,
+ * nothing of the wiring. `Stage`/`P`/`O`/`R` are the agent slice's type
+ * parameters (the consumer names them once); `Frame` is its SSE event shape.
+ * `C`/`U`/`Ctx` are the machine's own Cmd/Sub/Ctx — inferred from
+ * `buildMachine` at the `createAgentHost` call site (never name them by hand;
+ * an erased `any` here cost consumers all checking on this layer — #278).
+ */
+interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown> {
+    /**
+     * Build the wired agent machine. Called once per host build (per activation),
+     * AFTER the previous runtime — if any — was torn down. The consumer wires its
+     * per-tool interpret here (`agent.toMachine({ toolInterpret })`).
+     */
+    readonly buildMachine: () => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, C, U, Ctx>;
+    /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
+    readonly store: Store<AgentState<Stage, P, O, R>>;
+    /** The Ctx the machine threads to its interpret cells — checked against `buildMachine`'s. */
+    readonly ctx: Ctx;
+    /**
+     * The run-terminality predicate (#46) — what makes `result()` first-class.
+     * Defaults to the agent's own terminal phases (`done` / `failed`).
+     */
+    readonly terminal?: (state: AgentState<Stage, P, O, R>) => boolean;
+    /**
+     * Map one semantic {@link AgentEvent} to the consumer's SSE frame, or `null`
+     * to skip it. This is the ONLY place the consumer touches the SSE seam — the
+     * host owns the subscription wiring (`sseFromAgentEvents`) and the hub.
+     */
+    readonly toSseFrame: (event: AgentEvent<R>) => Frame | null;
+    /** Clock injected for `autoBoot` (the host's only boot clock read). */
+    readonly now?: () => number;
+}
+/**
+ * The assembled host: the runtime cell + the SSE hub + the framework test seam,
+ * owned ONCE. A DO holds one `AgentHost` and delegates to it; its own surface
+ * shrinks to the domain (the gateway, the WS bridge, the command-send mapping).
+ *
+ * @typeParam Stage Pipeline stage type.
+ * @typeParam P     Brain-call purposes.
+ * @typeParam O     Per-purpose outputs (bound to {@link AgentTurn}).
+ * @typeParam R     Tool result type.
+ * @typeParam Frame The consumer's SSE event shape.
+ */
+interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame> {
+    /**
+     * Get (or build) the booted runtime. Build-once-boot-once: the first call
+     * builds the machine, wires SSE off the semantic event stream, awaits the boot
+     * gate, runs the `autoBoot` re-fire for a rehydrated suspended run, and caches
+     * the booted `Runtime`; subsequent calls return the cached handle. The single
+     * assembly every consumer used to hand-roll in `getRuntime()`.
+     */
+    runtime(): Promise<Runtime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, AgentEvent<R>>>;
+    /**
+     * The agent's lifecycle status (#49) — the ONE typed channel a consumer reads
+     * instead of re-deriving `run.phase` / `awaiting` by hand. Ensures the runtime
+     * is built + boot-reconciled first. Replaces the per-consumer `isSuspended` /
+     * `runPhase` test methods (read `status().kind`).
+     */
+    status(): Promise<AgentStatus<Stage>>;
+    /**
+     * The run's terminal State (#46), or `undefined` while in flight. Read the
+     * run's product off it (e.g. `result()?.output`). Replaces the per-consumer
+     * `verdict` plumbing's source. Ensures the runtime is built first.
+     */
+    result(): Promise<AgentState<Stage, P, O, R> | undefined>;
+    /**
+     * The SSE hub — the route (`host.sse.open()`) AND the test seam
+     * (`host.sse.register(sink)`). The host drives `hub.emit` off the semantic
+     * event stream; the consumer never touches it except to open / register.
+     */
+    readonly sse: SseHub<Frame>;
+    /**
+     * Tear down the cached runtime (drain its tail via `stop()`, drop the handle)
+     * so the next `runtime()` rebuilds from storage. The framework `settle` test
+     * seam, owned once.
+     */
+    reset(): Promise<void>;
+}
+/**
+ * Build an {@link AgentHost} from the consumer's domain mappings. Owns the
+ * runtime+events+autoBoot assembly and the framework test seam — the wiring
+ * issue #53 had every consumer re-write.
+ *
+ * @example
+ *   const host = createAgentHost<Stage, Purpose, Outputs, ClientResult, SseEvent>({
+ *     buildMachine: () => agent.toMachine<Ctx>({ toolInterpret }),
+ *     store: doStore(storage, parse),
+ *     ctx,
+ *     toSseFrame: (e) =>
+ *       e.type === "ToolSettled" ? { kind: "result", ...} :
+ *       e.type === "TurnSettled" && e.turn.toolCalls.length === 0
+ *         ? { kind: "verdict", verdict: e.turn.content } :
+ *       e.type === "RunDone" ? { kind: "phase", phase: "done" } : null,
+ *   });
+ *   // route:   return host.sse.open();
+ *   // start:   await (await host.runtime()).dispatch({ type: "agent_start", ... });
+ *   // test:    (await host.status()).kind === "suspended"
+ */
+declare function createAgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown>(config: AgentHostConfig<Stage, P, O, R, Frame, C, U, Ctx>): AgentHost<Stage, P, O, R, Frame>;
+
+/**
+ * @demlik/tea/do — the idempotent-effect brick (the receiver/effect-side dedup).
+ *
+ * ## The half this closes (do NOT re-implement the ledger)
+ *
+ * The runtime's `stepDispatch` step order is SAVE-BEFORE-EFFECTS: state is
+ * persisted (`store.save(next)`) *before* its commands are interpreted
+ * (`packages/tea/src/index.ts` — "Save-before-effects is the hard ordering;
+ * tests pin it"). So a DO evicted after `save` but before an effect's result is
+ * folded RE-FIRES that effect on the next activation.
+ *
+ * `durable-effects.ts` (sibling) owns the SENDER half of this: the at-least-once
+ * `pendingEffectsLedger`, whose surviving owed entries `reissueSurvivingEffects`
+ * re-fires on activation. Its own header states the contract this file fulfils:
+ * "At-least-once ⇒ a confirmed-but-not-yet-persisted delivery WILL be re-sent
+ * after a crash, so the receiver must deduplicate by id" and "the receiver owns
+ * its own dedup." This module IS that receiver-side dedup — the piece that
+ * upgrades the ledger's at-least-once re-fire to **effectively-once at the
+ * external write**:
+ *
+ *   - ledger (`survivingEffects` / `reissueSurvivingEffects`) = at-least-once re-fire;
+ *   - this brick (`idempotentEffect` + `appliedEffects`)      = effect-side dedup
+ *   ⇒ together, effectively-once.
+ *
+ * It COMPLEMENTS the ledger; it does not re-implement it. The ledger keys owed
+ * effects by a monotonic `DeliveryId` (its private sender bookkeeping); this
+ * brick keys applied effects by a caller-supplied durable `EffectKey` (e.g.
+ * `(runId, violationId)`), because dedup identity must be stable across the
+ * re-fire — the same external write must resolve to the same key on every
+ * activation, which a fresh monotonic id cannot guarantee.
+ *
+ * ## The load-bearing rule (mirrors `durable-effects.ts`)
+ *
+ * The applied-marker set is a PURE FOLD over the same kind of event stream the
+ * actor already replays — it is **NOT** a separately-persisted side table:
+ *
+ *   - `effect_applied`   — `{ key }` ADDS the key to the applied set.
+ *   - `effect_forgotten` — `{ key }` REMOVES it (retention — see below).
+ *
+ * `foldApplied(events)` is `events.reduce(applyAppliedEvent, empty)` — the same
+ * fold shape `replay` / `foldLedger` use. This makes the marker live "alongside
+ * State (single authority)" for BOTH persistence modes:
+ *
+ *   - `doEventSourcedStore`: persist the two events into the SAME log it already
+ *     appends; folding the log on activation rebuilds the applied set for free.
+ *   - default snapshot `doStore`: carry the `AppliedEffects` set as a field of
+ *     the Model, round-tripped by the store's `serialize`/`parse` hooks (a `Set`
+ *     flattens under `JSON.stringify`, exactly the `Map` sharp edge #182), so it
+ *     is checkpointed with the rest of `S`.
+ *
+ * Either way the marker is folded/snapshotted with State, never a side channel.
+ *
+ * ## Ordering — why the marker is recorded AFTER `fn` (at-least-once, not at-most)
+ *
+ * `run` invokes `fn` and only THEN yields the `effect_applied` event to persist.
+ * An eviction in the window between `fn` succeeding and that event being folded
+ * re-fires the effect (at-least-once) — correct, because recording the marker
+ * BEFORE `fn` would let a crash strand the marker with the write never made
+ * (at-most-once ⇒ a silently-dropped effect). Once the marker is folded, every
+ * subsequent re-fire of that key is a proven no-op: `fn` is not invoked again.
+ * The ledger guarantees the re-fire; this brick swallows the duplicate.
+ *
+ * ## Retention — pruning mirrors the ledger's confirm-removes-entry (not a new policy)
+ *
+ * An applied-marker is only needed while its effect can still re-fire. The
+ * ledger stops re-firing an effect once its `effect_confirmed` removes the owed
+ * entry — so at that same point the marker is dead weight and is pruned via
+ * `effect_forgotten` (`guard.forget(key)`), keeping the applied set bounded. This
+ * deliberately reuses the ledger's confirm-removes-entry retention shape rather
+ * than inventing a second policy (the #227 triage's one open question).
+ */
+
+/**
+ * The caller-supplied durable dedup identity for an effect — stable across the
+ * re-fire (e.g. `` `${runId}:${violationId}` ``). Unlike the ledger's monotonic
+ * `DeliveryId`, it is chosen by the domain so the SAME external write resolves
+ * to the SAME key on every activation.
+ */
+type EffectKey = string;
+/** An effect keyed `key` has been APPLIED. Adds `key` to the set when folded. */
+interface EffectApplied extends Cmd<"effect_applied"> {
+    readonly key: EffectKey;
+}
+/**
+ * An applied-marker is no longer needed (its effect can no longer re-fire, e.g.
+ * its ledger entry was confirmed) and may be pruned. Removes `key` when folded.
+ */
+interface EffectForgotten extends Cmd<"effect_forgotten"> {
+    readonly key: EffectKey;
+}
+/** The event union the applied-marker set folds over. */
+type AppliedEffectsEvent = EffectApplied | EffectForgotten;
+/** The set of keys whose effect has been applied. A pure fold result. */
+type AppliedEffects = ReadonlySet<EffectKey>;
+/** The empty applied set — the fold's seed (a fresh actor has applied nothing). */
+declare function emptyApplied(): AppliedEffects;
+/**
+ * Apply ONE event — the reducer at the heart of the fold.
+ *
+ *   - `effect_applied`   → add `key` (a duplicate add is a no-op — a re-fired
+ *     already-applied key tolerated by at-least-once).
+ *   - `effect_forgotten` → remove `key` (a no-op if already absent).
+ *
+ * Pure: returns a NEW set on change, never mutates the input — so folding the
+ * same events twice (live and post-eviction) yields equal results.
+ */
+declare function applyAppliedEvent(applied: AppliedEffects, event: AppliedEffectsEvent): AppliedEffects;
+/**
+ * THE FOLD. Rebuild the applied set from an event stream — the same fold shape
+ * `replay`/`foldLedger` use. After a simulated eviction this is called over the
+ * persisted events and yields a set equal to the never-evicted one, because a
+ * pure fold over identical input is identical. This is what proves "no side
+ * table": the set is `events` reduced, nothing more.
+ */
+declare function foldApplied(events: Iterable<AppliedEffectsEvent>): AppliedEffects;
+/** Has this key's effect already been applied (folded into the set)? */
+declare function isApplied(applied: AppliedEffects, key: EffectKey): boolean;
+/**
+ * A keyed external effect. `key` is the durable dedup identity; `fn` is the
+ * irreversible external write (HTTP write, DB upsert, finding/ticket publish).
+ */
+interface IdempotentEffect<A> {
+    readonly key: EffectKey;
+    readonly fn: () => Promise<A> | A;
+}
+/**
+ * Pair a durable `key` with an external effect `fn` — the brick's primary
+ * surface. Run it through {@link appliedEffects}'s guard; a re-fire whose key is
+ * already applied is a proven no-op (`fn` is not invoked a second time).
+ */
+declare function idempotentEffect<A>(key: EffectKey, fn: () => Promise<A> | A): IdempotentEffect<A>;
+/**
+ * The outcome of running a keyed effect through the guard. A boolean-discriminated
+ * union so the skipped arm cannot carry a (never-produced) `result`/`event`:
+ *
+ *   - `ran: true`  — first application: `fn` ran, `result` is its value, and
+ *     `event` is the `effect_applied` marker the caller MUST persist (fold into
+ *     State) so future re-fires are swallowed.
+ *   - `ran: false` — the key was already applied: `fn` was NOT invoked, the
+ *     duplicate is swallowed, and there is no new event to persist.
+ */
+type IdempotentOutcome<A> = {
+    readonly ran: true;
+    readonly key: EffectKey;
+    readonly result: A;
+    readonly event: EffectApplied;
+} | {
+    readonly ran: false;
+    readonly key: EffectKey;
+};
+/**
+ * A live guard over an applied-marker set. Mirrors `pendingEffectsLedger`'s
+ * recorder shape: it keeps an in-memory mirror folded from the same events the
+ * caller persists, so the dedup decision is available without a re-read.
+ *
+ *   - `run(effect)`   — apply-once: skip (no `fn`) if the key is already applied,
+ *     else await `fn` and yield the `effect_applied` event to PERSIST.
+ *   - `forget(key)`   — prune a marker once its effect can no longer re-fire;
+ *     yields the `effect_forgotten` event to PERSIST.
+ *   - `applied()`     — the current folded set.
+ *   - `isApplied(key)`— convenience membership test against the mirror.
+ */
+interface AppliedEffectsGuard {
+    run<A>(effect: IdempotentEffect<A>): Promise<IdempotentOutcome<A>>;
+    forget(key: EffectKey): {
+        readonly event: EffectForgotten;
+    };
+    applied(): AppliedEffects;
+    isApplied(key: EffectKey): boolean;
+}
+/**
+ * Build a live guard. `restore` rehydrates it after an eviction: pass the events
+ * read back from the log (or the applied set carried in the reloaded snapshot,
+ * as single-element `effect_applied` events) so the mirror reflects what was
+ * already applied. Omit `restore` for a fresh actor.
+ */
+declare function appliedEffects(restore?: {
+    readonly events?: Iterable<AppliedEffectsEvent>;
+}): AppliedEffectsGuard;
+
+/**
+ * @demlik/tea/do — generic hibernatable PRESENCE + BROADCAST for a NATIVE
+ * (non-agent) Durable-Object grain.
+ *
+ * ## The gap this fills
+ *
+ * `./host` ships `acceptCommandSocket` / `acceptDurableCommandSocket` /
+ * `broadcast` / `broadcastHibernatable`, but those are framed for — and live
+ * alongside — the LLM-agent **deferred-tool gateway** (`createAgentHost`): the
+ * socket is "the command-runner socket", the frame is "a command", and the
+ * fan-out is the agent's `sendCommand` loop. A plain realtime grain — a game
+ * room, a presence list, a collab document — does not have an agent, a gateway,
+ * or commands. It just wants to accept hibernatable client sockets and fan a
+ * frame out to whoever is connected. Today every such grain (vortex's
+ * `ArenaGrain`, #162) hand-rolls the same `ctx.acceptWebSocket(server)` +
+ * `for (const ws of ctx.getWebSockets()) ws.send(...)` boilerplate (#181).
+ *
+ * This module lifts exactly that, decoupled from the agent host:
+ *
+ *   - {@link broadcastFrame} — the fan-out, with the **socket set as the input**
+ *     (not a `ctx`), so it is a pure function testable with fake sockets and
+ *     reusable over any iterable (`ctx.getWebSockets()`, a filtered subset, a
+ *     test array). It serializes once, sends to every OPEN socket, and skips a
+ *     closed/errored one — returning a {@link BroadcastReport} count rather than
+ *     swallowing the skip silently (errors are data).
+ *   - {@link registerHibernatableSocket} — register an already-created server
+ *     socket on the DO via the Cloudflare **Hibernation API**
+ *     (`ctx.acceptWebSocket`), optionally tagging it and persisting a
+ *     per-socket attachment that survives eviction. Pure over the `ctx` +
+ *     socket seam, so the registration logic is testable with fakes.
+ *   - {@link acceptPresenceSocket} — the full upgrade: build the
+ *     `WebSocketPair`, register the server end, and return the `server` socket
+ *     plus the 101 upgrade `Response`. The one piece that touches the
+ *     runtime-only `WebSocketPair` (so it is exercised by type, not by a unit
+ *     test without workerd) — the registration it delegates to *is* unit-tested.
+ *   - {@link presenceCount} — the live connection count off `ctx.getWebSockets`,
+ *     the trivial roster-size lift a presence grain reaches for.
+ *
+ * It is transport/Msg-agnostic: `frame` is `unknown` (JSON-serialized by
+ * default, or via a caller `serialize`), and nothing here references an agent,
+ * a gateway, a Sub, or a Msg. It is ADDITIVE — `./host`'s agent-coupled
+ * helpers keep working untouched for the agent consumer.
+ */
+/**
+ * The minimal "send a string frame" surface {@link broadcastFrame} needs. A real
+ * Cloudflare `WebSocket` satisfies it structurally (its `send` accepts a string
+ * and it carries a numeric `readyState`), so `ctx.getWebSockets()` flows in
+ * directly; a test supplies a fake with just `send` (and optionally
+ * `readyState`).
+ *
+ * `readyState` is OPTIONAL: when present and not {@link WS_READY_STATE_OPEN},
+ * the socket is skipped WITHOUT calling `send`; when absent, `send` is attempted
+ * and a throw is caught (a fake that models only liveness via a throwing `send`
+ * needs no `readyState`).
+ */
+interface PresenceSocket {
+    send(message: string): void;
+    readonly readyState?: number;
+}
+/**
+ * The Hibernation slice of `DurableObjectState` a presence grain needs — the
+ * accept that hands the socket to the runtime (surviving eviction) and the
+ * getter that repopulates the live set after a wake. A real `DurableObjectState`
+ * satisfies this structurally; a test supplies a fake (no live Workers runtime
+ * needed to exercise the accept/registry seam).
+ */
+interface PresenceCtx {
+    acceptWebSocket(ws: WebSocket, tags?: string[]): void;
+    getWebSockets(tag?: string): WebSocket[];
+}
+/**
+ * The OPEN `readyState` value (`WebSocket.READY_STATE_OPEN` in the Cloudflare
+ * runtime). Named here so {@link broadcastFrame} can skip a non-open socket
+ * without referencing the runtime constant (keeping the fold pure + testable).
+ */
+declare const WS_READY_STATE_OPEN = 1;
+/**
+ * What a {@link broadcastFrame} fan-out did, surfaced rather than swallowed:
+ * `sent` is the number of sockets the frame reached; `skipped` is the number
+ * passed over (not OPEN, errored on `send`, or the `except` socket). A caller
+ * can log or assert these — a silent fan-out hides a room going dark.
+ */
+interface BroadcastReport {
+    readonly sent: number;
+    readonly skipped: number;
+}
+/** Optional knobs for {@link broadcastFrame}. */
+interface BroadcastOptions<S extends PresenceSocket> {
+    /**
+     * A socket to exclude from the fan-out — typically the sender, so a collab /
+     * chat frame is not echoed back to its originator. Compared by identity.
+     */
+    readonly except?: S;
+    /**
+     * How to turn `frame` into the wire string. Defaults to `JSON.stringify`.
+     * Override for a non-JSON wire format (e.g. a pre-encoded string passthrough).
+     */
+    readonly serialize?: (frame: unknown) => string;
+}
+/**
+ * Serialize `frame` ONCE and send it to every OPEN socket in `sockets`, skipping
+ * any that is closed, errors on `send`, or is the `except` socket. The socket
+ * set is the INPUT (not a `ctx`), so this is a pure function: pass
+ * `ctx.getWebSockets()` in a live grain, a filtered subset for a targeted
+ * fan-out, or a fake array in a test.
+ *
+ * Skip semantics (a dead socket never crashes the broadcast):
+ *   - `readyState` present and not {@link WS_READY_STATE_OPEN} → skipped, `send`
+ *     not called;
+ *   - `send` throws (a socket closing mid-fan-out) → skipped, the throw is
+ *     caught (the close lifecycle reaps it);
+ *   - the `except` socket → skipped.
+ *
+ * Returns a {@link BroadcastReport} of `{ sent, skipped }` — the skip is data,
+ * not silence.
+ */
+declare function broadcastFrame<S extends PresenceSocket>(sockets: Iterable<S>, frame: unknown, options?: BroadcastOptions<S>): BroadcastReport;
+/** Optional knobs for {@link registerHibernatableSocket} / {@link acceptPresenceSocket}. */
+interface RegisterOptions<A> {
+    /**
+     * Hibernation tags for the socket — the same strings `ctx.getWebSockets(tag)`
+     * filters on, so a grain can fan out to a subset (e.g. a team, a channel).
+     */
+    readonly tags?: readonly string[];
+    /**
+     * A per-socket value to persist via `server.serializeAttachment` so it
+     * survives DO eviction (e.g. the player/session id the grain re-reads in
+     * `webSocketMessage`/`webSocketClose`). Omitted ⇒ no attachment written.
+     */
+    readonly attachment?: A;
+}
+/**
+ * The subset of `WebSocket` {@link registerHibernatableSocket} writes to — the
+ * attachment serializer. A real server `WebSocket` satisfies it; a test supplies
+ * a fake that records the serialized attachment.
+ */
+interface AttachableSocket {
+    serializeAttachment(value: unknown): void;
+}
+/**
+ * Register an already-created `server` socket on the DO via the Cloudflare
+ * **Hibernation API**: `ctx.acceptWebSocket(server, tags)` hands the socket to
+ * the runtime (it survives eviction and re-delivers inbound frames to the DO's
+ * `webSocketMessage` lifecycle method), and — when an `attachment` is supplied —
+ * persists it via `server.serializeAttachment` so it survives the wake.
+ *
+ * Pure over the `ctx` + socket seam (no `WebSocketPair` construction), so the
+ * registration logic — that accept is called with the right tags, that the
+ * attachment is serialized iff present — is unit-testable with fakes.
+ * {@link acceptPresenceSocket} is the thin wrapper that also builds the pair.
+ */
+declare function registerHibernatableSocket<S extends AttachableSocket, A>(ctx: PresenceCtx, server: S, options?: RegisterOptions<A>): void;
+/** What {@link acceptPresenceSocket} hands back: the live server end (to send
+ *  initial frames on) and the 101 upgrade `Response` (to return from `fetch`). */
+interface PresenceUpgrade {
+    /** The server end of the pair — send the welcome / initial snapshot on it. */
+    readonly server: WebSocket;
+    /** The 101 Switching-Protocols upgrade response carrying the client end. */
+    readonly response: Response;
+}
+/**
+ * Accept a client WebSocket upgrade on a native DO and register it for
+ * hibernation. Builds the `WebSocketPair`, registers the server end via
+ * {@link registerHibernatableSocket} (tags + optional attachment), and returns
+ * the `server` socket plus the 101 upgrade {@link PresenceUpgrade.response}.
+ *
+ * The caller's `fetch` collapses to: send any initial frames on `server`
+ * (welcome, current roster/snapshot), then `return upgrade.response`. This lifts
+ * the `new WebSocketPair()` + `ctx.acceptWebSocket` + `serializeAttachment` +
+ * `new Response(null, { status: 101, webSocket })` boilerplate a presence grain
+ * hand-rolls.
+ *
+ * NOTE: `WebSocketPair` is a runtime-only global (no workerd in unit tests), so
+ * this assembly is exercised by TYPE here; its registration seam is unit-tested
+ * via {@link registerHibernatableSocket}.
+ *
+ * @example
+ *   async fetch(request: Request): Promise<Response> {
+ *     if (request.headers.get("Upgrade") !== "websocket") {
+ *       return new Response("expected a websocket upgrade", { status: 426 });
+ *     }
+ *     const { server, response } = acceptPresenceSocket(this.ctx, {
+ *       attachment: { playerId },
+ *     });
+ *     server.send(JSON.stringify(welcome));
+ *     server.send(JSON.stringify(room.snapshot()));
+ *     return response;
+ *   }
+ */
+declare function acceptPresenceSocket<A>(ctx: PresenceCtx, options?: RegisterOptions<A>): PresenceUpgrade;
+/**
+ * The live connection count for a presence grain — `ctx.getWebSockets(tag)
+ * .length`, repopulated by the runtime after a wake. Pass a `tag` to count only
+ * the sockets registered under it. The trivial roster-size lift a presence /
+ * game grain reaches for (vortex's `connectionCount`).
+ */
+declare function presenceCount(ctx: PresenceCtx, tag?: string): number;
 
 /**
  * @demlik/tea/do — Durable Object adapter for `@demlik/tea`.
  *
- * Two exports drive the integration:
+ * The integration is built on ONE transport model and one durability primitive:
  *
  *   1. `doStore<S>(storage, parse, key?)` — `Store<S>` impl backed by
  *      `DurableObjectStorage`. JSON-stringifies on save, JSON-parses on load
@@ -15,31 +1682,46 @@ import { Store, SubId, Sub } from '../index.js';
  *      synchronously"). Shape mismatch is NOT a throw — `parse` returns
  *      `null` and the substrate boots fresh.
  *
- *   2. `doSubscribe<M, Ctx>()` — handler registry for the two DO-native sub
- *      types this package owns:
- *        - `do_alarm` — schedules a real DO alarm via `state.storage.setAlarm`;
- *          the cooperating DO's `alarm()` lifecycle method dispatches the sub's
- *          msg. Cleanup clears the alarm.
- *        - `do_ws`   — registers a WebSocket-id'd listener in a per-DO registry
- *          that the cooperating DO's `webSocketMessage()` consults. Cleanup
- *          deregisters.
- *
- * BOTH `do_alarm` and `do_ws` rely on the host DO cooperating: alarm and
- * webSocketMessage are DO lifecycle methods, not JS events the handler can
- * subscribe to from the outside. The cooperating DO must:
- *
- *   - Maintain a `Ctx` that exposes `state: DurableObjectState` AND the
- *     subscriber registries (`wsRegistry`, `alarmRegistry`). The handlers read
- *     from `ctx`.
- *   - Forward `alarm()` callbacks into the alarm registry by id, dispatching
- *     the registered msg.
- *   - Forward `webSocketMessage(ws, data)` callbacks into the ws registry,
- *     dispatching `sub.msg(data)` for matching `socketId`s.
- *
- * `src/test-worker.ts` is the canonical example of this cooperation. See
- * `test/README.md` for the convention.
+ *   2. `deferredGateway` + `createAgentHost` (from `./host`) — THE transport for
+ *      a DO-hosted agent. A `createAgent().toMachine()` machine owns exactly one
+ *      Sub type, `DeadlineSub` (the agent's own retry + watchdog timers); it has
+ *      no DO-native Sub variant to compose, and it needs none. The gateway owns
+ *      each deferred tool round-trip as a Promise the interpret cell awaits:
+ *        - Inbound WebSocket frames are bridged straight into `gateway.settle(...)`
+ *          from the DO's `webSocketMessage` lifecycle method — a direct dispatch,
+ *          NOT a Sub.
+ *        - The per-tool deadline is a `setTimeout` inside the gateway, NOT a DO
+ *          alarm.
+ *      One model: the transport lives outside the Sub system, bridged into
+ *      `dispatch` by the gateway. See `./host`'s module doc for the full rationale
+ *      and `.patterns/tea/durable-actors.md` for the host-layer north star.
+ *
+ * (Historical note: this module previously also shipped `do_ws` / `do_alarm`
+ * Subs + a `doSubscribe` registry. Because `toMachine` fixes the agent machine's
+ * Sub type to `DeadlineSub`, those Subs could never union into an agent host's
+ * Sub set — they were structurally unusable by the flagship consumer and had no
+ * callers. They were dropped in favor of the gateway as the single transport.)
  */
 
+/**
+ * Options for {@link doStore}. Mirrors the optional-bag shape
+ * `doEventSourcedStore` already uses for its `parse`/`keys`, so the two DO
+ * stores read alike.
+ */
+interface DoStoreOptions<S> {
+    /** Storage key the snapshot cell lives at. Defaults to `@@state`. */
+    readonly key?: string;
+    /**
+     * The serialize half of the boundary (#182) — the INVERSE of `doStore`'s
+     * `parse`. Maps the live `S` to a JSON-safe carrier before `JSON.stringify`,
+     * so a Model holding a `Map`/`Set`/`Date` (which `JSON.stringify` would
+     * silently flatten) round-trips: `parse` reconstructs the rich `S` from the
+     * carrier on load. Omit for a plain-JSON Model (the identity default — the
+     * `Record`-not-`Map` constraint, unchanged). When present, `parse` MUST
+     * accept whatever `serialize` produces.
+     */
+    readonly serialize?: (state: S) => unknown;
+}
 /**
  * `Store<S>` over `DurableObjectStorage`.
  *
@@ -62,74 +1744,23 @@ import { Store, SubId, Sub } from '../index.js';
  * behavior in `init`/`update`. After this, the boundary parse rejects the
  * old shape (returns null) and the DO boots fresh, picking up its new
  * schema from the next dispatch onward.
- */
-declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, key?: string): Store<S>;
-/**
- * A DO alarm sub: fires `msg` at `firesAt` (epoch ms). The substrate diffs
- * subs by `id`; same id across transitions = same alarm. To reschedule, emit
- * a DIFFERENT id (e.g., `audit-timeout-v2`).
- */
-type DoAlarmSub<M> = {
-    id: SubId;
-    type: "do_alarm";
-    firesAt: number;
-    msg: M;
-};
-/**
- * A DO WebSocket sub: routes incoming messages on `socketId` through
- * `sub.msg(data)` to dispatch.
- */
-type DoWsSub<M> = {
-    id: SubId;
-    type: "do_ws";
-    socketId: string;
-    msg: (data: string) => M;
-};
-type DoSub<M> = DoAlarmSub<M> | DoWsSub<M>;
-type AssertDoSubIsSub<T extends Sub = DoSub<unknown>> = T;
-/**
- * Registry of pending alarm dispatches keyed by sub `id`. The cooperating DO's
- * `alarm()` lifecycle method drains this and dispatches each msg.
- *
- * One alarm-queue cell at a time per DO (DO has exactly one alarm slot). We
- * still key by `id` so multiple alarm subs scheduled in the same reconcile
- * pass don't clobber each other — the earliest `firesAt` wins (DO native
- * behavior) and `alarm()` drains everything due by the fire time.
- */
-type DoAlarmRegistry<M> = Map<string, {
-    firesAt: number;
-    msg: M;
-}>;
-/**
- * Registry of WebSocket message subscribers keyed by sub `id`. The cooperating
- * DO's `webSocketMessage(ws, data)` consults this and dispatches
- * `sub.msg(data)` for entries matching the incoming `socketId`.
- */
-type DoWsRegistry<M> = Map<string, {
-    socketId: string;
-    msg: (data: string) => M;
-}>;
-/**
- * Minimum shape a cooperating DO must put on its `Ctx` for `doSubscribe`
- * handlers to wire up. Users may extend with anything else they like.
- */
-interface DoSubscribeCtx<M> {
-    state: DurableObjectState;
-    alarmRegistry: DoAlarmRegistry<M>;
-    wsRegistry: DoWsRegistry<M>;
-}
-/**
- * Build the `subscribe` handler registry for `do_alarm` and `do_ws` subs.
  *
- * Returned object shape matches `Machine#subscribe`'s `[K in U['type']]:
- * (sub, ctx, dispatch) => () => void` contract for `U = DoSub<M>`.
+ * Serialization sharp edge (#182): `save` JSON-serializes the Model, and
+ * `JSON.stringify` does NOT survive a `Map`/`Set`/`Date` (a `Map` stringifies
+ * to `{}`, silently losing every entry). A Model that wants a `Map` (the
+ * natural "roster keyed by id") therefore supplies a `serialize` hook — the
+ * INVERSE of `parse` — so the boundary owns both directions: `serialize` turns
+ * the live `S` into a JSON-safe carrier on the way out, `parse` reconstructs
+ * the rich `S` from that carrier on the way back in. They are a matched pair:
+ * `parse(JSON.parse(JSON.stringify(serialize(state))))` must round-trip to a
+ * value equal to `state`. Omit `serialize` and the Model must stay plain-JSON
+ * (the `Record`-not-`Map` constraint the default imposes, unchanged).
  *
- * Generic `Ctx` is user-defined and must extend `DoSubscribeCtx<M>` so handlers
- * can reach `state.storage`, `alarmRegistry`, and `wsRegistry`.
+ * @param parse - boundary parse, the deserialize half (`unknown -> S | null`).
+ * @param keyOrOptions - either the storage key (legacy positional form,
+ *   defaults to `@@state`) or a {@link DoStoreOptions} bag carrying `key`
+ *   and/or the `serialize` hook. A bare string is treated as `{ key }`.
  */
-declare function doSubscribe<M, Ctx extends DoSubscribeCtx<M>>(): {
-    do_alarm: (sub: DoAlarmSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-    do_ws: (sub: DoWsSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
-};
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, keyOrOptions?: string | DoStoreOptions<S>): Store<S>;
 
-export { type AssertDoSubIsSub, type DoAlarmRegistry, type DoAlarmSub, type DoSub, type DoSubscribeCtx, type DoWsRegistry, type DoWsSub, doStore, doSubscribe };
+export { type AgentHost, type AgentHostConfig, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferredGateway, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionId, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };