@pylonsync/sync 0.3.291 → 0.3.293

package/dist/local-store.d.ts

@@ -0,0 +1,186 @@
+import type { ChangeEvent, Row } from "./types";
+export declare class LocalStore {
+    private tables;
+    /**
+     * `(entity, row_id) → deletedAt seq`. A row in this map has been
+     * deleted; any insert/update event older than its tombstone seq is
+     * ignored so an out-of-order replay can't resurrect it. Without
+     * this, a delete followed by a reconnect-driven replay of the
+     * original insert would re-materialize the row.
+     *
+     * Real server-issued tombstones use the event's own seq. Optimistic
+     * client tombstones live in `optimisticTombstones` instead.
+     */
+    private tombstones;
+    /**
+     * Pending optimistic deletes — `(entity, row_id)` pairs the client
+     * has dropped but the server hasn't yet confirmed. Stored
+     * separately from `tombstones` so the real server-issued delete
+     * (with its real, smaller seq) can supersede the optimistic entry
+     * without being max-merged out.
+     *
+     * Invariant: a future legitimate re-create of the same id must
+     * succeed once the server's authoritative delete arrives. Test:
+     * `optimistic_delete_releases_id_when_server_confirms`.
+     */
+    private optimisticTombstones;
+    private listeners;
+    /** Get all rows for an entity. */
+    list(entity: string): Row[];
+    /** Get a row by ID. */
+    get(entity: string, id: string): Row | null;
+    /** Snapshot of every entity name with at least one local row. Used
+     *  by `SyncEngine.reconcile` to know which tables to diff against
+     *  server truth. */
+    entityNames(): string[];
+    /**
+     * Remove a row whose absence was confirmed by the server-truth
+     * reconciler. Records a tombstone at `tombstoneSeq` so a stale
+     * insert/update replayed afterwards (e.g. a slow WS frame) can't
+     * resurrect it. Callers pass the current sync cursor — any future
+     * change events have higher seqs and pass the tombstone check,
+     * while older replays are filtered.
+     *
+     * Differs from `optimisticDelete`: this is "the server says this
+     * row is gone right now"; that one is "the client wants this row
+     * gone before the server has confirmed."
+     */
+    reconcileRemove(entity: string, id: string, tombstoneSeq: number): boolean;
+    /**
+     * Per-subscriber row revocation: the server signaled that the
+     * current client lost read access to a specific row. ALWAYS
+     * records the tombstone (even when the row isn't in memory), so
+     * a stale insert/update event that arrives after the revocation
+     * can't resurrect the row.
+     *
+     * `reconcileRemove` returns early when the row is absent — that's
+     * the right behavior for "did anything change?" reconcile passes,
+     * but wrong here: a CRDT-only consumer using `useLoroDoc` without
+     * a JSON row never had the row in `tables` to begin with, and
+     * without the tombstone any future server-issued insert
+     * (legitimate re-grant or a slow stale frame) would land.
+     *
+     * Returns true if the row was present + removed; the tombstone
+     * is recorded regardless.
+     */
+    revokeRow(entity: string, id: string, tombstoneSeq: number): boolean;
+    private isTombstoned;
+    private recordTombstone;
+    /** Apply a change event to the local store. */
+    applyChange(change: ChangeEvent): void;
+    /** Apply multiple changes synchronously. Persistence runs fire-
+     *  and-forget. Prefer `applyChangesAsync` when you plan to advance
+     *  a cursor after — otherwise a crash can save the cursor before
+     *  rows hit disk, causing permanent missed changes on restart. */
+    applyChanges(changes: ChangeEvent[]): void;
+    /**
+     * Apply + persist, awaiting disk writes before returning. Callers
+     * that are about to advance a cursor based on `changes` MUST use
+     * this path — otherwise cursor durability is broken: a crash
+     * between the memory apply and the eventual disk write can persist
+     * a cursor that's ahead of the replica, skipping those rows
+     * forever on restart.
+     *
+     * Returns `true` when every persist write reached disk durably,
+     * `false` when at least one degraded (quota / abort). The engine
+     * uses the result to hold the PERSISTED cursor back: a row that
+     * didn't reach disk must not be skipped by an advanced on-disk
+     * cursor on the next cold start. The in-memory replica always
+     * reflects the change regardless.
+     */
+    applyChangesAsync(changes: ChangeEvent[]): Promise<boolean>;
+    /**
+     * Reshape a change event so its `data` field matches the row as it
+     * now exists in memory after `applyChange` merged the patch.
+     * Persistence callers (IndexedDB) save the full row, which only
+     * works if they receive the full row. Deletes pass through
+     * untouched.
+     */
+    private hydrateFromMemory;
+    /** Persistence callback for auto-saving changes. Returns
+     *  `Promise<boolean>` (true = durable, false = degraded) so
+     *  `applyChangesAsync` can gate the on-disk cursor on durability.
+     *  Void-returning callbacks are accepted for backwards compatibility
+     *  (treated as durable / fire-and-forget). */
+    _persistFn: ((change: ChangeEvent) => void | Promise<boolean>) | null;
+    /** Subscribe to store changes. Returns unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+    /** Apply an optimistic insert. Returns a temporary id. */
+    optimisticInsert(entity: string, data: Row): string;
+    /**
+     * Apply an optimistic insert with a caller-provided id.
+     *
+     * Used by `useMutation({ optimistic })`: the React hook generates a
+     * Pylon-shaped id (40-char hex via `generateId()`), threads it
+     * through the mutation args as `_optimisticId`, and the server
+     * function honors it on `ctx.db.insert("Entity", { id, ... })`.
+     * Because the optimistic ghost and the canonical row share the
+     * same row_id, the WS broadcast that follows lands as a field-
+     * level merge on top of the optimistic — no delete-then-replace
+     * flash, no temp-row swap.
+     */
+    optimisticInsertWithId(entity: string, id: string, data: Row): void;
+    /**
+     * Roll back an optimistic insert without leaving a tombstone.
+     *
+     * Counterpart to `optimisticInsertWithId`. On rejection the ghost
+     * row must go away, but we MUST NOT leave a tombstone — a future
+     * legitimate insert with the same id (user retries, workflow
+     * eventually creates the row) must not be blocked.
+     * `optimisticDelete` records a MAX_SAFE_INTEGER tombstone, which is
+     * the wrong semantic here; this is a plain remove.
+     */
+    rollbackOptimisticInsert(entity: string, id: string): void;
+    /** Apply an optimistic update. */
+    optimisticUpdate(entity: string, id: string, data: Partial<Row>): void;
+    /**
+     * Undo a rejected optimistic update/delete by restoring the row to its
+     * captured pre-mutation value and clearing any optimistic tombstone
+     * for it. `failPushedMutation` calls this when the server rejects an
+     * update (restore the prior field values) or a delete (bring the row
+     * back AND un-fence it so the row — and any future server insert of
+     * the id — isn't blocked by the lingering optimistic tombstone).
+     *
+     * `prev === null` means the row didn't exist before the mutation
+     * (e.g. an update on a row that was itself an un-acked insert) — in
+     * that case we just remove it + clear the fence.
+     *
+     * A REAL (server-issued) tombstone wins over the restore: if an
+     * authoritative delete/revocation for this id landed on the applyQueue
+     * while the rejected push was in flight (the opQueue and applyQueue run
+     * independently), resurrecting `prev` here would briefly un-delete a row
+     * the server says is gone — healed only at the next reconcile. So when a
+     * server tombstone is present we drop the row and let the canonical
+     * state stand; the failed mutation's own optimistic fence is cleared
+     * regardless so a later legitimate re-create of the id isn't blocked.
+     */
+    restoreRow(entity: string, id: string, prev: Row | null): void;
+    /** Apply an optimistic delete. Block any incoming insert/update
+     *  for this id until the server's authoritative delete arrives. */
+    optimisticDelete(entity: string, id: string): void;
+    /**
+     * Apply a reconcile result against the local replica. Reconcile is
+     * "the server says these are the canonical rows right now" — it does
+     * NOT carry per-event seqs. Distinct from `applyChange` (which
+     * threads server-issued change events through a monotonic seq
+     * guard + cursor advance).
+     *
+     * `tombstoneSeq` is the cursor at the start of the reconcile fetch.
+     * - Upserts skip rows whose tombstone is fresher (would be stale
+     *   resurrections of a later delete).
+     * - Removals tombstone at `tombstoneSeq` so a later legitimate
+     *   re-create (with a strictly greater seq) flows through.
+     *
+     * Cursor is NOT advanced — reconcile fabricates no real seqs, so
+     * the engine's cursor stays pinned to the change-log position the
+     * reconcile started from.
+     */
+    applyReconcileBatch(entity: string, upserts: Row[], removalIds: string[], tombstoneSeq: number): Promise<void>;
+    /**
+     * Drop every table + tombstone in-place, then notify. Used by the
+     * sync engine's `resetReplica()` on identity flip (token or tenant
+     * changed — the old replica reflects a different visible set).
+     */
+    clearAll(): void;
+}

