@happyvertical/smrt-web 0.51.31 → 0.51.33

package/dist/internal.d.ts

@@ -0,0 +1,15 @@
+/** Internal coordination state shared by the smrt-web runtime modules. */
+/**
+ * TanStack transactions resolve with an opaque transaction object rather than
+ * the value returned by the REST mutation handler. Keep the latter beside the
+ * public collection handle so WebMCP can return the server's canonical row
+ * without exposing engine internals.
+ */
+export declare const persistedMutationResults: WeakMap<object, Map<string, unknown>>;
+/**
+ * Engine-owned hydration boundary. The implementation registers this callback
+ * where the typed query-collection API is available; WebMCP only asks the
+ * boundary to hydrate a row and never reaches into engine internals.
+ */
+export declare const mutationTargetHydrators: WeakMap<object, (row: Record<string, unknown>) => Promise<void>>;
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,uCAGlC,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,wBAE5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAC9C,CAAC"}

package/dist/offline/durable-queue.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @happyvertical/smrt-web — the durable IndexedDB outbox queue (#1762).
+ *
+ * A raw IndexedDB FIFO queue: the persistence half of the offline outbox. One
+ * database per durable-store namespace ({@link durableStoreNamespace}), one
+ * object store (`outbox`) keyed by an AUTO-INCREMENTING `seq` — so insertion
+ * order IS replay order for free — plus a `state` index so the replay loop can
+ * scan only rows that still need work.
+ *
+ * ## Why raw IndexedDB, not `@tanstack/offline-transactions`
+ *
+ * The decisive finding (#1762): the TanStack offline layer's public API is
+ * engine-typed (`Collection<…>`, `mutationFns`), so importing it emits a
+ * `@tanstack/` specifier into `dist/offline.d.ts`, which
+ * `scripts/check-smrt-web-engine-boundary.mjs` scans for unconditionally — the
+ * build would fail. It also pins `@tanstack/db` exactly and competes with
+ * smrt-web's OWN mutation lifecycle. So the outbox is hand-rolled over browser
+ * globals (`indexedDB`, `navigator.locks`) with ZERO new runtime dependency.
+ *
+ * This module is engine-free (no `@tanstack/*` import): it stays inside the
+ * engine-absorption boundary (#1761) and speaks only the sync-apply contract's
+ * op shape (`packages/core/src/sync/apply.ts`).
+ *
+ * Row payloads are stored as structured-clone-safe plain objects; IndexedDB
+ * clones on write, so callers may keep mutating the source object after enqueue.
+ */
+import type { SyncApplyOp } from './types.js';
+/** IndexedDB object-store name inside every outbox database. */
+export declare const OUTBOX_STORE = "outbox";
+/** Index over {@link OutboxRow.state} — the replay scan reads it. */
+export declare const OUTBOX_STATE_INDEX = "state";
+/** IndexedDB schema version. Bump only on a store/index migration. */
+export declare const OUTBOX_DB_VERSION = 1;
+/**
+ * Durable lifecycle state of one queued mutation. Deliberately a SUPERSET of
+ * the app-observable sync state: `pending` rows are due for (re)send, while
+ * `synced`/`failed` are terminal tombstones removed after each drain. The
+ * app-facing {@link OutboxSyncState} (`pending`/`uploading`/`synced`/`failed`)
+ * is derived by the engine — `uploading` is a transient in-flight marker the
+ * engine emits, never persisted; this enum is the on-disk truth.
+ */
+export type OutboxRowState = 'pending' | 'synced' | 'failed';
+/**
+ * One durable outbox row — a single client-authored mutation awaiting replay
+ * through `POST {basePath}/sync/apply`. Fields mirror the sync-apply item so a
+ * row maps to a batch item with no translation, plus the durable bookkeeping the
+ * replay loop needs (`state`, `attempts`, `nextAttemptAt`, `lastError`).
+ */
+export interface OutboxRow {
+    /** Auto-incrementing primary key — monotonic, so `seq` order IS FIFO. */
+    seq?: number;
+    /**
+     * The sync-apply `itemId`: the client's idempotency/correlation handle. A
+     * fresh UUID minted at enqueue time, distinct from {@link id} (the row UUID),
+     * so it survives coalescing and is echoed back verbatim by the endpoint.
+     */
+    itemId: string;
+    /** The collection route segment (e.g. `products`) — sync-apply `object`. */
+    object: string;
+    /** Which mutation kind — sync-apply `op`. */
+    op: SyncApplyOp;
+    /** The client-generated row UUID — sync-apply `id`. */
+    id: string;
+    /** Field data for create/update; omitted for delete. */
+    payload?: Record<string, unknown>;
+    /** The server `updated_at` the client last saw — the conflict guard base. */
+    baseUpdatedAt?: string;
+    /**
+     * The consumer-declared replay transport this row routes through (#3021),
+     * by name. Absent ⇒ the row replays through `sync/apply`. Present ⇒ it
+     * replays ONLY through the transport registered under this name, and is held
+     * (never re-routed to `sync/apply`) until one is. Additive: rows written
+     * before #3021 lack it and keep their sync-apply meaning, so no schema bump.
+     */
+    transport?: string;
+    /**
+     * A value the row's transport pinned on its first attempt (#3021) — e.g. the
+     * built server request — so every retry under the same idempotency key
+     * resends an identical request. Structured-clone-safe.
+     */
+    pinned?: unknown;
+    /** On-disk lifecycle state. */
+    state: OutboxRowState;
+    /** How many replay attempts this row has made (drives backoff). */
+    attempts: number;
+    /** Epoch ms before which this row must not be retried (backoff gate). */
+    nextAttemptAt: number;
+    /** Last replay error message, for diagnostics/`snapshot()`. */
+    lastError?: string;
+    /** Epoch ms the row was first enqueued — stable ordering tiebreak + age. */
+    enqueuedAt: number;
+}
+/** The fields a caller supplies to {@link DurableOutboxQueue.enqueue}. */
+export interface EnqueueInput {
+    itemId: string;
+    object: string;
+    op: SyncApplyOp;
+    id: string;
+    payload?: Record<string, unknown>;
+    baseUpdatedAt?: string;
+    transport?: string;
+}
+/**
+ * Feature-detect a usable IndexedDB. Some environments expose `indexedDB` but
+ * throw on `open()` (private-mode Firefox historically, sandboxed iframes), so a
+ * real probe opens a throwaway database. Returns `false` rather than throwing so
+ * the engine can degrade to a no-op instead of crashing the host.
+ */
+export declare function probeIndexedDb(): Promise<boolean>;
+/**
+ * The durable FIFO outbox queue over one IndexedDB database. Constructed via
+ * {@link openDurableOutboxQueue} (async open + schema upgrade), then used
+ * through the async methods below (each resolves once its txn commits).
+ *
+ * NOT concurrency-controlled across tabs on its own — the OutboxEngine layers
+ * Web Locks leader election on top so exactly one tab drains it. Within one tab,
+ * IndexedDB's own transaction serialization is sufficient.
+ */
+export declare class DurableOutboxQueue {
+    private readonly db;
+    /** The IndexedDB database name (== the durable-store namespace). */
+    readonly dbName: string;
+    constructor(db: IDBDatabase, dbName: string);
+    /**
+     * Append a mutation to the tail of the queue in state `pending`, due
+     * immediately (`nextAttemptAt = 0`, `attempts = 0`). Resolves with the
+     * assigned `seq` once the write is durably committed.
+     */
+    enqueue(input: EnqueueInput): Promise<number>;
+    /**
+     * Persist a state transition (and any of attempts/backoff/error) for the row
+     * at `seq`, reading-then-writing inside ONE transaction so a concurrent drain
+     * in the same tab can't lose the update. A no-op if the row is already gone
+     * (removed by a prior terminal transition).
+     */
+    markState(seq: number, patch: Partial<Pick<OutboxRow, 'state' | 'attempts' | 'nextAttemptAt' | 'lastError' | 'pinned'>>): Promise<void>;
+    /**
+     * All rows that are due to (re)send at `now`: state `pending` AND
+     * `nextAttemptAt <= now`, in ascending `seq` (FIFO). Uses the `state` index to
+     * avoid scanning terminal tombstones. Terminal rows (`synced`/`failed`) are
+     * excluded — they await removal, not replay.
+     */
+    listPending(now: number): Promise<OutboxRow[]>;
+    /** Remove the row at `seq` (a terminal transition drops it). */
+    remove(seq: number): Promise<void>;
+    /** Every row currently in the queue (any state), ascending `seq`. */
+    all(): Promise<OutboxRow[]>;
+    /**
+     * Drop every row — the durable-store `clear()` for `wipeDurableStore`. Empties
+     * the store but keeps the database (and its `seq` autoincrement counter) so a
+     * subsequent enqueue still gets fresh monotonic ids.
+     */
+    clear(): Promise<void>;
+    /** Close the underlying database handle (called on engine dispose). */
+    close(): void;
+}
+/**
+ * Open (creating/upgrading as needed) the outbox database for `dbName` and wrap
+ * it in a {@link DurableOutboxQueue}. `dbName` MUST be a
+ * {@link durableStoreNamespace} string — already `encodeURIComponent`-safe and
+ * carrying the api/tenant/identity/manifest isolation boundary, so two
+ * identities never share one queue database.
+ *
+ * The `onupgradeneeded` handler creates the `outbox` store keyed by
+ * autoincrementing `seq` and the `state` index. Idempotent: re-opening an
+ * existing database at the same version skips the upgrade — which is exactly the
+ * "reload" path (a new tab re-opens the same durable backing and sees prior
+ * rows).
+ */
+export declare function openDurableOutboxQueue(dbName: string): Promise<DurableOutboxQueue>;
+//# sourceMappingURL=durable-queue.d.ts.map

package/dist/offline/durable-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-queue.d.ts","sourceRoot":"","sources":["../../src/offline/durable-queue.ts"],"names":[],"mappings":"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"}

package/dist/offline/engine.d.ts

@@ -0,0 +1,359 @@
+/**
+ * @happyvertical/smrt-web — the shared, namespace-keyed outbox engine (#1762).
+ *
+ * The engine owns the durable queue, the leader lock, and the replay loop for
+ * ONE durable-store namespace, and is REF-COUNTED so that N collections sharing
+ * a namespace share exactly ONE engine — one IndexedDB database, one leader
+ * lock, one FIFO queue. This sharing is REQUIRED for correctness, not an
+ * optimization: if each collection held its OWN leader lock, two tabs could each
+ * win a different collection's lock and both replay the (shared) queue,
+ * double-POSTing. One lock per namespace route ⇒ one replayer per route across
+ * all tabs. Since #3021 a route is `sync-apply` (every sync-apply collection;
+ * keeps the pre-#3021 lock name) or one consumer-declared transport, and a tab
+ * leads only routes it has a binding for, so FIFO and backoff are per route.
+ *
+ * Replay maps sync-apply results onto durable transitions per the contract's
+ * "Web outbox (#1762)" consumer notes
+ * (docs/content/architecture/sync-apply-contract.md):
+ *
+ * | apply result                        | queue transition                       |
+ * |-------------------------------------|----------------------------------------|
+ * | `applied`                           | remove → `synced`                      |
+ * | `conflict` (stale_write/create_conflict) | remove + fire onConflict → `synced` (a RESOLVED outcome) |
+ * | `rejected` `write_failed`           | keep, attempts++, backoff → `pending`  |
+ * | `rejected` `auth_required`/`forbidden` | PAUSE the loop, keep queued → `pending` |
+ * | `rejected` other (`invalid_*`/`unknown_object`/`not_found`/`op_not_allowed`/`id_conflict`) | remove → `failed` (terminal) |
+ * | network reject / non-200 / lost response | whole batch stays `pending`, drain stops behind it (blind replay is safe by construction — idempotency) |
+ *
+ * Because items carry client-generated UUIDs and the endpoint is idempotent
+ * (`_insertOnly` create + no-op re-apply), a batch that was sent but whose
+ * response was lost can be blindly re-sent with no duplicate rows — which is
+ * why the network-failure path simply leaves the batch `pending`.
+ *
+ * Engine-free public surface: no `@tanstack/*` import — inside the boundary
+ * (#1761). The one engine-adjacent value it receives is the SMRT-owned
+ * durable-store namespace + registration hooks passed in `config`.
+ */
+import { type OutboxCommandTransport, type OutboxConflict, type ResolvedBackoff, type SyncApplyOp, type SyncStateEvent } from './types.js';
+/** Maps a capability-seam envelope kind to a sync-apply op. */
+export declare function envelopeKindToOp(kind: 'insert' | 'update' | 'delete'): SyncApplyOp;
+/**
+ * The bookkeeping a namespace's durable-store registration needs, supplied by
+ * the public surface so the engine can key its queue and register for
+ * {@link wipeDurableStore} WITHOUT importing `durable-store.ts` itself (keeping
+ * this module's dependency surface minimal and the namespacing single-sourced in
+ * the caller). `namespace` is the {@link durableStoreNamespace} string.
+ */
+export interface OutboxEngineConfig {
+    /** The durable-store namespace string — the IDB dbName + lock-name root. */
+    namespace: string;
+    /** Resolved backoff parameters. */
+    backoff: ResolvedBackoff;
+    /**
+     * Register this engine's queue as a durable resource so `wipeDurableStore`
+     * can clear it; returns the unregister fn. Wraps `registerDurableResource`
+     * from the caller so the engine stays decoupled from that module.
+     */
+    registerResource: (clear: () => Promise<void>) => () => void;
+    /** Injectable RNG for deterministic backoff jitter in tests. */
+    random?: () => number;
+}
+/**
+ * A pending optimistic write to enqueue, in capability-seam terms. Callbacks are
+ * NOT carried here — they are registered per-`object` at
+ * {@link OutboxEngine.registerCollection} so that reloaded rows (which this
+ * session never enqueued) still route their events to the collection.
+ */
+export interface OutboxEnqueueRequest {
+    kind: 'insert' | 'update' | 'delete';
+    /** The collection route segment (definition.name). */
+    object: string;
+    /**
+     * The client-generated row UUID (the optimistic row's id). Empty ⇒ the
+     * minted item id stands in (a transport command with no target row).
+     */
+    rowId: string;
+    /** Full row (insert) / changed fields (update) / ignored (delete). */
+    data: Record<string, unknown>;
+    /** The server updated_at last seen for this row, for the conflict guard. */
+    baseUpdatedAt?: string;
+    /**
+     * Replay through the transport registered under this name instead of
+     * `sync/apply` (#3021). Absent ⇒ sync-apply.
+     */
+    transport?: string;
+}
+/**
+ * Where a namespace's sync-apply rows are POSTed. Supplied by the binding that
+ * replays through sync-apply (an `offlineOutbox` without a `transport`), not by
+ * the engine's creator: a command-only queue may create the shared engine
+ * first, and must not pin a sync-apply base path it never declared.
+ */
+export interface OutboxSyncApplyTarget {
+    /** Absolute base path the sync-apply endpoint lives under (e.g. `/api/v1`). */
+    basePath: string;
+    /** Fetch implementation (injectable for tests/SSR). */
+    fetchFn: typeof fetch;
+}
+/** A read-only view of one queued item, for {@link OutboxEngine.snapshot}. */
+export interface OutboxSnapshotItem {
+    itemId: string;
+    object: string;
+    op: SyncApplyOp;
+    rowId: string;
+    state: 'pending' | 'synced' | 'failed';
+    attempts: number;
+    nextAttemptAt: number;
+    lastError?: string;
+    /** The replay transport name, when the item replays through one (#3021). */
+    transport?: string;
+}
+/**
+ * The shared per-namespace outbox engine. Create/lookup via
+ * {@link getOrCreateOutboxEngine}; never construct directly (the module keeps
+ * the ref-counted registry).
+ */
+export declare class OutboxEngine {
+    private readonly config;
+    /**
+     * Per-collection callback sets, keyed by the collection route segment
+     * (`object`). Keyed by `object` — NOT by the queue row's `itemId` — precisely
+     * so replayed rows that were REHYDRATED from IndexedDB after a reload (whose
+     * itemIds this session never enqueued) still route their state/conflict events
+     * to the reloaded collection's callbacks. A `Set` per object so N collections
+     * sharing one engine+object each get every event (the common case is one
+     * collection per object, but the shared-engine model does not forbid more).
+     */
+    private readonly listenersByObject;
+    /**
+     * The sync-apply endpoint, adopted from the first binding that declares one.
+     * A tab without one never leads the sync-apply route, so its rows wait for a
+     * tab that does (never dropped) — see `drainOnce`.
+     */
+    private syncApply;
+    /** Ref count: number of collections currently attached to this engine. */
+    private refCount;
+    /** The durable queue, once opened. undefined while opening / if IDB absent. */
+    private queue;
+    /** Resolves once the async open settles (success or degraded). */
+    private readonly ready;
+    /** True when IndexedDB was unavailable and the engine is a durable no-op. */
+    private degraded;
+    /**
+     * Per-route leadership, requested when the first binding serving a route
+     * attaches and released when the last one detaches. Exactly one tab replays a
+     * given route; a tab never leads a route it has no binding for.
+     */
+    private readonly leaders;
+    /** Unregister fn from the durable-store registry. */
+    private unregisterResource;
+    /** True once dispose() ran — guards late async continuations. */
+    private disposed;
+    /**
+     * Paused by an auth_required/forbidden result: the loop stops draining until
+     * a later enqueue (the app re-authenticated and is writing again) or an
+     * explicit retry wakes it. Items stay queued.
+     */
+    private paused;
+    /** Wipes issued but not yet cleared; replay is suspended meanwhile. */
+    private wipesPending;
+    /** Those wipes, so `dispose()` can let them finish before closing. */
+    private readonly pendingWipes;
+    /** True while a drain pass is running, to coalesce concurrent triggers. */
+    private draining;
+    /** The running drain, while `draining`. */
+    private activeDrain;
+    /** A drain requested while one was in flight — run one more pass after. */
+    private drainQueued;
+    /** Timer for the next backoff-scheduled drain, if any. */
+    private backoffTimer;
+    /** The `online` event listener, so we can remove it on dispose. */
+    private onlineListener;
+    constructor(config: OutboxEngineConfig);
+    /** Open the durable queue (or mark degraded if IndexedDB is unusable). */
+    private open;
+    /**
+     * Register the queue as a durable resource. A wipe drops the namespace's
+     * registrations, so the clear callback forgets ours and the next enqueue
+     * registers again — otherwise a second wipe would miss rows written after
+     * the first.
+     */
+    private registerForWipe;
+    /** Wake the drain loop immediately when connectivity returns. */
+    private wireOnlineListener;
+    /**
+     * Request cross-tab leadership for `route` (ref-counted per tab). The
+     * sync-apply route keeps the pre-#3021 lock name, so it stays mutually
+     * exclusive with tabs running an older build; each transport route has its
+     * own lock.
+     */
+    private acquireRoute;
+    /** Drop one reference to `route`; the last one releases its lock. */
+    private releaseRoute;
+    /** Does this tab currently lead `route`? */
+    private leads;
+    /**
+     * Attach a collection: register its per-object callbacks and bump the ref
+     * count. Returns the exact callback record registered so the caller can pass
+     * it back to {@link unregisterCollection} for precise removal (two collections
+     * on the same object must each detach only their own callbacks). Registering
+     * by `object` is what lets rehydrated rows (reloaded from IDB) reach this
+     * collection's callbacks even though this session never enqueued them.
+     */
+    registerCollection(binding: OutboxCollectionBinding): object;
+    /** The first live transport registered under `name`, if any. */
+    private transportFor;
+    /**
+     * Detach a collection: remove its callback record and decrement the ref count;
+     * when it reaches zero, dispose the engine (release the lock, unregister from
+     * the durable-store registry, close IndexedDB). The durable ROWS are NOT
+     * cleared — they must survive to replay after a reload; only the in-memory
+     * engine is torn down. Returns true if it disposed.
+     */
+    unregisterCollection(object: string, record: object): Promise<boolean>;
+    /** Current ref count (test/introspection aid). */
+    get referenceCount(): number;
+    /**
+     * Enqueue an optimistic write into the durable queue and fire the initial
+     * `pending` state, then kick a drain. Resolves once the row is durably
+     * committed (so the caller's `wrapMutation` only reports handled after
+     * persistence). Replay events for this row (and for rows this session did not
+     * enqueue — reloaded from disk) route to the registered per-`object`
+     * callbacks, so a reload does not lose observability.
+     *
+     * In degraded (no-IndexedDB) mode the write is NOT durable, so this returns
+     * `undefined` and the capability falls through to the real fetcher instead
+     * of acknowledging an optimistic-only write.
+     */
+    enqueue(request: OutboxEnqueueRequest): Promise<string | undefined>;
+    /**
+     * Force a retry of a specific queued item now: clears its backoff gate and
+     * wakes the loop. The bridge `OutboxHandle.retry(itemId)` calls this so an app
+     * "retry" button can flush a backed-off or auth-paused item. A no-op for an
+     * item that is not (or no longer) queued.
+     */
+    retry(itemId: string): Promise<void>;
+    /**
+     * A read-only snapshot of the durable queue — the basis of
+     * `OutboxHandle.snapshot()`. Because the READ cache is NOT rehydrated after a
+     * reload in this slice (that's #1764's warmStart), the snapshot + the raw IDB
+     * store are how a test/app proves durability, not `collection.toArray()`.
+     */
+    snapshot(): Promise<OutboxSnapshotItem[]>;
+    /**
+     * Deliver a state event to every callback registered for the event's
+     * collection `object` (best-effort). Routing by `object` — not `itemId` —
+     * means a row REHYDRATED from IndexedDB after a reload still reaches the
+     * reloaded collection's callback even though this session never enqueued it.
+     */
+    private emit;
+    /** Deliver a conflict to every callback registered for its collection. */
+    private emitConflict;
+    /**
+     * The replay loop. Gated on: (a) leading at least one route, (b) not paused by an
+     * auth failure, (c) `navigator.onLine !== false`, (d) IndexedDB usable. Drains
+     * every led route's rows due now (`nextAttemptAt <= now`), oldest-first per
+     * route; sync-apply chunks into batches of ≤1000 per POST, one send at a time
+     * to preserve each route's FIFO. Concurrency-coalesced: a drain requested while one runs sets a flag
+     * to run exactly one more pass, so overlapping triggers never interleave.
+     */
+    private drain;
+    /**
+     * Settles once the drain in flight (if any) has finished its request AND its
+     * durable result transition. A route's lock is released only after this, so
+     * another tab can never replay a row this tab is still settling.
+     */
+    private settled;
+    /** One drain pass: send every currently-due batch, then schedule backoff. */
+    private drainOnce;
+    /**
+     * Replay one transport row through its consumer-declared transport (#3021)
+     * and map the outcome through the SAME transitions as a sync-apply result. A
+     * throw is the ambiguous path (request may or may not have landed): the row
+     * stays `pending` with backoff and is resent under the same idempotency key.
+     * Returns false when the row remains pending, stopping this route's pass
+     * (FIFO per route).
+     */
+    private sendCommand;
+    /**
+     * Send one chunk through `POST {basePath}/sync/apply` and map results back
+     * onto durable transitions. On a network reject / non-200 / lost/mismatched
+     * response the WHOLE chunk stays `pending` (blind replay is safe) — every row
+     * goes back to `pending` with an incremented attempt + backoff so the loop
+     * doesn't hot-spin. Returns false when a retryable row remains pending, which
+     * stops this drain pass so newer FIFO chunks do not overtake it.
+     */
+    private sendBatch;
+    /**
+     * POST a batch to `{basePath}/sync/apply`. Throws on a non-2xx or a network
+     * error (the caller treats a throw as "response lost → keep pending"). Returns
+     * the positional `results` array, or `undefined` on a malformed 200 body.
+     */
+    private postBatch;
+    /**
+     * Map one positional apply result onto a durable transition + observable
+     * state, per the contract's consumer notes. See the class doc's mapping table.
+     */
+    private applyResult;
+    /** Remove a successfully-applied (or conflict-resolved) row → `synced`. */
+    private finishSynced;
+    /** Re-queue every row of a failed batch (network path) with backoff. */
+    private requeueBatch;
+    /** Re-queue one row: attempts++, backoff gate, `pending` event. */
+    private requeueRow;
+    /**
+     * Schedule the next drain for the soonest backed-off row's `nextAttemptAt`.
+     * Only one timer is ever pending; a sooner schedule replaces a later one.
+     */
+    private scheduleNextBackoff;
+    /**
+     * Tear down the in-memory engine: release leadership, remove the online
+     * listener, clear timers, unregister from the durable-store registry, and
+     * close IndexedDB. Does NOT clear the durable rows — they must survive to
+     * replay on the next load.
+     */
+    private dispose;
+}
+/**
+ * Get the shared engine for `config.namespace`, creating it on first use and
+ * ref-counting it. Every collection opting into the outbox under the same
+ * namespace gets the SAME engine — one IndexedDB db, one leader lock, one FIFO
+ * queue. The caller MUST pair each `getOrCreateOutboxEngine(...).registerCollection()`
+ * with a later `unregisterCollection()` (via `teardown`) so the engine disposes
+ * when its last collection detaches.
+ */
+export declare function getOrCreateOutboxEngine(config: OutboxEngineConfig): OutboxEngine;
+/**
+ * The per-collection (or per-command-queue) binding registered on attach.
+ * `object` is the event-routing key AND, for a `transport` binding, the name
+ * transport rows are queued under.
+ */
+export interface OutboxCollectionBinding {
+    object: string;
+    onSyncStateChange?: (event: SyncStateEvent) => void;
+    onConflict?: (conflict: OutboxConflict) => void;
+    /** Replay rows queued under `object` through this transport (#3021). */
+    transport?: OutboxCommandTransport;
+    /** Declares the sync-apply endpoint (sync-apply bindings only). */
+    syncApply?: OutboxSyncApplyTarget;
+}
+/**
+ * Attach a collection to the namespace's engine (creating it if needed),
+ * register its per-`object` callbacks, and increment its ref count. Returns the
+ * engine plus the exact callback `record` to hand back to
+ * {@link releaseOutboxEngine} for precise removal. Pair with
+ * {@link releaseOutboxEngine}.
+ */
+export declare function acquireOutboxEngine(config: OutboxEngineConfig, binding: OutboxCollectionBinding): {
+    engine: OutboxEngine;
+    record: object;
+};
+/**
+ * Detach a collection from an engine (removing its callback record) and, if it
+ * was the last one, dispose it and evict it from the shared registry so the
+ * namespace starts fresh next time.
+ */
+export declare function releaseOutboxEngine(namespace: string, engine: OutboxEngine, object: string, record: object): Promise<void>;
+/** Test-only: current engine count (for leak assertions). */
+export declare function _outboxEngineCount(): number;
+//# sourceMappingURL=engine.d.ts.map

package/dist/offline/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/offline/engine.ts"],"names":[],"mappings":"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"}

package/dist/offline/leader.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @happyvertical/smrt-web — Web Locks leader election for the outbox (#1762).
+ *
+ * With multiple tabs open, exactly ONE must replay the shared outbox queue, or
+ * two tabs would POST the same batch concurrently. The mechanism is the native
+ * Web Locks API (`navigator.locks`): a tab requests an EXCLUSIVE lock keyed by
+ * the durable-store namespace and holds it — via a promise that resolves only on
+ * release — for as long as it should be leader. The browser grants the lock to
+ * exactly one waiter at a time and AUTO-RELEASES it on tab crash/close/navigation
+ * with no heartbeat, so the next waiting tab becomes leader instantly and there
+ * is never a stuck lock.
+ *
+ * Why Web Locks over a BroadcastChannel election (v1 decision, locked): Web
+ * Locks gives crash-safe, race-free, browser-arbitrated exclusion for free —
+ * a hand-rolled BroadcastChannel election has to solve liveness (heartbeats,
+ * takeover on a silent crash) itself. BroadcastChannel is a possible future
+ * enhancement (cross-tab state fan-out), not the election primitive.
+ *
+ * ## Single-tab fallback (documented gap)
+ *
+ * When `navigator.locks` is absent (older Safari, non-browser hosts), this warns
+ * ONCE and falls back to acquiring leadership immediately and unconditionally.
+ * The outbox STILL replays — a lone tab is trivially the only replayer — but the
+ * multi-tab exactly-one-replayer guarantee does not hold across tabs that all
+ * took the fallback. This is a deliberate v1 limitation, NOT masked by a
+ * BroadcastChannel shim.
+ *
+ * Engine-free: no `@tanstack/*` import — stays inside the boundary (#1761).
+ */
+/**
+ * A handle to relinquish leadership: call it to release the Web Lock (or cancel
+ * a still-pending request). Idempotent.
+ */
+export type LeadershipHandle = () => void;
+/**
+ * Acquire cross-tab leadership for `lockName` (the outbox's
+ * `smrt-web-outbox-leader:<namespace>`).
+ *
+ * When the lock is granted this tab becomes leader and `onAcquired()` fires; the
+ * tab stays leader — holding the lock — until the returned handle is called (or
+ * the tab dies, when the browser auto-releases). On release, `onReleased()`
+ * fires. Requesting is non-blocking: this returns synchronously with the
+ * release handle while the request waits in the background for its turn.
+ *
+ * Contract:
+ * - The lock is requested EXCLUSIVE; the callback returns a promise that stays
+ *   pending until the release handle resolves it, so the browser considers the
+ *   lock held for exactly that window.
+ * - Calling the handle before the lock is even granted aborts the pending
+ *   request (via `AbortSignal`) so a torn-down engine never becomes leader
+ *   later. `onReleased` still fires so callers can settle their own state.
+ * - No Web Locks support → single-tab fallback: `onAcquired()` fires on the next
+ *   microtask (leadership is immediate and unconditional), the handle just fires
+ *   `onReleased()`.
+ */
+export declare function acquireLeadership(lockName: string, onAcquired: () => void, onReleased: () => void): LeadershipHandle;
+//# sourceMappingURL=leader.d.ts.map

package/dist/offline/leader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader.d.ts","sourceRoot":"","sources":["../../src/offline/leader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC;AAsB1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,IAAI,EACtB,UAAU,EAAE,MAAM,IAAI,GACrB,gBAAgB,CA6ElB"}