@helipod/client 0.1.0

package/dist/client-mJZjEkhK.d.ts

@@ -0,0 +1,1144 @@
+import { JSONValue, Value } from '@helipod/values';
+import { ClientMessage, ServerMessage, MutationBatchEntry } from '@helipod/sync';
+import { a as OutboxStorage, O as OutboxEntry, c as OutboxEntryError, d as OutboxEntryStatus } from './outbox-storage-C6VHkXs9.js';
+
+/**
+ * `FunctionArgs`/`FunctionReturnType` — extract the typed args/return generics from a
+ * codegen-generated function reference (see `@helipod/codegen`'s `FUNCTION_REFERENCE_TYPE`,
+ * emitted verbatim into every app's `_generated/api.d.ts` as `FunctionReference<Type, Vis, Args,
+ * Returns>`). The `__args`/`__returns` fields are phantom — they exist purely at the type level
+ * (the actual runtime value behind e.g. `api.messages.send` is the untyped `anyApi` proxy from
+ * `./api.ts`) — so these generics operate structurally on any type carrying them, without this
+ * package importing the app's generated types.
+ *
+ * This is D10 (docs/superpowers/specs/2025-10-16-optimistic-updates-design.md): `returns`
+ * validators are now threaded through codegen to a real `Returns` type (`functions.ts`'s
+ * `returnsJson` -> `validatorToTsType` -> the `generate.ts` `returnsType` slot); a function
+ * without a `returns` declaration stays `any` (the documented gap — see the executor's
+ * `returnsJson` doc for the enforcement follow-on). Consumed by the typed optimistic-updates
+ * store and `useQuery`/`useMutation`/`useAction`.
+ */
+interface AnyFunctionReference<Args = any, Returns = any> {
+    readonly __args: Args;
+    readonly __returns: Returns;
+}
+/** The argument type a generated function reference expects (`any` if the function declares no `args`). */
+type FunctionArgs<FuncRef extends AnyFunctionReference> = FuncRef["__args"];
+/**
+ * The value a generated function reference resolves with (`any` if the function declares no
+ * `returns` — D10's documented gap; migrants add `returns` incrementally to narrow it).
+ */
+type FunctionReturnType<FuncRef extends AnyFunctionReference> = FuncRef["__returns"];
+
+/**
+ * The runtime `api` — a proxy that turns `api.messages.list` into a function reference whose
+ * `__path` is `"messages:list"` (module path + function name). Typed as the generated `Api`
+ * type, this is what `useQuery(api.messages.list, …)` passes. Nested modules join with `/`
+ * (e.g. `api.admin.users.list` → `"admin/users:list"`).
+ */
+interface FunctionReference {
+    __path: string;
+}
+/**
+ * T5's type reconciliation (verdict §(b), flagged latent by T3's report): this package's own
+ * `FunctionReference` (`{ __path }`, above) and codegen's generated `Api` type (`FunctionReference<
+ * Type, Vis, Args, Returns>` — `__type`/`__visibility`/`__args`/`__returns`, NO `__path` in its
+ * TYPE) are structurally incompatible AT THE TYPE LEVEL ONLY. At runtime they are the exact same
+ * object — every app's `_generated/server.ts` does `export const api = anyApi as Api`, and
+ * `anyApi`'s `Proxy` answers any string property access, `__path` included. This union is the
+ * bridge: every public entry point that accepts a function reference (`client.query`/`mutation`/
+ * `subscribe`/`action`, `useQuery`/`useMutation`/`useAction`, `OptimisticLocalStore`) is typed
+ * against `AnyFunctionRef` (or overloaded across its two members) so a generated typed `api` value
+ * compiles wherever the client's own untyped `anyApi` value already did.
+ */
+type AnyFunctionRef = FunctionReference | AnyFunctionReference<any, any> | string;
+declare function getFunctionPath(ref: AnyFunctionRef): string;
+/** The untyped api proxy; cast to your generated `Api` type at the import site. */
+declare const anyApi: unknown;
+
+/**
+ * Transports carry the sync protocol between the client and the engine. The client logic is
+ * transport-agnostic; pick `loopbackTransport` (in-process / embedded) or `webSocketTransport`
+ * (over the network) — the same `HelipodClient` runs on either.
+ */
+
+interface ClientTransport {
+    send(message: ClientMessage): void;
+    onMessage(listener: (msg: ServerMessage) => void): () => void;
+    /** Fires when the transport closes or errors (so the client can fail pending work / resync). */
+    onClose(listener: () => void): () => void;
+    /**
+     * Optional (T6): fires once per successful RECONNECT — never for the initial connect. A
+     * transport that never reconnects (e.g. `loopbackTransport`) simply doesn't implement this; the
+     * client treats it as absent (`transport.onReopen?.(...)`). Implemented by `webSocketTransport`
+     * so the client can replay `SetAuth`, resubscribe every live query, and flush unsent mutations
+     * against the fresh session.
+     */
+    onReopen?(listener: () => void): () => void;
+    close(): void;
+}
+/** Anything shaped like an embedded loopback connection. */
+interface LoopbackLike {
+    send(message: ClientMessage): unknown;
+    onMessage(listener: (msg: ServerMessage) => void): () => void;
+    close(): void;
+}
+declare function loopbackTransport(connection: LoopbackLike): ClientTransport;
+interface WebSocketTransportOptions {
+    /** Reconnect automatically after a disconnect, with exponential backoff + jitter. Default `true`
+     *  — `{ reconnect: false }` restores the old terminal-on-close behavior verbatim. */
+    reconnect?: boolean;
+    /** Base delay before the first reconnect attempt; doubles each subsequent attempt. Default `300`. */
+    initialBackoffMs?: number;
+    /** Reconnect backoff cap. Default `30_000` (~30s). */
+    maxBackoffMs?: number;
+    /** @internal test seam — how to construct the underlying `WebSocket`. Defaults to `new WebSocket(url)`. */
+    createWebSocket?: (url: string) => WebSocket;
+}
+/**
+ * Equal-jitter exponential backoff: half the exponential delay, plus up to another half at random
+ * — never zero (avoids a thundering-herd reconnect storm) and monotone-capped at `maxBackoffMs`.
+ * Exported so the schedule itself is directly unit-testable without simulating a WebSocket.
+ */
+declare function reconnectDelayMs(attempt: number, initialBackoffMs: number, maxBackoffMs: number, rand?: () => number): number;
+/**
+ * WebSocket transport over the platform `WebSocket` (browsers, Node 22+, Bun). Reconnects by
+ * default on disconnect — exponential backoff + jitter, capped ~30s (`{ reconnect: false }` opts
+ * out, preserving the old terminal-on-close contract exactly). `onClose` fires once per disconnect
+ * (so the client can run its close disposition — reject inflight, retain unsent, drop layers);
+ * `onReopen` fires once per successful RECONNECT, never for the very first connect, so the client
+ * knows when to replay `SetAuth`, resubscribe, and flush unsent mutations against the fresh session.
+ */
+declare function webSocketTransport(url: string, opts?: WebSocketTransportOptions): ClientTransport;
+
+/**
+ * S1 — the `MutationLog`. One entry per unconfirmed mutation, held in a Map whose iteration order
+ * is insertion order — which, because `requestId`s are assigned by a monotonically-incrementing
+ * counter (`client.ts`), IS the "requestId order" the reconciler replays surviving updates in
+ * (verdict §(c) event 2d). The entry carries the **serializable triple** `(requestId, udfPath,
+ * args)` from day one (verdict §(b)'s A1 amendment) so "the log is what a durable outbox later
+ * persists" is true instead of aspirational — the durable-offline slice backs S1 with IndexedDB
+ * without reshaping this record.
+ */
+
+/** A single unconfirmed mutation and its optimistic effect. Verbatim from verdict §(b). */
+interface PendingMutation {
+    /** Client-local id; rides the existing wire `requestId` field. Opaque string (kept opaque so a
+     *  future durable outbox can choose uuid vs monotone clientSeq without reshaping this record). */
+    requestId: string;
+    udfPath: string;
+    /** `(requestId, udfPath, args)` = the serializable triple. */
+    args: JSONValue;
+    /** The optimistic update closure. Looked up at replay, never serialized. Absent for a plain
+     *  (non-optimistic) mutation — such an entry holds no layer and only tracks in-flight status. */
+    update?: OptimisticUpdate;
+    /** Fixed at creation — feeds the deterministic `placeholderId()`/`now()` an updater calls (D2);
+     *  the SAME seed is reused on every replay so minted ids/timestamps are stable. (T5 consumes it.) */
+    seed: {
+        entropy: string;
+        now: number;
+    };
+    /** Query hashes the updater wrote to on its most recent run — which subscriptions its layer covers. */
+    touched: Set<string>;
+    status: {
+        type: "unsent";
+    } | {
+        type: "inflight";
+    } | {
+        type: "completed";
+        commitTs: number;
+        completedAt: number;
+    } | {
+        type: "parked";
+    };
+    /**
+     * Durable-outbox identity (verdict §(d), Task 2) — present ONLY when this `HelipodClient` was
+     * constructed with a durable `outbox`; a client without one never sets any of the fields below,
+     * so `entriesInOrder()` and the wire `Mutation` shape stay byte-identical to before this task for
+     * that path. `clientId`/`seq` ride the wire `Mutation`/`MutationBatchEntry` (`clientId`/`seq`,
+     * `@helipod/sync`'s `protocol.ts`) whenever an outbox is configured — carried for park-safety
+     * on every send, not just once the S4 swap is armed (see `client.ts#mutationMessage`).
+     */
+    clientId?: string;
+    seq?: number;
+    /** Global position across the WHOLE shared durable queue (every clientId sharing one outbox) —
+     *  the drain's FIFO key (T4 consumes it; T2 only assigns it). */
+    order?: number;
+    /** SHA-256 of the last `SetAuth` token ("anon" for none/empty) — stamped synchronously from a
+     *  cache `client.ts#setAuth` computes asynchronously (spec §(k)7: SubtleCrypto is async, enqueue
+     *  is sync, so the digest is computed ahead of time and merely read here). */
+    identityFingerprint?: string;
+    enqueuedAt?: number;
+    /** Flips `true` once this entry's `OutboxStorage.append()` has resolved. "Park eligibility
+     *  requires durability" (verdict §(d)): `delivery-policy.ts#closeDisposition` only parks an
+     *  `inflight` entry when this is `true` — a still-in-flight (unconfirmed) append rejects with
+     *  `MutationUndeliveredError` exactly as before this task existed. Always left falsy when no
+     *  outbox is configured. */
+    durable?: boolean;
+}
+
+/**
+ * S2 — the `LayeredQueryStore`. It splits what was a single `value` slot per subscription into a
+ * **`serverValue`** (written only by server ingest) and a **`composedValue`** (= ordered replay of
+ * the surviving optimistic updates over that base — what listeners and the cached first delivery
+ * see). Change detection is by **reference inequality**, exactly as convex-js does.
+ *
+ * The **byte-identity invariant** (the no-re-render binding): when NO surviving update touches a
+ * query, its `composedValue` must be the *same reference* as its `serverValue`, not merely
+ * deep-equal — so a client with zero optimistic updates behaves reference-for-reference like the
+ * pre-slice client and triggers no extra renders.
+ *
+ * `recompose` is the sole place composed values are (re)built. It is transactional per-updater:
+ * an updater that throws mid-run contributes NOTHING (its buffered writes are discarded) and is
+ * reported for the caller to drop — a mid-rebuild throw never leaves the composed store half-built.
+ */
+
+/**
+ * The writeable view of composed state an optimistic updater receives. Reads see the composed
+ * state as built so far (prior layers + this updater's own writes); writes stack on top.
+ *
+ * T5 layers the *public typed* `OptimisticLocalStore` (with `placeholderId(table)`/`now()` derived
+ * from the entry `seed`, and dev-mode `Object.freeze` on `getQuery` results) on top of this
+ * internal contract — this slice implements the read/write view; those three are additive.
+ */
+interface OptimisticStoreView {
+    getQuery(ref: FunctionReference | string, args?: Record<string, Value>): Value | undefined;
+    setQuery(ref: FunctionReference | string, args: Record<string, Value>, value: Value | undefined): void;
+    getAllQueries(ref: FunctionReference | string): Array<{
+        args: Record<string, Value>;
+        value: Value | undefined;
+    }>;
+}
+/** The optimistic update closure. `store` is a writeable composed view; `args` is the mutation's args. */
+type OptimisticUpdate = (store: OptimisticStoreView, args: Value) => void;
+type QueryListener = (value: Value) => void;
+/** Fires when a subscribed query throws server-side (its handler errored). */
+type QueryErrorListener = (error: string) => void;
+
+/**
+ * T5 — the public, typed `OptimisticLocalStore` (verdict §(b)). Wraps T4's internal, untyped
+ * `OptimisticStoreView` (the raw read/write composed-state view `LayeredQueryStore.recompose`
+ * threads through an updater) with the v1 API surface a `withOptimisticUpdate` closure actually
+ * sees:
+ *
+ *  - **Typed `getQuery`/`setQuery`/`getAllQueries`** — `Q`'s declared `__args`/`__returns` (a
+ *    codegen-generated `FunctionReference`) drive `args`/`value`'s types; the client's own untyped
+ *    `{ __path }` ref or a raw string path fall back to `Record<string, Value>`/`Value` (see
+ *    `RefArgs`/`RefReturn` below — the same fallback shape `api.ts`'s `AnyFunctionRef` bridges).
+ *  - **`placeholderId(table)`** — deterministic per (entry, table, call-ordinal): replaying the
+ *    SAME pending mutation (same `entry.seed`, verdict §(c) event 2d's rebuild) mints the SAME id
+ *    sequence, while two calls to `placeholderId("messages")` within ONE updater invocation are
+ *    ordinal-distinct, and two DIFFERENT entries (distinct `seed.entropy`) never collide. Built from
+ *    `entry.seed.entropy` — NOT `crypto.randomUUID()` (verdict D11's replay-purity rule; Convex's
+ *    own docs example is the footgun this API shape is designed to make structurally impossible to
+ *    reach for).
+ *  - **`now()`** — `entry.seed.now`, fixed at mutation creation, stable across every replay. NOT
+ *    `Date.now()` (same D11 rule).
+ *  - **dev-mode `Object.freeze`** on every value `getQuery`/`getAllQueries` hands back — Convex's
+ *    documented "mutating the returned value in place will corrupt the client's internal state"
+ *    footgun becomes an immediate `TypeError` in development (strict-mode ESM) instead of silent
+ *    corruption. Gated on `process.env.NODE_ENV !== "production"` (no existing dev/prod convention
+ *    was found in this package at T1 — this is the convention going forward) so a production build
+ *    pays no freeze cost.
+ */
+
+/** `Q`'s declared args if `Q` carries codegen's `__args`/`__returns`; else the untyped default —
+ *  covers the client's own `{ __path }` ref and a raw string path (mirrors `api.ts`'s `AnyFunctionRef`). */
+type RefArgs<Q> = Q extends AnyFunctionReference<infer A, any> ? A : Record<string, Value>;
+/** `Q`'s declared return type — same fallback rule as `RefArgs`. */
+type RefReturn<Q> = Q extends AnyFunctionReference<any, infer R> ? R : Value;
+/** The typed store an optimistic updater receives (verdict §(b)'s v1 API surface, verbatim). */
+interface OptimisticLocalStore {
+    getQuery<Q extends AnyFunctionRef>(ref: Q, args?: RefArgs<Q>): RefReturn<Q> | undefined;
+    setQuery<Q extends AnyFunctionRef>(ref: Q, args: RefArgs<Q>, value: RefReturn<Q> | undefined): void;
+    getAllQueries<Q extends AnyFunctionRef>(ref: Q): Array<{
+        args: RefArgs<Q>;
+        value: RefReturn<Q> | undefined;
+    }>;
+    /** Deterministic per (entry, table, call-ordinal) — see file doc. NOT `crypto.randomUUID()`. */
+    placeholderId(table: string): string;
+    /** Entry-creation time, stable across every replay. NOT `Date.now()`. */
+    now(): number;
+}
+/**
+ * T5 — the `optimisticUpdates` registry's updater shape (verdict §(d) "Reload and rendering",
+ * spec §(k)6). The SAME `(store, args) => void` contract `useMutation(...).withOptimisticUpdate`
+ * accepts, but with `args` untyped (`Value`): the registry maps ONE function type across every
+ * udfPath key (`Partial<Record<UdfPathOf<Api>, OptimisticUpdateFn>>` — codegen emits the `UdfPathOf`
+ * union of KEYS; there is no per-key Args inference threaded through a `Record` at this level, so
+ * the VALUE type stays single and generic). Consulted ONLY when a durable entry is hydrated after a
+ * reload (never for a live call — "call-site closure wins for the live call, the registry is
+ * consulted only at hydrate"). An updater here should tolerate `store.getQuery(...)` returning
+ * `undefined` (no persisted query baseline exists pre-reconnect — the documented
+ * `if (list === undefined) return` recipe, `docs/enduser/offline.md`).
+ */
+type OptimisticUpdateFn = (store: OptimisticLocalStore, args: Value) => void;
+/**
+ * Builds the typed store for ONE updater invocation. The per-table ordinal counter is created
+ * fresh here (a local `Map`, not carried on `seed`) — every call to this factory starts every
+ * table's ordinal back at 0, which is exactly what makes replaying the same entry (same `seed`)
+ * deterministic: the Nth `placeholderId("messages")` call within a run always gets the same id.
+ */
+declare function createOptimisticLocalStore(view: OptimisticStoreView, seed: {
+    entropy: string;
+    now: number;
+}): OptimisticLocalStore;
+
+/**
+ * Task 4 — the drain (verdict §(d) "Drain", `docs/dev/research/offline-outbox/verdict.md`). The
+ * state machine that turns the durable queue (`OutboxStorage`) into exactly-once server effects.
+ *
+ * Shape (verdict §(d)):
+ *  - **Web Locks leader** (`helipod:outbox:<origin>:<deployment>`) — probe `navigator.locks`,
+ *    single-tab fallback when it's absent. Locks are *efficiency*, not correctness: two drainers
+ *    double-sending is harmless because Plan A's exact-match receipts replay-ack the loser (verdict
+ *    §(d): "locks are efficiency; correctness is the records"). Mid-drain lock loss (the tab killed,
+ *    or `stop()` on close) → stop cleanly; the durable records make the successor safe (hazard 7).
+ *  - **Hydrate** the durable queue into the in-memory log under each entry's RECORDED `(clientId,
+ *    seq)` (cross-session entries a prior page-load left behind), then prune dead-clientId meta rows.
+ *  - **FIFO by persisted `order`**, sent as `MutationBatch` chunks (default 50 — repair 4, the
+ *    500-drain arithmetic in verdict §(a)/(h)); ONE unacked chunk in flight at a time.
+ *  - **Per-unit resolution** of each chunk's per-entry `MutationResponse`:
+ *      - `applied` → settle (resolve + dequeue) and advance; the layer drop is routed by `replayed` —
+ *        a replay (historical, predates this session's baseline) uses T3's unconditional
+ *        baseline-gated drop, a fresh first-ever apply (this session) uses the same-session
+ *        `onMutationSuccess` gate a direct-send gets, to stay flicker-free (review-caught, T4).
+ *      - coded (terminal) failure → default **skip-and-record**: the SERVER recorded the terminal
+ *        verdict, so the client settles the promise terminally and CONTINUES past it; the
+ *        `poisonPolicy: "pause"` option instead HALTS the drain and surfaces (verdict §(c) R5).
+ *      - codeless (transient/infra) failure → back off (a local mirror of the scheduler's
+ *        `computeBackoff`) and re-send FROM the failed unit.
+ *      - the **transient-stop chunk contract** (Plan A's server semantics, its E2E is the
+ *        reference): a transient failure STOPS the server mid-batch, so every unit AFTER it gets NO
+ *        response — those remain queued and re-send on the next chunk.
+ *  - **Identity gate per entry at flush**: an entry whose stored `identityFingerprint` no longer
+ *    matches the session's current one terminal-fails LOUDLY with `OFFLINE_IDENTITY_CHANGED`
+ *    (hazard 9) — a mutation queued as user A must never flush as user B.
+ *  - **Wakes**: on enqueue, on reconnect-after-baseline, and on an interval nudge — NEVER
+ *    `navigator.onLine` (hazard 13: it lies).
+ *
+ * The drain owns no promise callbacks and no wire types beyond `MutationBatch`/`MutationResponse`;
+ * every settlement routes back through `client.ts` via {@link DrainHost} so the T3 seam
+ * (`settleVerdict`'s primitives — resolve/reject, dequeue, the drop rule) is reused, not forked.
+ */
+
+type MutationResponse = Extract<ServerMessage, {
+    type: "MutationResponse";
+}>;
+/** How the drain treats a coded (terminal, server-recorded) mutation failure (verdict §(c) R5). */
+type PoisonPolicy = 
+/** DEFAULT — skip-and-record: settle the promise terminally and CONTINUE draining. The server
+ *  already recorded the verdict, so a restart can never un-skip it. */
+"skip"
+/** Halt the whole drain on the first coded failure and surface it (A's argument, honored as an
+ *  option, not the default). */
+ | "pause";
+declare function computeDrainBackoff(attempts: number, rng?: () => number): number;
+/** The default `MutationBatch` chunk size (verdict §(a)/(h) repair 4). */
+declare const DEFAULT_DRAIN_CHUNK_SIZE = 50;
+/** The default interval-nudge period — the backstop wake (verdict §(d): never `navigator.onLine`). */
+declare const DEFAULT_DRAIN_INTERVAL_MS = 5000;
+/** The one method the drain needs from `navigator.locks` — a minimal, structurally-fakeable seam.
+ *  `request(name, options, cb)` holds the named lock for the lifetime of `cb`'s returned promise
+ *  (exactly the real `LockManager.request` 3-arg contract). The callback's `lock` parameter mirrors
+ *  the real `LockGrantedCallback` shape (`null` under `{ifAvailable: true}` when the lock could not
+ *  be granted immediately) — declared optional so every existing zero-arg callback (`async () =>
+ *  {...}`) stays assignable unchanged; callers that DO need the availability signal (e.g.
+ *  `headless-drain.ts#isLockAvailable`) can read it with no cast. */
+interface OutboxLockManager {
+    request(name: string, options: {
+        signal?: AbortSignal;
+        mode?: "exclusive" | "shared";
+        ifAvailable?: boolean;
+    }, callback: (lock?: unknown) => Promise<unknown> | unknown): Promise<unknown>;
+}
+interface DrainHost {
+    readonly outbox: OutboxStorage;
+    /** This tab-session's current clientId (re-minted on `onClientReset`). */
+    currentClientId(): string | undefined;
+    /** The session's current identity fingerprint — the flush-time identity gate compares against it. */
+    currentFingerprint(): string;
+    /** The transport is up (not closed) — the drain never sends while down. */
+    transportOpen(): boolean;
+    /** A `ConnectAck` has proven server-side receipt dedup for this session (S4 armed) — the drain
+     *  never flushes before this, so it can never re-execute against an old/undedup'd server. */
+    isArmed(): boolean;
+    /** Drain-eligible entries (`unsent`/`parked`, durable, `clientId`+`seq` set), FIFO by `order`. */
+    drainable(): PendingMutation[];
+    /** Add a hydrated durable entry to the log under a FRESH requestId (idempotent by `(clientId,
+     *  seq)`). The persisted requestId was session-correlation only, so a fresh one avoids colliding
+     *  with this session's own requestId counter. */
+    addHydrated(entry: OutboxEntry): void;
+    /** Send the first-connect `Connect` handshake if one hasn't gone out on this connection yet
+     *  (idempotent) — the reload analog of T3's reopen handshake (verdict §(d): "the drain starts
+     *  only after the reconnect baseline Transition has been adopted"). */
+    ensureInitialHandshake(): void;
+    /** Flip an in-log entry's status (drain-owned transitions: `inflight` on flush, back to `unsent`
+     *  on a transient revert). */
+    setStatus(entry: PendingMutation, status: "inflight" | "unsent"): void;
+    /** Build the wire `MutationBatchEntry` for an in-log entry. */
+    batchEntry(entry: PendingMutation): MutationBatchEntry;
+    /** Send one `MutationBatch` chunk. */
+    sendBatch(entries: MutationBatchEntry[]): void;
+    /** applied/replayed settlement (verdict §(d) drop rule, T3's `settleVerdict` primitives): resolve
+     *  the awaiting promise (if any), dequeue the durable record, then drop the layer — routed by
+     *  `replayed`. A REPLAY (`replayed: true`, a resend whose commit predates this session's `Connect`)
+     *  drops unconditionally once the baseline is adopted (T3's rule — sound because the baseline
+     *  snapshot already renders it). A FRESH first-ever apply (`replayed` absent/false — the server
+     *  executed it for the first time, THIS session, `ts` genuinely after the baseline) must NOT drop
+     *  early: it needs the same same-session gated hold `onMutationSuccess` gives a direct-send, or the
+     *  layer disappears a frame before the row it represents actually renders (a flicker). */
+    settleApplied(requestId: string, value: Value | null, replayed: boolean, ts: number | undefined): void;
+    /** Terminal settlement: reject the awaiting promise (coded), dequeue, drop the layer. */
+    settleTerminal(requestId: string, code: string | undefined, message: string): void;
+    /** Resolves once the first post-`Connect` baseline Transition has been adopted (verdict §(d) —
+     *  the drain's send gate). Resolves immediately when no handshake is in flight. */
+    whenBaselineAdopted(): Promise<void>;
+}
+/** Terminal code for the flush-time identity gate (hazard 9). */
+declare const OFFLINE_IDENTITY_CHANGED = "OFFLINE_IDENTITY_CHANGED";
+/** The auth-refresh mutation's canonical udf path — mirrors `auth-client.ts`'s default `refreshPath`
+ *  convention (`"auth:refresh"`). A durable entry hydrated under this path is DROPPED at hydrate
+ *  time (see `hydrateOnce` below) rather than resent — defense-in-depth for a row a PRE-FIX client
+ *  version already durably enqueued, before `client.ts#mutation`'s `{transient: true}` escape hatch
+ *  existed. Replaying a refresh mutation is never safe: there is no live promise awaiter for the
+ *  mint result across a reload, and blindly resending a stale refresh token risks tripping the
+ *  session's reuse-detection and force-signing-out an honest user (`auth-client.ts`'s file doc,
+ *  `REFRESH_REUSED`). A fixed client never durably enqueues this path in the first place, so this
+ *  should only ever match a row a stale/pre-fix build left behind. */
+declare const AUTH_REFRESH_UDF_PATH = "auth:refresh";
+/** Terminal code stamped on a hydrate-time-dropped refresh entry — see {@link AUTH_REFRESH_UDF_PATH}. */
+declare const NON_REPLAYABLE_MUTATION_DROPPED = "NON_REPLAYABLE_MUTATION_DROPPED";
+interface OutboxDrainOptions {
+    /** The Web Locks lock name — `helipod:outbox:<origin>:<deployment>`. */
+    lockName: string;
+    /** `undefined` → probe `navigator.locks`; `null` → force single-tab; an object → use it (tests). */
+    locks?: OutboxLockManager | null;
+    poisonPolicy?: PoisonPolicy;
+    chunkSize?: number;
+    intervalMs?: number;
+    /** Injectable backoff (tests drive it deterministically); defaults to {@link computeDrainBackoff}. */
+    backoffMs?: (attempts: number) => number;
+    /** Fired once when `poisonPolicy: "pause"` halts the drain on a coded failure (surfacing). */
+    onPause?: (info: {
+        requestId: string;
+        udfPath: string;
+        code: string;
+    }) => void;
+}
+declare class OutboxDrain {
+    private readonly host;
+    private readonly lockName;
+    private readonly locksOption;
+    private readonly poisonPolicy;
+    private readonly chunkSize;
+    private readonly intervalMs;
+    private readonly backoffMs;
+    private readonly onPause?;
+    private started;
+    private leader;
+    private stopped;
+    private paused;
+    private hydrated;
+    /** The in-flight chunk: requestId → in-log entry. Non-null iff one unacked chunk is outstanding. */
+    private active;
+    /** Re-entrancy guard around `maybeDrainNext`'s `await whenBaselineAdopted()` (one flush at a time). */
+    private flushScheduling;
+    /** Consecutive transient-stop count — the backoff attempt number (reset on any forward progress). */
+    private transientAttempts;
+    private readonly abort;
+    private releaseLeadership?;
+    private intervalTimer?;
+    private backoffTimer?;
+    constructor(host: DrainHost, opts: OutboxDrainOptions);
+    /** Acquire leadership (Web Locks, or single-tab fallback) and, once leader, hydrate + drain. Safe
+     *  to call once; a no-op afterward. */
+    start(): void;
+    /** Stop cleanly (client close, or mid-drain lock loss). Releases leadership, cancels a pending
+     *  lock request, and clears every timer — the durable records make a successor leader safe. */
+    stop(): void;
+    /** Wake the drain (enqueue / reconnect-after-baseline / an explicit nudge). Deferred to a
+     *  microtask so a synchronous settling frame (e.g. a `ConnectAck` emitted right after reopen)
+     *  always settles its entries BEFORE the drain re-reads the queue. */
+    nudge(): void;
+    /** True iff `requestId` belongs to the drain's in-flight chunk — `client.ts` routes that unit's
+     *  `MutationResponse` here instead of down the direct-send path. */
+    handles(requestId: string): boolean;
+    /** The transport dropped (a reconnect-class close, NOT the client's `close()` — leadership and
+     *  the interval survive). The in-flight chunk's unresponded units will never get a response on
+     *  the new server session, so revert them to re-sendable and clear the chunk NOW — otherwise
+     *  `canDrain()`'s one-unacked invariant (`active === null`) would wedge the drain for the rest of
+     *  this tab session (no chunk would ever flush again, and every new mutation would queue behind
+     *  the stuck backlog until overflow). Called by `client.ts#onTransportClosed` BEFORE the
+     *  reconciler's S4 close rules run, so the reverted (`unsent`) units are simply retained by the
+     *  close disposition, promises pending, ready for the reconnect handshake + re-drain. A pending
+     *  transient-backoff timer is also cleared — the reconnect handshake re-drives the drain, and
+     *  `canDrain()` would no-op a stale timer against a closed transport anyway. */
+    onTransportClosed(): void;
+    /** True while an unacked chunk is in flight — `client.ts#hasOutboxBacklog` counts it so a new
+     *  `mutation()` enqueues BEHIND the chunk instead of direct-sending ahead of it (the FIFO rule:
+     *  "while the queue is non-empty, new mutations enqueue behind it"). A chunk's units are
+     *  `inflight`, which the unsent/parked backlog scan alone would miss when the chunk consumed the
+     *  entire backlog. */
+    get hasActiveChunk(): boolean;
+    /** @internal test/debug — the drain halted on a coded failure under `poisonPolicy: "pause"`. */
+    get isPaused(): boolean;
+    /** @internal test/debug — the drain currently holds leadership. */
+    get isLeader(): boolean;
+    /** Resume a `pause`d drain (T5 owns the app-facing retry surface; this is the mechanism). */
+    resume(): void;
+    private becomeLeader;
+    private startInterval;
+    /** Load the durable queue into the log (once), under recorded ids, then prune dead meta rows.
+     *  Only STILL-ACTIVE entries (`unsent`/`inflight`/`parked`) are hydrated into the log — a `failed`
+     *  entry left behind by a prior session is a terminal, accessor-only record (surfaced via
+     *  `pendingMutations()`/the constructor's `refireDurableFailures` R9 scan) and must never be
+     *  resurrected here as a fresh `unsent` log entry: `host.addHydrated` unconditionally stamps
+     *  `status: "unsent"` regardless of the persisted status, so hydrating a `failed` row verbatim
+     *  would render a phantom optimistic row for an already-dead mutation AND make it drainable again
+     *  (a resend of something the server/R9 already settled), on top of double-firing R9 alongside the
+     *  constructor's unconditional resume scan. Mirrors the same filter `mirrorFromStore`'s cross-tab
+     *  backstop applies (`client.ts`). */
+    private hydrateOnce;
+    /** Delete meta rows for clientIds with no live entries and that aren't the current session's — the
+     *  T1-flagged unbounded-tiny-rows gap (one dead row accrues per prior tab-session + every reset).
+     *  Capability-gated: a minimal `OutboxStorage` (a bare test double) may omit the two optional
+     *  methods, in which case pruning is simply skipped. */
+    private pruneDeadMeta;
+    private canDrain;
+    /** Flush the next chunk when eligible. The `flushScheduling` guard + the synchronous `this.active`
+     *  set (in `flushChunk`) keep exactly one chunk in flight across the `await` yield. */
+    private maybeDrainNext;
+    private flushChunk;
+    /** Route one unit's `MutationResponse` (only ever called for a requestId in the active chunk). */
+    onResponse(msg: MutationResponse): void;
+    private resolveResponseValue;
+    /** A unit settled (applied or coded-terminal): if the chunk is now empty, advance to the next. */
+    private onForwardProgress;
+    /** Revert every still-in-flight entry of the active chunk to `unsent` (re-sendable) and clear the
+     *  chunk — used by the transient-stop and pause paths. The units that got no response are exactly
+     *  those still in `active`. */
+    private revertActive;
+}
+
+/** Passed to the `onClientReset` callback (verdict §(d) Retention) when the server disowns this
+ *  client's mutation history on `ConnectAck{known: false}`. `unsentReEnqueued` counts the `unsent`
+ *  entries carried forward under the fresh clientId + NEW seqs; `parkedRejected` counts the
+ *  in-flight-at-disconnect entries rejected loudly with `OfflineClientResetError`. */
+interface ClientResetInfo {
+    oldClientId: string | undefined;
+    newClientId: string;
+    unsentReEnqueued: number;
+    parkedRejected: number;
+}
+/** T5 (R9): the `onMutationFailed` callback's payload — a terminal, server-recorded verdict for a
+ *  durable outbox entry the CURRENT session may have no live promise awaiter for (a hydrated
+ *  cross-reload entry, a retried one, or one discovered already-failed at construction — "resume"). */
+interface MutationFailedInfo {
+    clientId: string;
+    seq: number;
+    udfPath: string;
+    error: OutboxEntryError;
+}
+/** T5 (R9): one row of `client.pendingMutations()`/`usePendingMutations()` — a snapshot from the
+ *  DURABLE store (verdict §(d) "Observability"), not the in-memory reconciler log; `retry()`/
+ *  `dismiss()` are meaningful only when `status === "failed"` (a terminal, server-recorded verdict —
+ *  every other status is still in flight and simply isn't a `retry()`/`dismiss()` candidate) and are
+ *  harmless no-ops otherwise. */
+interface PendingMutationEntry {
+    readonly clientId: string;
+    readonly seq: number;
+    readonly udfPath: string;
+    readonly status: OutboxEntryStatus;
+    readonly enqueuedAt: number;
+    readonly error?: OutboxEntryError;
+    /** Re-enqueue this FAILED entry under a fresh `(clientId, seq)` — "never reuse a seq for a new
+     *  attempt" (verdict §(b)): the old seq's durable record IS its terminal verdict. No-op unless
+     *  `status === "failed"`. */
+    retry(): Promise<void>;
+    /** Permanently remove this FAILED entry from the durable store without retrying. No-op unless
+     *  `status === "failed"`. */
+    dismiss(): Promise<void>;
+}
+/** T5 (R9, hazard 2's client half): the queue-age/size advisory — cheap enough to poll before
+ *  surfacing a "you have offline changes that may be lost soon" banner ahead of Safari's 7-day
+ *  eviction cliff. `oldestEnqueuedAt`/`oldestAgeMs` are `undefined` for an empty (or unconfigured)
+ *  outbox. */
+interface PendingSummary {
+    count: number;
+    oldestEnqueuedAt: number | undefined;
+    oldestAgeMs: number | undefined;
+}
+/** T5 (R9): the one method `usePendingMutations()`'s cross-tab nudge needs from `BroadcastChannel` —
+ *  a minimal, structurally-fakeable seam (the same probe-and-fallback discipline as
+ *  `OutboxLockManager`, `./outbox-drain`). Real `BroadcastChannel`s satisfy this structurally. */
+interface OutboxBroadcastLike {
+    postMessage(message: unknown): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    close(): void;
+}
+/** T-crosstab (browser-ux spec Part A): the broadcast channel's payload becomes ADDITIVELY typed.
+ *  Today's bare `1` ("the message IS the nudge", see `notifyOutboxChange` below) stays a valid,
+ *  forward-compatible message forever — every listener still fires its `outboxChangeListeners` fan-out
+ *  on ANY payload shape first (`onmessage` below), unconditionally. These three shapes let a receiver
+ *  additionally MIRROR another tab's durable entries live, instead of merely re-reading on next poll:
+ *   - `enqueued` — posted after any durable-outbox-mutating write (append/dequeue/status change);
+ *     the receiver re-reads `loadAll()` and reconciles its mirrored set against it (the backstop).
+ *   - `settled` — posted by the drain leader right after an `applied` verdict; a mirroring tab holds
+ *     its layer `completed` and drops it only once ITS OWN feed observes `commitTs` (flicker-free).
+ *   - `failed` — posted by the drain leader right after a terminal verdict; a mirroring tab drops the
+ *     layer and fires its own R9 `onMutationFailed`/dev-loud default (no promise exists to reject).
+ *  A payload that isn't one of these three (including the legacy bare `1`, or anything malformed) is
+ *  simply not recognized by `isOutboxBroadcastMessage` below — nudge-only, mirrors nothing, throws
+ *  nothing. */
+type OutboxBroadcastMessage = {
+    kind: "enqueued";
+} | {
+    kind: "settled";
+    clientId: string;
+    seq: number;
+    commitTs: number;
+} | {
+    kind: "failed";
+    clientId: string;
+    seq: number;
+    code?: string;
+    message: string;
+};
+declare class HelipodClient {
+    private readonly transport;
+    private version;
+    private resyncing;
+    private closed;
+    private resumeSinceTs;
+    private readonly store;
+    private readonly reconciler;
+    /** Mutation promise callbacks, keyed by requestId — resolved/rejected here; layers live in the log. */
+    private readonly pendingMutationCallbacks;
+    private readonly pendingActions;
+    private readonly broadcastListeners;
+    private readonly disposeTransport;
+    private readonly disposeClose;
+    private readonly disposeReopen?;
+    private nextQueryId;
+    private nextRequestId;
+    /** The last token passed to `setAuth` (T6: replayed on reconnect). Unset until `setAuth` is
+     *  first called — a transport that never had auth set never sends a spurious `SetAuth` on reopen. */
+    private hasSetAuth;
+    private lastAuthToken;
+    /** Absent unless `opts.outbox` is configured — a client constructed without it behaves exactly
+     *  as before this seam existed (`outbox-storage.ts`'s file doc: "never touches this file's
+     *  runtime branches that matter"). */
+    private readonly outbox?;
+    /** Resolves once this tab-session's clientId is durably persisted (`mintIdentity`,
+     *  `outbox-storage.ts`) — ALWAYS a fresh clientId, never one reused from a prior session. Public
+     *  contract for tests/direct inspection; `mutation()` itself never awaits this (see
+     *  `outboxClientId`/`outboxNextSeq` below — the synchronous counterparts it actually reads). */
+    private readonly outboxIdentity?;
+    /** This tab-session's clientId, minted SYNCHRONOUSLY at construction (Task 2) — `mutation()` must
+     *  stay fully synchronous (T1's open concern), so it cannot await `outboxIdentity`'s async
+     *  `getMeta`/`setMeta` round-trip. Fed into `mintIdentity` via `opts.mintClientId` below so the
+     *  durable meta row names this SAME id. Set once, iff `opts.outbox` is configured; never reused
+     *  across a reload (a fresh `HelipodClient` always mints again). */
+    private outboxClientId?;
+    /** In-memory serial `seq` counter for `outboxClientId` (verdict §(d): "seqs minted serially
+     *  in-memory per tab"). Starts at 0 synchronously; `outboxIdentity`'s resolution only ever
+     *  reconciles it UPWARD (never re-hands-out a seq already allocated locally) for the
+     *  astronomically-unlikely colliding-clientId case `mintIdentity` itself guards against. */
+    private outboxNextSeq;
+    /** Monotonic per-tab counter for `OutboxEntry.order` — the drain's (T4) FIFO key across the
+     *  WHOLE shared queue (every clientId/tab). Seeded from wall-clock time so multiple tabs sharing
+     *  one outbox interleave in roughly chronological order; strictly increasing per call within
+     *  this tab regardless of clock resolution. Cross-tab total ordering is a best-effort aid to the
+     *  drain's efficiency, NOT a correctness requirement — "locks are efficiency; correctness is the
+     *  records" (verdict §(d) "Drain"). */
+    private outboxOrderCounter;
+    /** Cache of `identityFingerprint` (SHA-256 hex of the last `SetAuth` token, or `"anon"` for
+     *  none/empty) — see `setAuth()` below and spec §(k)7. Stamped synchronously onto every entry;
+     *  computed asynchronously (SubtleCrypto) whenever `setAuth` is called with a real token. */
+    private outboxFingerprint;
+    /** When true, a managed `createAuthClient` owns the outbox fingerprint (derived from the stable
+     *  `sessionId`, not the rotating token) — `setAuth`'s token-hash recompute is suppressed so
+     *  rotation never orphans queued offline mutations mid-drain (spec decision 9). The raw
+     *  `setAuth(token)` path (no `createAuthClient`) leaves this false and keeps token-hash
+     *  fingerprinting byte-for-byte unchanged. */
+    private sessionFingerprintActive;
+    /** The `session:<sessionId>` key whose SHA-256 is the active managed fingerprint — guards a stale
+     *  async digest from overwriting a newer session's fingerprint. */
+    private sessionFingerprintKey;
+    /** The S4 swap's capability flag (verdict §(d) "S4 swap, feature-detected") — flipped by
+     *  `setOutboxArmed()`, which T3's Connect handshake calls once a `ConnectAck` proves server-side
+     *  receipt dedup exists for this session. Defaults `false`: today's fail-fast, byte-for-byte,
+     *  whether or not an outbox is configured. */
+    private outboxArmed;
+    private readonly outboxMaxQueueSize;
+    /** The last `ConnectAck.deploymentId` seen — the same-timeline proof stamp (verdict §(g) hazard
+     *  15's client half). Surfaced via `getOutboxDeploymentId()`; also written into the durable meta
+     *  row so a future reload can compare timelines. Undefined until the first `ConnectAck`. */
+    private outboxDeploymentId?;
+    /** App callback fired once whenever a `ConnectAck{known: false}` resets this client's identity
+     *  (verdict §(d) Retention). Optional constructor config. */
+    private readonly onClientResetCallback?;
+    /** True while the Connect handshake is waiting for the first post-`Connect` baseline Transition
+     *  to be ADOPTED through S3 (verdict §(d) / spec decision 5 — "a NEW await"). While true, the
+     *  drop rule for `applied` cross-session entries is DEFERRED (queued in `outboxPendingDrops`) and
+     *  `whenBaselineAdopted()` (T4's drain gate) stays pending. */
+    private outboxAwaitingBaseline;
+    /** requestIds whose `applied`-verdict layer drop is deferred until the baseline is adopted (so the
+     *  drop is flicker-free — the baseline already renders the effect). Drained by `markBaselineAdopted`. */
+    private outboxPendingDrops;
+    /** Resolvers for in-flight `whenBaselineAdopted()` promises — settled together when the baseline
+     *  Transition adopts (or immediately, when a reopen had no live subscriptions to re-baseline). */
+    private outboxBaselineResolvers;
+    /** Whether a `Connect` handshake has already gone out on the CURRENT connection (reset at close).
+     *  Guards against a double-handshake when both the reopen path and the drain's first-connect path
+     *  could fire — the drain's `ensureInitialHandshake()` is a no-op once a reopen already sent one. */
+    private outboxConnectSent;
+    /** DLR Stage 2a — whether this connection has advertised `supportsQueryDiff` (reset at close). A
+     *  non-outbox client has no resume `Connect` to piggyback the capability on (an outbox client's
+     *  `buildConnectMessage` carries it), so it sends a minimal capability-only `Connect` before its
+     *  first subscribe. Without this the server never records the capability and every by-id sub falls
+     *  back to RERUN — correct, but the diff path never engages. */
+    private diffCapabilitySent;
+    /** The drain (Task 4) — the Web Locks leader that turns the durable queue into exactly-once server
+     *  effects. Present iff `opts.outbox` is configured; started at construction. */
+    private readonly outboxDrain?;
+    /** T5: the registry `mutation()` NEVER consults — only `addHydratedEntry` does, at hydrate time
+     *  (verdict §(d): "call-site closure wins for the live call; the registry is consulted only at
+     *  hydrate"). Plain string-keyed: a generated `UdfPathOf<Api>` union (`@helipod/codegen`) narrows
+     *  the caller's OWN object-literal keys; this package never imports that generated type. */
+    private readonly optimisticUpdates;
+    /** udfPaths already warned for a registry miss at hydrate — "one warn per udfPath" (spec §(k)6),
+     *  not once per missed ENTRY (a stale backlog of the same unregistered udfPath warns exactly once). */
+    private readonly optimisticUpdateMissWarned;
+    /** T5 (R9): fired for a terminal durable failure with no live promise awaiter THIS session (a
+     *  hydrated/retried entry, or one discovered already-failed at construction — "resume"). Never
+     *  fired for a failure a live `mutation()` caller's own rejected promise already delivered
+     *  (Lunora's `hadAwaiter` — no double notification for one failure). */
+    private readonly onMutationFailedCallback?;
+    /** T5 (R9): same-instance listeners for "the durable outbox changed" — `usePendingMutations()`'s
+     *  re-read trigger. Fired locally on every outbox-mutating op AND on an incoming cross-tab
+     *  `outboxBroadcast` message (unified into one path — a listener never needs to know which). */
+    private readonly outboxChangeListeners;
+    /** T5 (R9): the cross-tab nudge — `undefined` when no outbox is configured or the probe/injected
+     *  option resolved to nothing (single-tab observability still works via `outboxChangeListeners`). */
+    private readonly outboxBroadcast?;
+    /** T-crosstab: serializes `mirrorFromStore()` — a second call arriving while one is already
+     *  in-flight (a rapid burst of `enqueued` broadcasts) sets this bit instead of racing a second
+     *  `loadAll()`; the in-flight run loops once more on completion so the caller's freshest read is
+     *  never dropped. */
+    private mirrorInFlight;
+    private mirrorRerun;
+    constructor(transport: ClientTransport, opts?: {
+        gateTimeoutMs?: number;
+        outbox?: OutboxStorage;
+        outboxMaxQueueSize?: number;
+        onClientReset?: (info: ClientResetInfo) => void;
+        /** How a coded (terminal, server-recorded) mutation failure is handled during the drain
+         *  (verdict §(c) R5) — `"skip"` (default: skip-and-record + continue) or `"pause"` (halt). */
+        poisonPolicy?: PoisonPolicy;
+        /** The Web Locks manager for the drain leader — `undefined` probes `navigator.locks`, `null`
+         *  forces single-tab, an object is used directly (tests inject a fake). */
+        outboxLocks?: OutboxLockManager | null;
+        /** Distinguishes the drain's lock name per deployment (`helipod:outbox:<origin>:<deployment>`);
+         *  defaults to `"default"`. */
+        outboxDeployment?: string;
+        /** The drain's interval-nudge period (verdict §(d): never `navigator.onLine`). */
+        outboxDrainIntervalMs?: number;
+        /** The drain's `MutationBatch` chunk size (default 50). */
+        outboxChunkSize?: number;
+        /** Injectable backoff for the drain's codeless-retry path (tests drive it deterministically). */
+        outboxBackoffMs?: (attempts: number) => number;
+        /** Fired once when `poisonPolicy: "pause"` halts the drain (surfacing). */
+        onOutboxPause?: (info: {
+            requestId: string;
+            udfPath: string;
+            code: string;
+        }) => void;
+        /** T5: the durable-outbox registry — consulted ONLY when a durable entry is hydrated after a
+         *  reload (never for a live call). Plain string-keyed here; a generated `UdfPathOf<Api>`
+         *  (`@helipod/codegen`) narrows an app's own object literal at the call site. */
+        optimisticUpdates?: Partial<Record<string, OptimisticUpdateFn>>;
+        /** T5 (R9): fired for a terminal durable failure with no live promise awaiter this session. */
+        onMutationFailed?: (info: MutationFailedInfo) => void;
+        /** T5 (R9): the cross-tab nudge for `usePendingMutations()` — `undefined` probes the ambient
+         *  `BroadcastChannel`, `null` disables it (single-tab observability only), an object is used
+         *  directly (tests inject a fake). */
+        outboxBroadcast?: OutboxBroadcastLike | null;
+    });
+    /** The origin component of the drain's Web Locks name — `location.origin` in a browser, a stable
+     *  fallback elsewhere (Node/SSR share one origin; correctness is the records, not the lock). */
+    private originTag;
+    /** @internal This tab-session's durable outbox identity, or `undefined` when no `outbox` was
+     *  configured. Exposed for direct testing of the identity-mint behavior; `mutation()` itself
+     *  reads the synchronous `outboxClientId`/`outboxNextSeq` counterparts, never this promise
+     *  (see the field doc above `outboxClientId`). */
+    getOutboxIdentity(): Promise<{
+        clientId: string;
+        nextSeq: number;
+    }> | undefined;
+    /** @internal T3's Connect handshake calls this once a `ConnectAck` proves server-side receipt
+     *  dedup exists for this session — see verdict §(d) "S4 swap, feature-detected". Before that (no
+     *  outbox configured, a fresh/pre-handshake session, or an old server that never sends
+     *  `ConnectAck`), `close()` behaves exactly as it always has: today's fail-fast, byte-for-byte. */
+    setOutboxArmed(armed: boolean): void;
+    /**
+     * Subscribe to a reactive query. `onUpdate` fires with the latest **composed** value (immediately
+     * if cached). `onError` (optional) fires if the query's handler throws server-side — otherwise a
+     * failing query is logged and leaves the last known value in place.
+     *
+     * Two overloads bridge T3/T5's type reconciliation (`api.ts`'s `AnyFunctionRef` doc): a
+     * codegen-generated ref types `args`/`onUpdate`'s value from its declared `__args`/`__returns`;
+     * this package's own untyped `{ __path }` ref or a raw string path fall back to the pre-existing
+     * `Record<string, Value>`/`Value` shape (an explicit `T` still overrides, as before).
+     */
+    subscribe<Q extends AnyFunctionReference<any, any>>(ref: Q, args: FunctionArgs<Q>, onUpdate: (value: FunctionReturnType<Q>) => void, onError?: QueryErrorListener): () => void;
+    subscribe(ref: FunctionReference | string, args: Record<string, Value> | undefined, onUpdate: QueryListener, onError?: QueryErrorListener): () => void;
+    /** One-shot read: resolves with the first **composed** value (D15) — a one-shot read can return
+     *  speculative data — or rejects if the query throws; then unsubscribes. */
+    query<Q extends AnyFunctionReference<any, any>>(ref: Q, args?: FunctionArgs<Q>): Promise<FunctionReturnType<Q>>;
+    query(ref: FunctionReference | string, args?: Record<string, Value>): Promise<Value>;
+    /**
+     * Run a mutation; resolves with its return value at `MutationResponse` (D3), or rejects with its
+     * error. With `{ optimisticUpdate }`, the closure runs synchronously against a writeable composed
+     * view before the mutation is sent (instant UI); if it throws, `mutation` throws **synchronously**
+     * and nothing is sent. The optimistic layer is dropped on observed inclusion, never on the ack.
+     *
+     * The typed overload's `optimisticUpdate` is typed against the public `OptimisticLocalStore`
+     * (`Q`'s declared `__args`) — sound because `Reconciler.invokeUpdate` (`reconcile.ts`) ALWAYS
+     * enriches the raw internal view into an `OptimisticLocalStore` before calling `entry.update`,
+     * regardless of entry point; the cast to the internal `OptimisticUpdate` shape below is safe for
+     * exactly that reason.
+     *
+     * `{ transient: true }` (internal escape hatch, e.g. `auth-client.ts`'s refresh call) skips the
+     * durable outbox entirely for THIS call — wire-send-only, normal promise semantics — even when an
+     * `outbox` is configured. It exists for mutations that must never be durably replayed after a
+     * reload (an auth-refresh call: replaying a stale refresh token blind, with no live awaiter for
+     * the mint result, trips reuse-detection and force-signs-out an honest user). A non-outbox client
+     * is unaffected either way (`useOutbox` is already false whenever `this.outbox` is unset).
+     */
+    mutation<Q extends AnyFunctionReference<any, any>>(ref: Q, args?: FunctionArgs<Q>, opts?: {
+        optimisticUpdate?: (store: OptimisticLocalStore, args: FunctionArgs<Q>) => void;
+        transient?: boolean;
+    }): Promise<FunctionReturnType<Q>>;
+    mutation(ref: FunctionReference | string, args?: Record<string, Value>, opts?: {
+        optimisticUpdate?: OptimisticUpdate;
+        transient?: boolean;
+    }): Promise<Value>;
+    /** The wire `Mutation` message for `entry` — carries `(clientId, seq)` whenever an outbox is
+     *  configured (park-safety, verdict §(d)), and OMITS the fields entirely (not merely `undefined`)
+     *  when it isn't, so a client with no `outbox` sends exactly today's shape, byte-for-byte. */
+    private mutationMessage;
+    /** The persisted `OutboxStorage` twin of `entry` — only ever called when `this.outbox` (and thus
+     *  `entry.clientId`/`seq`/`order`/`enqueuedAt`) is set. */
+    private toOutboxEntry;
+    /** True while any OTHER entry is `unsent` (queued for a flush) or `parked` (queued for a future
+     *  drain) — the FIFO-preserving gate a new mutation enqueues behind (verdict §(d) "Enqueue").
+     *  A drain chunk in flight also counts (its units are `inflight`, which the scan alone would miss
+     *  when the chunk consumed the whole backlog) — otherwise a mutation issued mid-chunk would
+     *  direct-send AHEAD of a still-unsettled older unit, breaking the FIFO promise if the chunk
+     *  transient-stops and re-sends. Plain live in-flight direct-sends deliberately do NOT count:
+     *  "when empty, live sends go direct and concurrent" (T2's scoping, unchanged). */
+    private hasOutboxBacklog;
+    /** Count of outbox-tracked entries not yet fully settled (excludes `completed` — already acked,
+     *  held only for the ts-gate) — the overflow cap's occupancy (verdict §(d) "Enqueue": "bounded,
+     *  default 1000"). */
+    private outboxQueueDepth;
+    /** Monotonic `OutboxEntry.order` allocator — see the `outboxOrderCounter` field doc. */
+    private nextOutboxOrder;
+    /** Run an action; resolves with its return value (or rejects with its error). Not reactive — an action has no subscription. */
+    action<Q extends AnyFunctionReference<any, any>>(ref: Q, args?: FunctionArgs<Q>): Promise<FunctionReturnType<Q>>;
+    action(ref: FunctionReference | string, args?: Record<string, Value>): Promise<Value>;
+    /** Set (or clear) the session identity for this connection; the server re-runs subscriptions under it. */
+    setAuth(token: string | null): void;
+    /** Managed-session fingerprinting (spec decision 9): a `createAuthClient` calls this so the durable
+     *  outbox's `identityFingerprint` derives from the STABLE `sessionId`, not the rotating access
+     *  token — otherwise a rotation mid-drain would orphan queued offline mutations under a new
+     *  fingerprint. Pass `null` to hand the fingerprint back to the raw `setAuth` token-hash path
+     *  (e.g. on sign-out). No-op when no outbox is configured. */
+    setSessionFingerprint(sessionId: string | null): void;
+    /** Publish an ephemeral event (presence/typing) — bypasses the engine. */
+    publishEphemeral(topic: string, event: Value): void;
+    /** Listen for ephemeral broadcasts (presence/typing) from other clients. */
+    onBroadcast(listener: (topic: string, event: Value) => void): () => void;
+    close(): void;
+    /** @internal test/debug only — the observed-inclusion frontier (resets to 0 at close). */
+    get __maxObservedTs(): number;
+    /** @internal test/debug only — the live pending-mutation log, in requestId order. */
+    get __pending(): readonly PendingMutation[];
+    /** @internal test/debug only — the current `identityFingerprint` cache (see `setAuth`); polling
+     *  this (rather than calling `mutation()` repeatedly, which consumes seqs) is how a test waits
+     *  out the async SHA-256 digest without depending on a fixed tick count. */
+    get __outboxFingerprint(): string;
+    private onServerMessage;
+    /** A frame was missed: reset and re-subscribe all live queries; adopt the server's next state. */
+    private resync;
+    private onTransportClosed;
+    /**
+     * T6: the transport reconnected (a fresh session — the server has no state for it). Order is
+     * load-bearing (verdict §(c) event 6): `SetAuth` replay first (the server re-runs subscriptions
+     * under the right identity), THEN resubscribe every live query (the existing resync path — it
+     * adopts the reply as a fresh baseline regardless of its start version), THEN flush every
+     * `unsent` mutation FIFO — each transitions `unsent` -> `inflight` reusing its ORIGINAL
+     * `requestId` (never re-minted), so the promise created at `mutation()` call time stays the one
+     * that resolves when the new session's `MutationResponse` arrives.
+     */
+    private onTransportReopened;
+    /** Send the `Connect` resume handshake once per connection (idempotent via `outboxConnectSent`),
+     *  arming the baseline await. Shared by the reopen path and the drain's first-connect path (Task 4
+     *  / T3 handoff #1: a fresh-client-first-connect after reload has no reopen event, so the drain
+     *  triggers the same handshake on becoming leader with a durable backlog). */
+    private initiateHandshake;
+    /** True iff at least one live subscription has NOT yet received its first server reply
+     *  (`!sub.answered` — set by `ingestTransition` on EITHER outcome, `QueryUpdated` or `QueryFailed`).
+     *  The drain's first-connect `ensureInitialHandshake` gate (T4 bug fix, later widened to cover the
+     *  failed-query shape too — re-review FIX 2): a subscription created (and answered) BEFORE the
+     *  drain's async hydrate finishes has already consumed its one-shot Transition by the time the
+     *  handshake arms — waiting for ANOTHER one that will never come on a quiet deployment would starve
+     *  `whenBaselineAdopted()` (and so the drain) forever. Only a subscription still awaiting its first
+     *  reply guarantees a future Transition is actually coming — that's the one worth waiting for.
+     *  (Deliberately NOT `sub.serverValue === undefined`: a `QueryFailed` reply never sets `serverValue`
+     *  — there's no base to render — so that check misclassified an already-answered failed query as
+     *  still-undelivered and reproduced the same deadlock via the failed-query path.) */
+    private hasUndeliveredSubscription;
+    /** @internal T4's drain gate. Resolves once the first post-`Connect` baseline Transition has been
+     *  adopted through S3 (verdict §(d) / spec decision 5). Resolves immediately when no handshake is
+     *  in flight (nothing to await) or when a reopen had no live subscriptions to re-baseline. */
+    whenBaselineAdopted(): Promise<void>;
+    /** @internal test/debug — the last `ConnectAck.deploymentId` (the same-timeline proof stamp), or
+     *  `undefined` before any handshake completed. */
+    getOutboxDeploymentId(): string | undefined;
+    /** @internal test/debug — whether the S4 park swap is armed (a `ConnectAck` has proven dedup). */
+    get __outboxArmed(): boolean;
+    /** Begin awaiting the post-`Connect` baseline. `expectTransition` is true iff a baseline Transition
+     *  is actually coming — for a reopen, `this.resyncing` (set iff `resync()` re-subscribed live
+     *  queries); for a first connect, whether any live subscription is still awaiting its first
+     *  delivery (`hasUndeliveredSubscription()` — NOT merely whether one exists: a subscription
+     *  created and already answered before the handshake armed has nothing left to wait for). With
+     *  nothing pending, there is no baseline frame coming and adoption is immediate. */
+    private beginBaselineAwait;
+    /** The baseline Transition adopted (or there was none to await): fire every deferred `applied`
+     *  layer drop (each flicker-free now — the baseline renders the effect), release the drain gate,
+     *  and wake the drain (reconnect-after-baseline). */
+    private markBaselineAdopted;
+    /** Send the `Connect` resume handshake: this tab-session's clientId, the `held` durable entries
+     *  (every not-yet-settled `(clientId, seq)` in the log — the server classifies each into
+     *  `ConnectAck.results`), and `ackedThrough` (the contiguous settled-prefix per clientId, for
+     *  server-side retention pruning). Delegates the pure computation to `./connect-handshake` — the
+     *  SAME shared module the headless drain (`headless-drain.ts`) builds its own `Connect` from. */
+    private sendConnect;
+    /** DLR Stage 2a — advertise by-id diff support once per connection for a NON-outbox client (an
+     *  outbox client's resume `Connect` already carries the flag). A capability-only `Connect` (no
+     *  `clientId`/`held`/`ackedThrough`) is the reserved server no-op path — it records the capability
+     *  and sends no `ConnectAck` — so it never interferes with the outbox handshake or backpressure.
+     *  Sent BEFORE the first `ModifyQuerySet` (fresh connect) and before `resync()` (reopen) so the
+     *  server has the capability recorded when it decides a by-id sub's initial answer; the ordered
+     *  transport guarantees delivery order. Even if it somehow arrived late the diff path self-heals
+     *  (a pre-capability RERUN answer, then diffs resume), but sending it first keeps the common path
+     *  on the diff answer from the very first subscribe. */
+    private maybeSendDiffCapability;
+    /** Process a `ConnectAck` (verdict §(e)): the capability proof arms the S4 park swap; the
+     *  deploymentId is surfaced + persisted; `known: false` triggers `onClientReset`; otherwise each
+     *  classified `held` seq is settled (`applied`/`failed`/`stale` terminal; `unknown` left for the
+     *  drain). */
+    private handleConnectAck;
+    /** Settle one classified `held` seq from a `ConnectAck` (or, later, a drain replay-ack). */
+    private settleVerdict;
+    /** `known: false` — the server disowned this client's history (verdict §(d) Retention). Re-mint a
+     *  fresh clientId + meta; re-enqueue every `unsent` entry under the new clientId + NEW seqs (never
+     *  applied, so safe); reject every `parked` entry LOUDLY (in-flight-at-disconnect, no server dedup
+     *  → a blind resend could double-apply); fire the `onClientReset` callback. */
+    private onClientReset;
+    /** The in-memory log entry with this recorded `(clientId, seq)`, or `undefined`. */
+    private findOutboxEntry;
+    /** Resolve a pending mutation promise by requestId (no-op if it already settled / has no awaiter). */
+    private resolvePending;
+    /** Reject a pending mutation promise by requestId (no-op if it already settled / has no awaiter). */
+    private rejectPending;
+    /** Drop an `applied` cross-session entry's layer — deferred until the baseline is adopted (so the
+     *  drop is flicker-free), or immediately if it already has. */
+    private dropAfterBaseline;
+    /** Dequeue a settled durable entry from the outbox store (no-op without an outbox / clientId). */
+    private dequeueOutboxEntry;
+    /** An `Error` carrying the server's terminal verdict `code` (STALE_CLIENT, an app error code) so
+     *  the drain's coded-vs-codeless retry policy (T4) and apps can key off it. */
+    private mutationError;
+    /** @internal test/debug — the live drain (Task 4), or `undefined` without an outbox. */
+    get __outboxDrain(): OutboxDrain | undefined;
+    private makeDrainHost;
+    /** Drain-eligible entries: durable, recorded `(clientId, seq)`, still `unsent`/`parked`, FIFO by
+     *  the persisted `order`. Excludes `inflight` (a live direct-send or an in-flight chunk unit) and
+     *  `completed`. */
+    private drainableEntries;
+    /** Add a hydrated durable entry into the log under a FRESH requestId (the persisted requestId was
+     *  session-correlation only; a fresh one avoids colliding with this session's requestId counter).
+     *  Idempotent by `(clientId, seq)` — a direct-send this session already tracks is not re-added.
+     *  T5: `entry.update` is populated from the `optimisticUpdates` registry (hydrate-only lookup — a
+     *  live call-site closure is never in play here, there IS no live call site for a cross-reload
+     *  entry); a registry miss is layerless (no `update` at all), a clean drop under the baseline-gated
+     *  drop rule exactly as T4 shipped it. */
+    private addHydratedEntry;
+    /** T5: the registry lookup `addHydratedEntry` makes — hydrate-time ONLY (verdict §(d): "the
+     *  registry is consulted at hydrate only"). A miss warns ONCE per udfPath (not per entry — a
+     *  backlog of many unregistered entries for the same udfPath warns once) and returns `undefined`:
+     *  the entry still drains fine, only its optimistic rendering is skipped (spec §(k)6). */
+    private lookupHydratedUpdate;
+    /** The one predicate distinguishing a MIRRORED entry (another tab-session's durable append, or
+     *  this tab's own past-session hydrate — either way, no live promise) from an entry THIS instance
+     *  itself initiated live (hazard (a), "own-tab discrimination"): durable AND no
+     *  `pendingMutationCallbacks` registered for its `requestId`. A live `mutation()` caller has a
+     *  callback registered only UNTIL its own wire response settles it — resolved/rejected callbacks
+     *  are deleted immediately (`resolvePending`/`rejectPending`), well before a `completed` layer's
+     *  gate gets a chance to drop it. So a live caller's entry looks exactly like a true mirror
+     *  (`isMirroredEntry` returns `true`) for the whole post-ack, still-gated window — this predicate
+     *  alone does NOT distinguish "own tab, post-ack" from "another tab's mirror"; it is the
+     *  `status.type === "completed"` skip in `mirrorFromStore`'s backstop pass that closes that gap
+     *  (a `completed` layer is owned by its gate, never force-settled by this predicate or the store).
+     *  Used both by the dispatch methods below and the doc comment on `mirrorFromStore`'s backstop pass
+     *  — a single documented helper, never inlined twice (brief hazard (a)). */
+    private isMirroredEntry;
+    /** Handle an incoming (already-fan-out'd) broadcast payload — the typed half of `onmessage`. A
+     *  payload that doesn't match `OutboxBroadcastMessage` (the legacy bare `1`, or anything else) is
+     *  simply not recognized: the accessor nudge already fired in the caller, nothing else happens. */
+    private handleOutboxBroadcastMessage;
+    /** Re-read the durable store and reconcile this tab's mirrored set against it — the `enqueued`
+     *  broadcast's handler, and the missed-message backstop (spec Part A "Rules"): a mirrored entry
+     *  absent from the fresh snapshot (settled/failed elsewhere, whose OWN targeted broadcast this tab
+     *  never received) drops via the same `dropAfterBaseline` one-pass rule the verdict-after-baseline
+     *  path uses. Serialized on `mirrorInFlight` — a second call arriving mid-read sets `mirrorRerun`
+     *  and is folded into one more pass after the current read finishes, rather than racing a second
+     *  `loadAll()` against it.
+     *
+     *  Only STILL-ACTIVE entries (`unsent`/`inflight`/`parked`) are (re-)hydrated — a `failed` (or a
+     *  stray `completed`) entry is a terminal, accessor-only record (`pendingMutations()` already
+     *  surfaces it) and must never be resurrected as a fresh `unsent` optimistic layer. Without this
+     *  guard, a tab that itself once owned a now-terminally-failed entry would keep reviving its OWN
+     *  dead record on every subsequent `enqueued` broadcast (this store never dequeues a `failed`
+     *  entry — R9 "persists until dismissed/retried") — and, being `durable` with no live callback,
+     *  that revived entry would then match `isMirroredEntry`, making the tab react to an UNRELATED
+     *  later `settled`/`failed` broadcast that merely happens to name the same `(clientId, seq)`.
+     *
+     *  Two review-fixed hazards in the reconcile loop below (both stem from the SAME root cause: the
+     *  store's presence/absence is not always the authority for a mirrored layer's fate):
+     *   - a `completed` mirrored layer (this tab already got a targeted `settled` broadcast and is
+     *     holding it gated until ITS OWN feed observes `commitTs`, per `onCrossTabSettle`) is SKIPPED
+     *     entirely here, never force-dropped merely because the store record is absent. The leader's
+     *     own `drainSettleApplied` dequeues the record right after posting `settled`, and THAT
+     *     dequeue's `{kind:"enqueued"}` follow-up broadcast is exactly what drives this backstop pass —
+     *     so a `completed` entry being store-absent is the ordinary, expected case, not a missed
+     *     message. Force-dropping it here would race ahead of this tab's own gate (a flicker the gate
+     *     exists to prevent) — CRITICAL. The same skip also protects THIS tab's own just-acked live
+     *     mutation: its `pendingMutationCallbacks` entry is deleted the moment its wire response
+     *     settles it (see `isMirroredEntry`'s doc — the callback does NOT survive the whole gated
+     *     window, only until the response arrives), so during that gated window it is
+     *     indistinguishable from a true mirror to `isMirroredEntry` and would otherwise be dropped by a
+     *     totally unrelated tab's `enqueued` broadcast.
+     *   - the "is this mirror still active" check now reads from ACTIVE-status (`unsent`/`inflight`/
+     *     `parked`) entries only, not "any entry present in the store" — a mirror whose backing record
+     *     flipped to `failed` (R9 never dequeues a failure) is present-in-store but no longer active;
+     *     treating presence alone as "still live" would leave a permanent phantom optimistic row behind
+     *     a missed `failed` broadcast. Such an entry is instead settled failed right here (same effect
+     *     as `onCrossTabSettle`'s `failed` branch — mark failed + fire R9), using the terminal verdict
+     *     already recorded on the store row itself. */
+    private mirrorFromStore;
+    /** Handle a targeted `settled`/`failed` broadcast — the leader's flicker-free fast path (Part A's
+     *  normal route; `mirrorFromStore`'s backstop above is the fallback for a missed message). Ignored
+     *  entirely for an entry this tab doesn't know about, or one it initiated live itself (hazard (a)).
+     *  Never touches the durable store — the leader (whichever tab settled it) already wrote that;
+     *  this only updates THIS tab's in-memory reconciler layer + R9 observability. */
+    private onCrossTabSettle;
+    private drainBatchEntry;
+    /** applied settlement for a drained unit — resolve the awaiting promise (if any) and dequeue the
+     *  durable record ALWAYS; then route the layer drop by `replayed` (T4 review fix — the ungated
+     *  fresh-apply drop):
+     *   - `replayed: true` — a resend whose commit predates this session's `Connect`, reusing the same
+     *     primitive `settleVerdict`'s `applied` case uses (T3's unconditional baseline-gated drop).
+     *     Drop-soundness (T3 watch item, scoped to replays ONLY): the drop is gated on baseline
+     *     adoption, not on the replay's carried commitTs — the entry's commit necessarily predates this
+     *     session's `Connect`, so it predates the baseline's read snapshot and the baseline already
+     *     renders the effect. Historical-ts-vs-current-base is therefore still covered; the drop is
+     *     flicker-free by the same one-pass rule as T3's handshake.
+     *   - a FRESH apply (`replayed` absent/false — this session's OWN first execution, a genuinely new
+     *     `ts`) — the argument above does NOT apply: nothing proves this commit predates the baseline,
+     *     so an unconditional drop here would remove a still-rendered layer before its authoritative row
+     *     ever appears (a flicker). Instead this routes through the normal same-session gate,
+     *     `onMutationSuccess` (the response `ts`) — the exact same shipped no-flicker discipline the
+     *     direct-send path uses at `MutationResponse` (see the `case "MutationResponse"` handler above):
+     *     hold the layer `completed` until this client's own reactive feed observes `ts`.
+     *
+     *  T-crosstab: AFTER the local settle above, the leader (this tab, if it holds the drain lock)
+     *  also posts a targeted `settled` broadcast so a tab MIRRORING this same `(clientId, seq)` gets
+     *  the flicker-free fast path instead of waiting for its own next `enqueued`-triggered backstop
+     *  read. Posted only when the entry carries a durable `(clientId, seq)` — a plain non-outbox
+     *  mutation has nothing for another tab to have mirrored in the first place.
+     */
+    private drainSettleApplied;
+    /** Terminal settlement for a drained unit (a coded server verdict, or the identity gate) — reject
+     *  the awaiting promise (coded), MARK the durable record `"failed"` (R9: never dequeue a terminal
+     *  failure — it persists until dismissed/retried), drop the layer, and (T5) refire `onMutationFailed`
+     *  / the dev-loud default when nothing awaited this failure this session. T-crosstab: AFTER all of
+     *  the above, also posts a targeted `failed` broadcast (same durability gate as `drainSettleApplied`
+     *  above) — a mirroring tab's own `onCrossTabSettle` fires ITS OWN `onMutationFailed`/dev-loud
+     *  default; it never double-delivers THIS tab's own notification above. */
+    private drainSettleTerminal;
+    /** A snapshot of the durable outbox — `usePendingMutations()`'s underlying read. `[]` without an
+     *  outbox configured (verdict §(d) R9). Each row's `retry()`/`dismiss()` close over the entry as
+     *  read HERE (no extra storage round-trip — `retry()` needs `args`/`seed`/`identityFingerprint`,
+     *  all captured already). */
+    pendingMutations(): Promise<PendingMutationEntry[]>;
+    /** T5 (R9, hazard 2's client half): count + oldest-age advisory over the durable queue — cheap
+     *  enough to poll for a "your offline changes may be lost soon" banner ahead of a storage cliff
+     *  (Safari's 7-day eviction). `{count: 0, oldestEnqueuedAt: undefined, oldestAgeMs: undefined}`
+     *  without an outbox configured, or with an empty one. */
+    pendingSummary(): Promise<PendingSummary>;
+    private toPendingMutationEntry;
+    /** `entry.retry()` (R9): a FAILED entry only — everything else is a harmless no-op (verdict §(b):
+     *  "never reuse a seq for a new attempt"). Dequeues the OLD (failed-verdict) durable record and
+     *  builds a brand-new `PendingMutation` — fresh requestId/seq/order, the CURRENT session's identity
+     *  fingerprint (a fair shot even if identity rotated since the original failure), reconstructed
+     *  exactly like a hydrated entry (same udfPath/args/seed; the registry is consulted — there is no
+     *  live call-site closure for a retry either). No live promise is registered: like a hydrated
+     *  entry, its eventual outcome surfaces via `usePendingMutations()`/`onMutationFailed`, never a
+     *  returned `Promise<Value>` (the durable record outlives any promise). */
+    private retryOutboxEntry;
+    /** `entry.dismiss()` (R9): a FAILED entry only — permanently forget it without retrying. */
+    private dismissOutboxEntry;
+    /** T5 (R9): subscribe to "the durable outbox changed" — `usePendingMutations()`'s re-read trigger.
+     *  Fires on every local outbox-mutating op AND on an incoming cross-tab `outboxBroadcast` message. */
+    onOutboxChange(listener: () => void): () => void;
+    private notifyOutboxChange;
+    /** Every durable-mutating outbox call site funnels through these four wrappers (instead of a bare
+     *  `this.outbox?.xxx(...)`) so `notifyOutboxChange()` — and a rejection's route through
+     *  `handleOutboxWriteError` — is never missed at a new call site. */
+    private outboxAppend;
+    private outboxDequeue;
+    private outboxUpdateStatus;
+    /** Record a terminal failure DURABLY (`status: "failed"` + the error) instead of dequeuing — R9:
+     *  "failed entries persist until dismissed/retried". */
+    private outboxMarkFailed;
+    /** Routes a rejected fire-and-forget durable-outbox write (append/updateStatus/dequeue/setMeta —
+     *  never awaited by its caller, per the write-behind contract) to observability instead of letting
+     *  it become an unhandled promise rejection, which several Node/Electron hosts treat as fatal by
+     *  default (a `fsOutbox` that has fail-stopped after a disk error rejects EVERY subsequent op —
+     *  see `outbox-fs.ts`'s `OutboxClosedError`). When the write carries a `(clientId, seq)` — every
+     *  case except a meta-only write — it routes through the SAME R9 channel as any other terminal
+     *  mutation failure (`onMutationFailed`, or `notifyMutationFailed`'s own dev-mode loud
+     *  `console.error` default). With no such record to attach the failure to (a meta write), a
+     *  dev-loud `console.error` is the floor — NEVER swallowed silently either way. */
+    private handleOutboxWriteError;
+    /** T5 (R9): fire `onMutationFailed` for a terminal durable failure with NO live promise awaiter
+     *  this session (`hadAwaiter` already checked by every call site) — or, absent a registered
+     *  handler, the dev-mode loud `console.error` default (spec-review: "the five-line courtesy" no
+     *  position shipped). A no-op for a non-outbox-tracked entry (`clientId`/`seq` undefined) — R9 is
+     *  entirely a durable-outbox concern. */
+    private notifyMutationFailed;
+    /** R9 "resume" refire (constructor-only, verdict §(d) Observability: "`onMutationFailed` refires
+     *  from durable records on resume"): a fresh `HelipodClient` instance has made zero `mutation()`
+     *  calls yet, so EVERY already-`"failed"` durable record found here is trivially "no live awaiter" —
+     *  Lunora's `hadAwaiter` check is unconditionally false at this point, no gating needed. */
+    private refireDurableFailures;
+}
+
+export { AUTH_REFRESH_UDF_PATH as A, reconnectDelayMs as B, type ClientTransport as C, DEFAULT_DRAIN_CHUNK_SIZE as D, webSocketTransport as E, type FunctionArgs as F, HelipodClient as H, type LoopbackLike as L, type MutationFailedInfo as M, NON_REPLAYABLE_MUTATION_DROPPED as N, type OutboxLockManager as O, type PendingMutation as P, type QueryErrorListener as Q, type RefArgs as R, type WebSocketTransportOptions as W, type PoisonPolicy as a, type AnyFunctionRef as b, type AnyFunctionReference as c, type ClientResetInfo as d, DEFAULT_DRAIN_INTERVAL_MS as e, type DrainHost as f, type FunctionReference as g, type FunctionReturnType as h, OFFLINE_IDENTITY_CHANGED as i, type OptimisticLocalStore as j, type OptimisticStoreView as k, type OptimisticUpdate as l, type OptimisticUpdateFn as m, type OutboxBroadcastLike as n, type OutboxBroadcastMessage as o, OutboxDrain as p, type OutboxDrainOptions as q, type PendingMutationEntry as r, type PendingSummary as s, type QueryListener as t, type RefReturn as u, anyApi as v, computeDrainBackoff as w, createOptimisticLocalStore as x, getFunctionPath as y, loopbackTransport as z };