package/dist/multi-tab-orchestrator.d.ts

@@ -0,0 +1,141 @@
+import type { PendingMutation } from "./mutation-queue";
+import type { SubscriptionCoordinator } from "./subscription-coordinator";
+import type { ChangeEvent, ReactiveMessage, ResolvedSession, Row, SyncCursor } from "./types";
+/** Hooks the engine registers to receive inbound multi-tab events.
+ *  Cases that purely concern subscriptions are NOT routed through
+ *  these — the orchestrator dispatches them directly to its
+ *  `SubscriptionCoordinator` reference. */
+export interface MultiTabOrchestratorHooks {
+    /** Initial promotion (first election settles with this tab as
+     *  leader). Fired before the engine's start() proceeds past
+     *  `initMultiTab()`. */
+    onInitialLeader(): void;
+    /** Late promotion: the previous leader dropped while we were a
+     *  follower. Engine performs recovery (replay subs, pull, drain
+     *  the mutation queue, start the transport). */
+    onLatePromote(): void;
+    /** Demotion: another tab took over as leader. Engine tears down
+     *  its transport. */
+    onDemote(): void;
+    /** Inbound applied-change batch from the current leader. Engine
+     *  enqueues for apply with `fromBroadcast: true` so the queue
+     *  doesn't re-broadcast. */
+    onAppliedReceived(changes: ChangeEvent[], targetCursor: SyncCursor | undefined): void;
+    /** Inbound reconcile batch from the current leader. */
+    onReconciledReceived(entity: string, upserts: Row[], removalIds: string[], tombstoneSeq: number): void;
+    /** Replica reset broadcast from the leader. `wipeMutations` is true
+     *  when the reset was an identity flip (drop the outgoing identity's
+     *  pending offline writes), false for a same-user 410 RESYNC (keep
+     *  them — they survive the snapshot refresh). */
+    onResetReceived(wipeMutations: boolean): void;
+    /** Resolved session update from the leader. Engine funnels through
+     *  its session chain so concurrent triggers commit in order. */
+    onSessionReceived(resolved: ResolvedSession): void;
+    /** Follower → leader: ops the follower wants pushed. Only fires
+     *  when this tab is leader. */
+    onMutationsForwarded(ops: PendingMutation[]): void;
+    /** Leader → follower: op_ids that were successfully pushed. */
+    onMutationsAcked(opIds: string[]): void;
+    /** Leader → follower: op_ids that failed server-side validation. */
+    onMutationsFailed(ops: {
+        opId: string;
+        error: string;
+    }[]): void;
+    /** Leader → follower: a binary frame from the WS. Engine routes
+     *  to its local binary handlers. */
+    onBinaryReceived(bytes: Uint8Array): void;
+    /** A peer tab disappeared (broker observed `bye`). Engine and
+     *  SubscriptionCoordinator both clean up state for the departed tab. */
+    onPeerLeft(tabId: string): void;
+    /** Follower → leader: a follower wants to subscribe to a room.
+     *  Leader-only. Engine increments the per-room forwarder set and
+     *  sends `room-subscribe` to the server if no one else owned it. */
+    onRoomSubRegister?(roomId: string, fromTabId: string): void;
+    /** Follower → leader: a follower's last room subscriber unmounted.
+     *  Leader-only. Engine decrements the forwarder set and sends
+     *  `room-unsubscribe` when both the local refcount and the forwarder
+     *  set are empty. */
+    onRoomSubUnregister?(roomId: string, fromTabId: string): void;
+    /** Leader → followers: a room-snapshot landed on the WS. Followers
+     *  apply it to their local room registry so their subscribers fire. */
+    onRoomFanoutSnapshot?(roomId: string, members: unknown): void;
+    /** Leader → followers: a room-update landed. */
+    onRoomFanoutUpdate?(roomId: string, action: "join" | "leave" | "presence" | "broadcast", member: unknown, data: unknown): void;
+    /** Leader → followers: the server rejected a room-subscribe. */
+    onRoomFanoutError?(roomId: string, error: unknown): void;
+    /** New leader → followers: re-forward your locally-wanted room subs.
+     *  Triggered alongside CRDT/reactive replay after a leader change. */
+    onReplayRoomSubs?(): void;
+    /** Follower → leader: a follower's `useQuery` observed an entity.
+     *  Leader-only. The leader adds it to its reconcile sweep and fetches
+     *  it so a server row the follower never cached is discovered and
+     *  broadcast back as a `reconciled` batch. Without this, a follower's
+     *  view on a never-cached entity stays empty forever. */
+    onEntityObserve?(entity: string, fromTabId: string): void;
+    /** New leader → followers: re-declare your observed entities so the
+     *  new leader's reconcile sweep covers them. */
+    onReplayObservedEntities?(): void;
+    /** New leader → followers: re-forward your pending mutation batch. A
+     *  mutation a follower forwarded to a leader that died before acking is
+     *  otherwise stranded — the new leader only drains its OWN queue on
+     *  promotion, and the other replay hooks cover subs/rooms/entities but
+     *  not mutations. op_id makes the re-forward idempotent. */
+    onReplayForwardedMutations?(): void;
+}
+export interface MultiTabOrchestratorConfig {
+    /** When false, multi-tab coordination is disabled; this tab acts
+     *  as a sole leader. */
+    enabled?: boolean;
+    /** App name used to derive the BroadcastChannel name. Defaults to
+     *  "default" — apps that share an origin can pin their own name
+     *  to avoid cross-talk between unrelated installations. */
+    appName?: string;
+}
+export declare class MultiTabOrchestrator {
+    private readonly config;
+    private readonly subscriptions;
+    private readonly hooks;
+    private broker;
+    private _isLeader;
+    private settled;
+    constructor(config: MultiTabOrchestratorConfig, subscriptions: SubscriptionCoordinator, hooks: MultiTabOrchestratorHooks);
+    /** Bring up the broker and run the initial election. Resolves when
+     *  the election has settled (either onPromote fired, or the
+     *  settle timer expired without a peer claiming leadership).
+     *  Returns true if this tab is now the leader. */
+    init(): Promise<boolean>;
+    stop(): void;
+    isLeader(): boolean;
+    /** No-op when the broker isn't running. The engine uses this for
+     *  envelope shapes the orchestrator doesn't have first-class
+     *  helpers for (currently none — kept as an escape hatch). */
+    broadcastRaw(payload: unknown): void;
+    broadcastApplied(changes: ChangeEvent[], targetCursor?: SyncCursor): void;
+    broadcastReconciled(entity: string, upserts: Row[], removalIds: string[], tombstoneSeq: number): void;
+    broadcastReset(wipeMutations: boolean): void;
+    broadcastSession(resolved: ResolvedSession): void;
+    /** Follower → leader: forward our pending batch. The leader's
+     *  engine handles it via `onMutationsForwarded`. */
+    forwardMutations(ops: PendingMutation[]): void;
+    /** Leader → followers: applied op_ids. Followers mark applied + clear. */
+    broadcastMutationsAcked(opIds: string[]): void;
+    /** Leader → followers: per-op failures with error strings. */
+    broadcastMutationsFailed(ops: {
+        opId: string;
+        error: string;
+    }[]): void;
+    /** Leader → followers: a reactive-result / reactive-error landed on
+     *  the WS. Routed by sub_id to whatever tab owns the local handler. */
+    broadcastReactiveMessage(sub_id: string, payload: ReactiveMessage): void;
+    /** Leader → followers: a binary CRDT frame from the WS. Only
+     *  meaningful when at least one follower has forwarded a CRDT
+     *  sub — caller (engine) gates on `subscriptions.hasCrdtForwarders()`. */
+    broadcastBinary(bytes: Uint8Array): void;
+    /** New leader → followers: re-forward your active sub-registers. */
+    requestSubReplay(): void;
+    /** Public for tests + future debugging. Drives the same path the
+     *  BroadcastChannel's onmessage hits, so a test can simulate any
+     *  inbound envelope without standing up a real channel. The engine
+     *  itself never calls this directly — it goes through the broker. */
+    handleMessage(payload: unknown, fromTabId: string): void;
+}

package/dist/multi-tab.d.ts

@@ -0,0 +1,70 @@
+interface TabIdentity {
+    tabId: string;
+    startTime: number;
+}
+export interface MultiTabHandlers {
+    /** Fired when this tab becomes the leader (initial election or
+     *  promotion after the previous leader dropped). Idempotent —
+     *  called once per promotion. */
+    onPromote: () => void;
+    /** Fired when this tab transitions from leader to follower. Only
+     *  relevant if leader migration is supported (currently no-op
+     *  because the leader stays leader until it dies). */
+    onDemote: () => void;
+    /** Fired for every application-level message from another tab. */
+    onAppMessage: (payload: unknown, from: TabIdentity) => void;
+    /** Fired when another tab leaves the coordination group gracefully
+     *  (its `bye` was observed). The leader uses this to scrub forwarded
+     *  subscription state for the departed tab so it stops fanning WS
+     *  traffic at a dead peer. Does NOT fire for crashed tabs — those
+     *  have no `bye` and currently leak in the roster until either a
+     *  new election runs or this tab itself goes away. */
+    onLeave?: (tabId: string) => void;
+}
+export declare class MultiTabBroker {
+    readonly self: TabIdentity;
+    private channel;
+    /** Roster of currently-known tabs (including self). Maintained via
+     *  `hello` / `here` / `bye`. The smallest entry by
+     *  (startTime, tabId) is the leader. */
+    private roster;
+    private leaderTabId;
+    private lastLeaderHeartbeat;
+    private heartbeatTimer;
+    private monitorTimer;
+    private electionTimer;
+    private handlers;
+    private started;
+    private stopped;
+    /** Whether the broker can run on this platform — `BroadcastChannel`
+     *  is missing in Node/jsdom and old Safari. When false the engine
+     *  treats this tab as the implicit sole leader. */
+    static available(): boolean;
+    /** Begin participating in multi-tab coordination. The handlers
+     *  fire as elections settle. Idempotent — calling twice is a no-op
+     *  so the engine's `start()` can call freely. */
+    start(channelName: string, handlers: MultiTabHandlers): void;
+    /** Tear down. Sends a `bye` so other tabs can re-elect right away. */
+    stop(): void;
+    /** True if this tab is currently the leader. Follower paths use
+     *  this to decide whether to run their own network ops. */
+    isLeader(): boolean;
+    /** Send an application-level payload to every other tab. The
+     *  engine uses this for applied-change / mutation / session
+     *  broadcasts. */
+    broadcastApp(payload: unknown): void;
+    private handleBeforeUnload;
+    private send;
+    private handle;
+    private scheduleElection;
+    private electLeader;
+    /** Smallest (startTime, tabId) wins. Deterministic across every
+     *  tab that has the same roster, so peers converge without voting.
+     *  Used both for the initial election and for sanity-checking
+     *  `lead` claims against our local view. */
+    private computeWinner;
+    private promote;
+    private demote;
+    private checkLeaderLiveness;
+}
+export {};

package/dist/mutation-queue.d.ts

@@ -0,0 +1,88 @@
+import type { ClientChange, Row } from "./types";
+export interface PendingMutation {
+    id: string;
+    change: ClientChange;
+    status: "pending" | "applied" | "failed";
+    error?: string;
+    /** Pre-mutation snapshot of the affected row, captured at optimistic-
+     *  apply time for `update`/`delete`. On a server rejection,
+     *  `failPushedMutation` restores this so the local replica reverts to
+     *  the value the server actually holds. `null` = the row didn't exist
+     *  before the mutation; `undefined` = not captured (inserts). */
+    prevRow?: Row | null;
+}
+/**
+ * Optional persistence backend. The default IndexedDB persistence
+ * layer provides `savePending`/`loadPending`. Callers can supply a
+ * custom backend for tests or alternative storage.
+ */
+export interface MutationQueuePersistence {
+    saveAll(mutations: PendingMutation[]): Promise<void>;
+    loadAll(): Promise<PendingMutation[]>;
+}
+export declare class MutationQueue {
+    private queue;
+    private persistence?;
+    constructor(persistence?: MutationQueuePersistence);
+    /**
+     * Attach a persistence backend after construction. The SyncEngine
+     * swaps in IndexedDB-backed persistence once the DB has opened.
+     * Public so it doesn't need a `// @ts-expect-error` to reach in
+     * from the same package.
+     */
+    attachPersistence(persistence: MutationQueuePersistence): void;
+    /** Load persisted queue state. Call once at startup. */
+    hydrate(): Promise<void>;
+    /** Add a pending mutation. Returns the op_id used for server
+     *  idempotency. If the change ALREADY carries an op_id (e.g., it
+     *  was forwarded from another tab via multi-tab broadcast), reuse
+     *  that id so the leader and follower agree on the identifier the
+     *  server will dedupe against. Likewise we skip the add when an
+     *  entry with the same op_id is already queued — a follower
+     *  retrying its forward of the same op shouldn't double-queue on
+     *  the leader. */
+    add(change: ClientChange, prevRow?: Row | null): string;
+    pending(): PendingMutation[];
+    /** Look up a queued mutation by op id (any status). Used by the
+     *  follower's mutations-failed handler to reach the captured
+     *  `prevRow` for rollback. */
+    get(id: string): PendingMutation | undefined;
+    /**
+     * Set of `${entity}/${row_id}` keys for every mutation currently
+     * in Pending or Failed state. Used by reconcile() to skip rows
+     * whose canonical state on the server hasn't caught up with the
+     * local optimistic ghost yet — otherwise reconcile would tombstone
+     * the row (it's not yet on the server) and the still-pending push
+     * would later re-apply against the tombstone, fighting the local
+     * replica.
+     *
+     * Failed mutations are included too: a user-visible failure is
+     * recoverable, and sweeping the row would discard the local edit
+     * the user is still trying to push.
+     */
+    pendingRowKeys(): Set<string>;
+    markApplied(id: string): void;
+    markFailed(id: string, error: string): void;
+    /**
+     * Prune applied mutations. Failed mutations are KEPT so the UI can
+     * surface them to the user and so retries are possible.
+     */
+    clear(): void;
+    /** Remove a specific mutation by id. Used by the UI after user
+     *  ack of failures. */
+    remove(id: string): void;
+    /**
+     * Drop EVERY mutation — pending, failed, and applied — then flush the
+     * empty queue to disk. Used by the engine's identity-flip reset
+     * (`resetReplica({ wipeMutations: true })`): the queued offline writes
+     * belong to the OUTGOING identity, and replaying them under the new
+     * session would attribute one user's writes to another (or get
+     * policy-rejected on the server). Distinct from `clear()`, which only
+     * prunes already-applied entries and deliberately PRESERVES pending +
+     * failed writes — the 410-RESYNC same-user path relies on that so
+     * offline writes survive a snapshot refresh.
+     */
+    clearAll(): void;
+    /** Fire-and-forget persistence write. */
+    private flush;
+}

package/dist/op-queue.d.ts

@@ -0,0 +1,18 @@
+export declare class OpQueue {
+    private chain;
+    private pending;
+    /** Monotonic op counter — incremented as each op begins running.
+     *  Lets a caller stash a snapshot ("epoch when I scheduled") and
+     *  detect after `await` whether another op ran in between. */
+    private epoch;
+    /** Schedule an op behind any currently running/queued ops.
+     *
+     *  Coalescing: if `key` matches a pending op, the existing promise
+     *  is returned — the new caller does NOT re-enqueue. This preserves
+     *  the "many concurrent callers share one in-flight op" semantics
+     *  that pull/push/reconcile had via their respective mutexes. */
+    enqueue<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** Current epoch — read before scheduling, compare after `await` to
+     *  detect "another op ran while I was waiting." */
+    currentEpoch(): number;
+}

package/dist/persistence.d.ts

@@ -0,0 +1,114 @@
+import type { Row, ChangeEvent, SyncCursor, MutationQueuePersistence, PendingMutation } from "./index";
+/**
+ * IndexedDB-backed persistence for the sync store.
+ * Saves entity rows and sync cursor so data survives page refresh.
+ */
+export declare class IndexedDBPersistence {
+    private db;
+    private dbName;
+    /** Shared connection. Exposed so sibling persistence classes (e.g. the
+     *  mutation-queue backend) can reuse the same IDBDatabase — IndexedDB only
+     *  permits one open handle per (origin, db) at a time while upgrades run.
+     */
+    get connection(): IDBDatabase | null;
+    constructor(appName?: string);
+    open(): Promise<void>;
+    /** Resolve when a write transaction settles, reporting durability:
+     *  `true` on COMMIT, `false` if it aborts/errors — e.g.
+     *  QuotaExceededError on a storage-pressured device. NEVER rejects or
+     *  hangs: registering only `oncomplete` (the original shape) meant an
+     *  aborted tx never settled, and the engine awaits the persist before
+     *  advancing the cursor in `enqueueApply` — so ONE hung write wedged
+     *  the whole applyQueue and live sync silently died for the session.
+     *
+     *  But "resolve unconditionally" (the first fix) was also wrong: on an
+     *  abort the row never reached disk, yet `enqueueApply` still advanced
+     *  the PERSISTED cursor past it — so on restart the warm-load skipped
+     *  those rows forever (cursor ahead of replica). The boolean lets the
+     *  caller hold the on-disk cursor back when a row write fails, so the
+     *  next cold start re-pulls the gap. Best-effort: log once, keep the
+     *  in-memory replica authoritative, but never persist a cursor ahead of
+     *  what's actually durable. Mirrors the read paths (`getRow`/
+     *  `loadCursor`) which already degrade via `onerror`. */
+    private commit;
+    /** Save a row to IndexedDB. Resolves `true` when the write is durable,
+     *  `false` if it degraded (no DB / aborted) — see `commit`. */
+    saveRow(entity: string, id: string, data: Row): Promise<boolean>;
+    /** Fetch a row from IndexedDB by key. Used by `persistChange` on update
+     *  events to merge the patch against what's already on disk. */
+    getRow(entity: string, id: string): Promise<Row | null>;
+    /** Delete a row from IndexedDB. Resolves `true` when durable, `false`
+     *  if it degraded — see `commit`. */
+    deleteRow(entity: string, id: string): Promise<boolean>;
+    /** Load all rows for an entity from IndexedDB. */
+    loadAll(entity: string): Promise<Row[]>;
+    /** Load all entities and their rows from IndexedDB. */
+    loadAllEntities(): Promise<Record<string, Row[]>>;
+    /**
+     * Atomic warm-load: returns entities + cursor in a single IDB
+     * read transaction. Used by `SyncEngine.start()` to hydrate the
+     * in-memory replica BEFORE the network pull resolves so React
+     * hooks see real data on first render (no empty-then-populated
+     * flash on returning visits).
+     *
+     * `hadCache` is true when at least one row OR a saved cursor
+     * was found. The engine uses it to distinguish "true cold start
+     * — pull-from-0 IS a full snapshot, skip the post-snapshot
+     * reconcile" from "returning user with cached state — pull-from-
+     * cursor may miss server-side deletes that happened offline, the
+     * onConnected reconcile MUST run". Without that distinction, a
+     * returning user whose cursor somehow rolled back to 0 (rare:
+     * IDB partial corruption, cleared-by-mistake) would end up with
+     * ghost rows that survive forever.
+     *
+     * Single readonly tx is intentional — two separate reads could
+     * race a mid-load saveCursor/saveRow from another tab's apply
+     * pipeline and read an inconsistent (cursor C', rows for cursor C)
+     * pair. One tx guarantees a consistent snapshot.
+     */
+    loadSnapshot(): Promise<{
+        entities: Record<string, Row[]>;
+        cursor: SyncCursor | null;
+        hadCache: boolean;
+    }>;
+    /** Save the sync cursor. Resolves `true` when durable, `false` if it
+     *  degraded — see `commit`. */
+    saveCursor(cursor: SyncCursor): Promise<boolean>;
+    /** Load the sync cursor. */
+    loadCursor(): Promise<SyncCursor | null>;
+    /** Clear stored rows + cursor. Deliberately does NOT touch the
+     *  durable mutation queue: `resetReplica` calls this on a 410 RESYNC
+     *  (same user, needs a fresh snapshot) where pending offline writes
+     *  MUST survive. On an IDENTITY flip the old identity's pending
+     *  mutations must instead be discarded — that wipe runs through
+     *  `MutationQueue.clearAll()` (which persists an empty `MUTATIONS_STORE`
+     *  via its own backend), gated on `resetReplica({ wipeMutations })` at
+     *  the token/tenant-flip call sites. Splitting the two stores keeps each
+     *  reset path honest: 410 keeps writes, identity flip drops them. */
+    clear(): Promise<boolean>;
+}
+/**
+ * Apply a change event to IndexedDB persistence. Returns `true` when the
+ * write reached disk durably, `false` when it degraded (so `enqueueApply`
+ * can hold the persisted cursor back rather than skip the row on restart).
+ * A change with no `data` is a no-op and counts as durable.
+ */
+export declare function persistChange(persistence: IndexedDBPersistence, change: ChangeEvent): Promise<boolean>;
+/**
+ * IndexedDB-backed implementation of `MutationQueuePersistence`. Wires the
+ * `MutationQueue` into the same database as the entity mirror so everything
+ * the app needs to resume a session lives in one place.
+ *
+ * `saveAll` writes the entire queue on every change. That's O(n) per write,
+ * but `n` is bounded by "how many mutations the user queued while offline",
+ * which is tiny in practice. If that ever becomes a bottleneck, switch to
+ * per-id `put`/`delete` — the schema (`keyPath: "id"`) already supports it.
+ */
+export declare class IndexedDBMutationPersistence implements MutationQueuePersistence {
+    private readonly parent;
+    private db;
+    constructor(parent: IndexedDBPersistence);
+    private handle;
+    saveAll(mutations: PendingMutation[]): Promise<void>;
+    loadAll(): Promise<PendingMutation[]>;
+}