@syncular/client 0.1.3 → 0.2.1

package/dist/client.js

@@ -1,219 +1,1683 @@
-import { isSyncularOfflineError } from './errors.js';
-import { browserSyncularNetworkStatusSource } from './network.js';
-export function getSyncularClientStatus(client) {
-    const lifecycle = client.lifecycleState();
-    const connection = client.connectionState();
-    const outbox = lifecycle.outbox ?? null;
-    const conflicts = lifecycle.conflicts ?? null;
+/**
+ * SyncClient — the B3 client protocol core (SPEC.md §§3–8 client side).
+ *
+ * A plain library running on whatever thread it is constructed on
+ * (worker-OPTIONAL, REVISE B3): storage behind `ClientDatabase`, network
+ * behind `SyncTransport`/`SegmentDownloader`/`RealtimeConnector`, multi-tab
+ * ownership behind `LeaderLock`. One combined push+pull request per
+ * `sync()` round (§7.2); local reads go straight to the database.
+ */
+import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
+import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
+import { clearPendingUpload, computeBlobId, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, reconcileBlobRefcounts, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
+import { ClientSyncError } from './errors.js';
+import { Invalidation, InvalidationEmitter, } from './invalidation.js';
+import { singleOwnerLock, } from './leader-lock.js';
+import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, OutboxEncodeError, } from './outbox.js';
+import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalSchema, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, } from './schema.js';
+import { deleteSubscription, getMeta, getSubscription, loadSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
+import { deletePendingEviction, deleteWindowUnit, deriveSubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
+/** True iff `unit` is windowed-in for this snapshot (a registry hit, I3). */
+export function windowComplete(state, unit) {
+    return state.units.includes(unit);
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+/** §4.2 accept bits the client cares about. */
+const ACCEPT_ROWS_BASELINE = 0b0011;
+const ACCEPT_SQLITE = 1 << 2;
+const ACCEPT_SIGNED_URLS = 1 << 3;
+/**
+ * §7.4.4 client-local code: a pending outbox commit cannot re-encode under
+ * the new generated schema after a bump (a referenced column is gone).
+ * Never a wire code (§10.3) — surfaced through the rejection channel.
+ */
+const OUTBOX_INCOMPATIBLE_CODE = 'sync.outbox_incompatible';
+/** §6.1 per-request operation cap (matches the server's shipped default —
+ * `sync.too_many_operations` above it). The push half sends whole commits in
+ * commit order up to this cap and defers the rest to the next round. */
+const MAX_OPS_PER_REQUEST = 500;
+async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function emptySummary(pushed) {
     return {
-        lifecycle,
-        connection,
-        outbox,
-        conflicts,
-        isConnected: connection.realtime === 'connected' && !connection.closed,
-        isSyncing: lifecycle.phase === 'syncing' || lifecycle.phase === 'recovering',
-        hasPendingMutations: (outbox?.pending ?? 0) + (outbox?.sending ?? 0) > 0,
-        hasConflicts: (conflicts?.unresolved ?? 0) > 0,
-        requiresAction: lifecycle.requiresAction,
+        pushed,
+        applied: [],
+        rejected: [],
+        retryable: [],
+        conflicts: [],
+        commitsApplied: 0,
+        segmentRowsApplied: 0,
+        resets: [],
+        revoked: [],
+        failed: [],
     };
 }
-export class SyncularClientLifecycle {
-    client;
-    options;
+export class SyncClient {
+    #config;
+    #db;
+    #schema;
+    /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
+    #encryption;
+    #now;
     #started = false;
-    #pollTimer;
-    #unsubscribeDiagnostics;
-    #unsubscribeNetwork;
-    #syncInFlight;
-    #queuedSyncWaiters = [];
-    #hasConnectedRealtime = false;
-    #realtimeStarted = false;
-    #network;
-    constructor(client, options = {}) {
-        this.client = client;
-        this.options = options;
-        this.#network =
-            options.network === false
-                ? undefined
-                : (options.network ?? browserSyncularNetworkStatusSource());
+    #lease;
+    #clientId = '';
+    #schemaFloor;
+    #leaseState;
+    /** §7.4.5: true while a schema-bump reset + first bootstrap is in flight. */
+    #upgrading = false;
+    #conflicts = [];
+    #rejections = [];
+    #socket;
+    #pendingRound;
+    #needsPull = false;
+    #syncing = false;
+    /**
+     * True from the synchronous entry of `sync()` until its serialized round
+     * settles — the "one loop owns the database" guard that rejects a
+     * concurrent `sync()` before the op chain would queue it. Distinct from
+     * `#syncing`, which is true only while `#runSync`'s body actually runs
+     * (the fast-bail the delta path reads).
+     */
+    #syncOutstanding = false;
+    #hasBlobs;
+    /** §8.6 presence: scopeKey → (peerKey `actorId clientId` → peer). */
+    #presence = new Map();
+    /** TODO 3.1 / I1: the ONE apply-path invalidation listener set. */
+    #invalidation = new InvalidationEmitter();
+    /** §8.6: subscribable presence-change listeners (twin of onPresence). */
+    #presenceListeners = new Set();
+    /** The batch accumulator; non-undefined only inside `#applyBatch`. */
+    #batch;
+    /**
+     * Operation-serialization mutex (the core owns one loop). Every
+     * transaction-entering ASYNC operation — `sync`, the delta-apply body, and
+     * `setWindow` — runs to completion under this chain so no two interleave at
+     * an `await` point. This is the single guard that keeps the apply seam
+     * atomic: two `#processResponse` runs must never share the `#batch`
+     * accumulator or interleave their SQLite transactions (a delta arriving
+     * mid-`await this.#downloadSegment` of a pull, or a `setWindow` widen racing
+     * a delta). Synchronous ops (`mutate`, schema reset) never join the chain —
+     * single-threaded JS cannot interleave them, and because an async op holds
+     * no OPEN db transaction (and no installed `#batch`) across its awaits only
+     * while it is NOT actively running, a sync op can only land between chained
+     * sections, when the seam is quiescent.
+     */
+    #opChain = Promise.resolve();
+    constructor(config) {
+        this.#config = config;
+        this.#db = config.database;
+        this.#schema = compileClientSchema(config.schema);
+        this.#encryption = config.encryption;
+        this.#now = config.now ?? Date.now;
+        this.#hasBlobs = schemaHasBlobs(this.#schema);
     }
+    // -- lifecycle ------------------------------------------------------------
+    /** Acquire leadership, create local tables, resolve the clientId. */
     async start() {
         if (this.#started)
             return;
+        const lock = this.#config.leaderLock ?? singleOwnerLock();
+        this.#lease = await lock.acquire(this.#config.lockName ?? 'syncular-leader');
+        ensureLocalSchema(this.#db, this.#schema);
+        if (this.#hasBlobs)
+            ensureBlobSchema(this.#db);
+        const persisted = getMeta(this.#db, 'clientId');
+        this.#clientId = this.#config.clientId ?? persisted ?? crypto.randomUUID();
+        if (persisted !== this.#clientId) {
+            setMeta(this.#db, 'clientId', this.#clientId);
+        }
+        // §7.3.5: restore the persisted lease so leaseState survives restart.
+        const leaseJson = getMeta(this.#db, 'leaseState');
+        if (leaseJson !== undefined) {
+            this.#leaseState = JSON.parse(leaseJson);
+        }
+        // §7.4.2 trigger 1: the persisted local schema version differs from the
+        // generated version this client ships — run the wipe/re-bootstrap reset
+        // before the first sync round. A fresh install (no marker) is treated as
+        // already at the generated version.
+        this.#detectAndResetSchema();
         this.#started = true;
-        this.#hasConnectedRealtime =
-            this.client.connectionState().realtime === 'connected';
-        this.#realtimeStarted = this.#hasConnectedRealtime;
-        this.#unsubscribeDiagnostics = this.client.addDiagnosticListener((event) => this.#handleDiagnostic(event));
-        this.#unsubscribeNetwork = this.#subscribeNetworkEvents();
+    }
+    /**
+     * §7.4.1/§7.4.2: compare the generated schema version to the persisted
+     * marker and run the §7.4.3 reset when they differ. Idempotent by the
+     * marker — a mid-reset crash re-runs the reset on the next boot.
+     */
+    #detectAndResetSchema() {
+        const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
+        if (markerJson === undefined) {
+            // Fresh install: the tables just created match the running code.
+            setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
+            return;
+        }
+        const marker = Number(markerJson);
+        if (marker === this.#schema.version)
+            return;
+        this.#runSchemaReset();
+    }
+    /**
+     * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
+     * and leaseState. Drops/recreates every synced table from the new schema,
+     * resets subscription sync-state (keeping registrations), clears any
+     * schema-floor stop state, rewrites the marker, and raises `upgrading`.
+     * The bump is idempotent by the marker (rewritten last).
+     */
+    #runSchemaReset() {
+        this.#setUpgrading(true);
+        this.#applyBatch((batch) => {
+            this.#db.transaction(() => {
+                dropAndRecreateSyncedTables(this.#db, this.#schema);
+                resetSubscriptionsForBump(this.#db);
+                setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
+            });
+            // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
+            for (const table of this.#schema.tables.values())
+                batch.table(table.name);
+        });
+        // The stop state is over: this client now ships a servable schema. The
+        // outbox is re-applied optimistically over the (now empty) tables so
+        // pending offline writes stay visible across the bump (§7.4.5).
+        this.#schemaFloor = undefined;
+        this.#replayOutbox();
+    }
+    #setUpgrading(upgrading) {
+        if (this.#upgrading === upgrading)
+            return;
+        this.#upgrading = upgrading;
+        this.#config.onUpgrading?.(upgrading);
+    }
+    async close() {
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.#abortPendingRound('client closed mid-round');
+        await this.#lease?.release();
+        this.#lease = undefined;
+        this.#started = false;
+    }
+    // -- accessors ------------------------------------------------------------
+    get clientId() {
+        return this.#clientId;
+    }
+    /** The underlying database — raw SQL is the local query API (B3). */
+    get database() {
+        return this.#db;
+    }
+    query(sql, params) {
+        return this.#db.query(sql, params);
+    }
+    // -- live-query invalidation (TODO 3.1 / DESIGN-eviction I1–I4) -----------
+    /**
+     * Subscribe to fine-grained invalidation. The callback fires ONCE per
+     * apply batch (never per row, I1) with the `{tables, scopeKeys}` touched
+     * this batch (§3.1 vocabulary, I2). Returns an unsubscribe function.
+     *
+     * Every local mutation flows through the same choke point: `COMMIT`
+     * apply, segment apply, the optimistic overlay rebuild, the §3.3 purge,
+     * the §7.4.3 schema-bump reset, and local `mutate`. `tables` is the
+     * reliable floor; `scopeKeys` refines it wherever the source carried
+     * per-row scopes (COMMIT changes) or a scope map (segments/purge).
+     */
+    onInvalidate(listener) {
+        return this.#invalidation.on(listener);
+    }
+    /**
+     * Run `fn` as one apply batch: install a fresh accumulator, collect every
+     * touched key, then emit exactly one coalesced event if anything changed.
+     * Re-entrant calls share the outer batch so a nested apply never
+     * double-emits (e.g. purge → blob reconcile → replay inside one round).
+     */
+    #applyBatch(fn) {
+        if (this.#batch !== undefined)
+            return fn(this.#batch);
+        const batch = new Invalidation();
+        this.#batch = batch;
+        try {
+            return fn(batch);
+        }
+        finally {
+            this.#batch = undefined;
+            const event = batch.finish();
+            if (event !== undefined)
+                this.#invalidation.emit(event);
+        }
+    }
+    /**
+     * Run `fn` as the next link in the operation-serialization chain
+     * ({@link #opChain}): it starts only after every previously-serialized
+     * operation has fully settled, so transaction-entering async operations
+     * never interleave at an await point. Both chain branches settle to
+     * `undefined` so one operation's rejection never poisons the next
+     * (mirrors the worker host's `serializedSync`). NOT re-entrant: a
+     * serialized operation must not call another serialized operation, or it
+     * would deadlock waiting on itself.
+     */
+    #serialize(fn) {
+        const next = this.#opChain.then(fn, fn);
+        this.#opChain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    /** Async twin of {@link #applyBatch} for the pull/delta apply round. */
+    async #applyBatchAsync(fn) {
+        if (this.#batch !== undefined)
+            return fn(this.#batch);
+        const batch = new Invalidation();
+        this.#batch = batch;
         try {
-            if (this.options.subscriptions) {
-                await this.client.setSubscriptions(this.options.subscriptions);
+            return await fn(batch);
+        }
+        finally {
+            this.#batch = undefined;
+            const event = batch.finish();
+            if (event !== undefined)
+                this.#invalidation.emit(event);
+        }
+    }
+    // -- blobs (§5.9) ---------------------------------------------------------
+    /**
+     * Stage a blob for attachment (§5.9.7): hash the bytes into the content
+     * address, cache them locally, and queue the upload (flushed before the
+     * next push — B4). Returns the canonical `BlobRef` **string** to store in
+     * a `blob_ref` column of a mutation. The referencing row MUST be written
+     * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
+     */
+    async uploadBlob(bytes, options) {
+        if (this.#config.blobs === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
+        }
+        const blobId = await computeBlobId(bytes);
+        this.#db.transaction(() => {
+            putCachedBlob(this.#db, blobId, bytes, this.#now(), options?.mediaType);
+            recordPendingUpload(this.#db, blobId, this.#now(), options?.mediaType);
+        });
+        // §5.9.7 B1: a staged upload is pinned (recordPendingUpload), so the cap
+        // trim below will never evict it — but a stage may push other zero-ref
+        // bodies over the cap, so run the trim.
+        this.#enforceBlobCacheCap();
+        return {
+            blobId,
+            byteLength: bytes.length,
+            ...(options?.mediaType !== undefined
+                ? { mediaType: options.mediaType }
+                : {}),
+            ...(options?.name !== undefined ? { name: options.name } : {}),
+        };
+    }
+    /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
+    blobRefString(ref) {
+        return serializeBlobRef(ref);
+    }
+    /**
+     * Resolve blob bytes for a `blobId` (§5.9.7): a content-addressed cache
+     * hit serves without a network fetch (B1); a miss downloads via the blob
+     * transport (§5.9.5), verifies the content address, caches, and returns.
+     * Accepts a raw `blob_ref` column string or a bare `blobId`.
+     */
+    async fetchBlob(blobIdOrRef) {
+        const blobId = blobIdOrRef.startsWith('sha256:')
+            ? blobIdOrRef
+            : parseBlobRef(blobIdOrRef).blobId;
+        const cached = getCachedBlob(this.#db, blobId, this.#now());
+        if (cached !== undefined)
+            return cached;
+        const transport = this.#config.blobs;
+        if (transport === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
+        }
+        // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
+        // presign configured) a signed url the client fetches directly. On a url
+        // arm the client MUST NOT attach host auth and MUST NOT fall through:
+        // failure => re-request, the caller's next fetchBlob mints a fresh url.
+        const response = await transport.download(blobId);
+        let bytes;
+        if (response.kind === 'url') {
+            if (transport.fetchUrl === undefined) {
+                throw new ClientSyncError('sync.invalid_request', 'blob download returned a url but the transport cannot fetch urls (§5.9.5)');
             }
-            if (this.options.initialSync !== false && this.#isOnline()) {
-                await this.#syncForLifecycle();
+            if (response.urlExpiresAtMs !== undefined &&
+                response.urlExpiresAtMs <= this.#now()) {
+                // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
+                throw new ClientSyncError('sync.segment_expired', `blob url for ${blobId} expired before fetch — re-request mints a fresh url (§5.9.5)`, true);
             }
-            if (this.options.realtime !== false && this.#isOnline()) {
-                await this.#startRealtimeForLifecycle();
+            bytes = await transport.fetchUrl(response.url);
+        }
+        else {
+            bytes = response.bytes;
+        }
+        const computed = await computeBlobId(bytes);
+        if (computed !== blobId) {
+            // §5.9.5 inherits §5.1: verify the content address, reject on mismatch.
+            // On the url path this invalidates the fetch (no fall-through) — the
+            // next fetchBlob re-requests the authorized endpoint (§5.9.5 recovery).
+            throw new ClientSyncError('sync.invalid_request', `blob content address mismatch for ${blobId} (§5.9.5)`);
+        }
+        putCachedBlob(this.#db, blobId, bytes, this.#now());
+        this.#enforceBlobCacheCap();
+        const stored = getCachedBlob(this.#db, blobId);
+        if (stored === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'blob cache write failed');
+        }
+        return stored;
+    }
+    /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
+    #enforceBlobCacheCap() {
+        const cap = this.#config.blobCacheMaxBytes;
+        if (cap === undefined)
+            return;
+        enforceBlobCacheCap(this.#db, cap);
+    }
+    /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
+    async flushBlobUploads() {
+        const transport = this.#config.blobs;
+        if (transport === undefined || !this.#hasBlobs)
+            return;
+        for (const pending of listPendingUploads(this.#db)) {
+            const cached = getCachedBlob(this.#db, pending.blobId);
+            if (cached === undefined) {
+                // The bytes are gone (never happens for a well-behaved client);
+                // drop the upload so it does not wedge the queue.
+                clearPendingUpload(this.#db, pending.blobId);
+                continue;
             }
-            this.#startPolling();
+            await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType);
+            clearPendingUpload(this.#db, pending.blobId);
         }
-        catch (error) {
-            await this.stop().catch(() => undefined);
-            throw error;
+    }
+    /**
+     * §5.9.3: upload one blob, preferring the presigned direct-to-storage grant
+     * when the transport supports it, else streaming through the direct endpoint
+     * (capability, not fallback). A `url` grant PUTs direct with no host auth; on
+     * a grant PUT failure the client streams through the direct endpoint — a
+     * *different, host-authenticated capability*, not a fall-through of the
+     * grant's authority (the direct endpoint was always the other path, B4).
+     */
+    async #uploadOne(transport, blobId, bytes, mediaType) {
+        if (transport.uploadGrant !== undefined &&
+            transport.uploadToUrl !== undefined) {
+            const grant = await transport.uploadGrant(blobId, bytes.length, mediaType);
+            if (grant.kind === 'present')
+                return; // idempotent §5.9.3 — no PUT needed
+            if (grant.kind === 'url') {
+                if (grant.urlExpiresAtMs === undefined ||
+                    grant.urlExpiresAtMs > this.#now()) {
+                    try {
+                        await transport.uploadToUrl(grant.url, bytes, mediaType);
+                        return;
+                    }
+                    catch {
+                        // Grant PUT failed — stream through the direct endpoint below.
+                    }
+                }
+            }
+            // grant.kind === 'none' (no presign store) or a failed/expired grant:
+            // stream through the direct host-authenticated endpoint.
         }
+        await transport.upload(blobId, bytes, mediaType);
+    }
+    get conflicts() {
+        return this.#conflicts;
+    }
+    get rejections() {
+        return this.#rejections;
+    }
+    /** Non-undefined once the server declared a schema floor (§1.6). */
+    get schemaFloor() {
+        return this.#schemaFloor;
+    }
+    /**
+     * §7.4.5: true while a schema-bump reset + first re-bootstrap is in
+     * flight — the app's "upgrading…" cue. Clears when the first post-reset
+     * bootstrap round reaches idle (every subscription past its fresh
+     * bootstrap).
+     */
+    get upgrading() {
+        return this.#upgrading;
+    }
+    /**
+     * §7.3.5: the current auth-lease state (opaque). Undefined until a
+     * `LEASE` frame arrives. `errorCode` is set when a round was rejected
+     * with a request-level lease code — syncing on the lease has stopped.
+     */
+    get leaseState() {
+        return this.#leaseState;
+    }
+    /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
+     * `undefined` if no lease is held. Negative once expired. */
+    leaseRemainingMs(now = this.#now()) {
+        const expiresAtMs = this.#leaseState?.expiresAtMs;
+        return expiresAtMs === undefined ? undefined : expiresAtMs - now;
+    }
+    /** True when syncing is stopped pending a client upgrade. */
+    get stopped() {
+        return this.#schemaFloor !== undefined;
+    }
+    /** §8: a hello/wake-up asked for a pull that has not run yet. */
+    get syncNeeded() {
+        return this.#needsPull;
+    }
+    /**
+     * §8.6 presence on a scope key: the current peers present there (a map
+     * of `actorId clientId` → peer). Empty for a key with no present peers.
+     * Ephemeral — reflects only what the socket has delivered.
+     */
+    presence(scopeKey) {
+        const peers = this.#presence.get(scopeKey);
+        return peers === undefined ? [] : [...peers.values()];
+    }
+    /** Every scope key this client currently has presence state for. */
+    presenceKeys() {
+        return [...this.#presence.keys()];
     }
-    async stop() {
-        if (!this.#started)
+    /**
+     * §8.6: subscribe to presence changes (join/update/leave on any held key).
+     * The subscribable twin of the `onPresence` config callback — React's
+     * `usePresence` targets this so many components can watch one client.
+     * Returns an unsubscribe function.
+     */
+    onPresence(listener) {
+        this.#presenceListeners.add(listener);
+        return () => {
+            this.#presenceListeners.delete(listener);
+        };
+    }
+    /**
+     * §8.6.2 publish (or clear, `doc: null`) this client's presence document
+     * for `scopeKey`. Requires a live socket; the document is ephemeral and
+     * lost on disconnect (the server emits leave). Authorization is the
+     * connection's registration (§8.6.3) — an unheld key is rejected loudly
+     * by the server with `presence.forbidden`.
+     */
+    setPresence(scopeKey, doc) {
+        this.#requireStarted();
+        const socket = this.#socket;
+        if (socket === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'setPresence requires a connected realtime socket (§8.6)');
+        }
+        socket.send(encodePresencePublish(scopeKey, doc));
+    }
+    /**
+     * §4.2 accept mask: the configured override, or the rows baseline plus
+     * bit 2 when the backend can import sqlite images (§5.3) and a segment
+     * downloader exists (sqlite segments are never inline, §5.7), plus
+     * bit 3 when the downloader exposes a direct URL fetch (§5.4
+     * capability negotiation).
+     */
+    #acceptMask() {
+        const configured = this.#config.limits?.accept;
+        if (configured !== undefined)
+            return configured;
+        const segments = this.#config.segments;
+        const sqliteCapable = typeof this.#db.withSqliteImage === 'function' && segments !== undefined;
+        const urlCapable = typeof segments?.fetchUrl === 'function';
+        return (ACCEPT_ROWS_BASELINE |
+            (sqliteCapable ? ACCEPT_SQLITE : 0) |
+            (urlCapable ? ACCEPT_SIGNED_URLS : 0));
+    }
+    subscriptions() {
+        this.#requireStarted();
+        return loadSubscriptions(this.#db);
+    }
+    subscription(id) {
+        this.#requireStarted();
+        return getSubscription(this.#db, id);
+    }
+    pendingCommits() {
+        this.#requireStarted();
+        return listOutbox(this.#db);
+    }
+    // -- subscriptions ----------------------------------------------------------
+    subscribe(input) {
+        this.#requireStarted();
+        if (!this.#schema.tables.has(input.table)) {
+            throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
+        }
+        const existing = getSubscription(this.#db, input.id);
+        if (existing !== undefined) {
+            saveSubscription(this.#db, {
+                ...existing,
+                table: input.table,
+                scopes: input.scopes,
+                ...(input.params !== undefined ? { params: input.params } : {}),
+            });
             return;
-        this.#started = false;
-        this.#stopPolling();
-        this.#unsubscribeDiagnostics?.();
-        this.#unsubscribeDiagnostics = undefined;
-        this.#unsubscribeNetwork?.();
-        this.#unsubscribeNetwork = undefined;
-        this.#rejectQueuedSyncWaiters(new Error('Syncular lifecycle stopped before queued sync could run'));
-        if (this.options.realtime !== false) {
-            await this.client.stopRealtime();
-        }
-        this.#realtimeStarted = false;
-    }
-    async sync() {
-        if (this.#syncInFlight) {
-            return new Promise((resolve, reject) => {
-                this.#queuedSyncWaiters.push({ resolve, reject });
+        }
+        saveSubscription(this.#db, {
+            id: input.id,
+            table: input.table,
+            scopes: input.scopes,
+            ...(input.params !== undefined ? { params: input.params } : {}),
+            cursor: -1,
+            status: 'active',
+        });
+    }
+    unsubscribe(id) {
+        this.#requireStarted();
+        deleteSubscription(this.#db, id);
+    }
+    // -- windowed subscriptions (§4.8) ------------------------------------------
+    /**
+     * Set the live window units for a base (§4.8): a value-sharded family of
+     * subscriptions, one per unit. Computes the diff against the registry —
+     * added units get fresh subscriptions (image-lane bootstrap on the next
+     * sync); removed units are unsubscribed and evicted, fused in one local
+     * transaction (E1–E4). Idempotent: calling with the same units is a
+     * no-op. Re-entry (a unit removed then re-added) cancels any deferred
+     * eviction and fresh-bootstraps.
+     *
+     * The change takes effect on the next `sync()`/socket round — the pull's
+     * subscription list (now with the added unit, without the removed one)
+     * re-registers realtime at round end (§8.7). No socket cycle needed.
+     */
+    async setWindow(base, units) {
+        this.#requireStarted();
+        const table = this.#table(base.table);
+        if (!table.scopeColumnByVariable.has(base.variable)) {
+            throw new ClientSyncError('sync.invalid_request', `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
+        }
+        // Serialize the whole window edit: it spans an `await deriveSubId` between
+        // db transactions, so without the chain a delta apply (or a concurrent
+        // setWindow) could interleave its transactions and corrupt the registry.
+        await this.#serialize(async () => {
+            const baseKey = windowBaseKey(base);
+            const wanted = new Set(units);
+            const live = loadWindowUnits(this.#db, baseKey);
+            const liveByUnit = new Map(live.map((u) => [u.unit, u.subId]));
+            // Widen: units wanted but not live → fresh subscription + registry row.
+            for (const unit of wanted) {
+                if (liveByUnit.has(unit))
+                    continue;
+                const subId = await deriveSubId(base, unit);
+                this.#db.transaction(() => {
+                    // Re-entry cancels any deferred eviction for this sub id.
+                    deletePendingEviction(this.#db, subId);
+                    insertWindowUnit(this.#db, baseKey, unit, subId);
+                    saveSubscription(this.#db, {
+                        id: subId,
+                        table: base.table,
+                        scopes: unitScopes(base, unit),
+                        ...(base.params !== undefined ? { params: base.params } : {}),
+                        cursor: -1,
+                        status: 'active',
+                    });
+                });
+            }
+            // Shrink: units live but not wanted → unsubscribe fused with eviction.
+            for (const { unit, subId } of live) {
+                if (wanted.has(unit))
+                    continue;
+                this.#evictUnit(baseKey, base, unit, subId);
+            }
+        });
+    }
+    /**
+     * The completeness oracle (§4.8 I3): which units of a base are windowed-in
+     * locally, and a per-unit verdict a live query renders "may be partial"
+     * from. A query whose scope footprint includes an un-windowed unit is
+     * NOT answerable in full — the host widens or shows partial, never
+     * silently-complete.
+     */
+    windowState(base) {
+        this.#requireStarted();
+        const baseKey = windowBaseKey(base);
+        return { units: loadWindowUnits(this.#db, baseKey).map((u) => u.unit) };
+    }
+    /**
+     * §4.8 E1–E4: evict one departing unit, fused with its unsubscription in
+     * one transaction. Deletes the unit's rows EXCEPT those pinned by a
+     * pending outbox commit (E1); if any pin remains, records a deferred
+     * eviction retried on the next outbox drain. Discards the subscription's
+     * cursor/resume/effective-echo (E3) and its version state with the rows
+     * (E2). Emits the evicted table's invalidation keys (I1). Fail-closed:
+     * with no local scope-column mapping, surfaces a configuration error and
+     * evicts nothing (§4.8/§3.3).
+     */
+    #evictUnit(baseKey, base, unit, subId) {
+        const table = this.#table(base.table);
+        const sub = getSubscription(this.#db, subId);
+        // The rows a unit holds live under its LAST effective scopes if it ever
+        // synced; before first sync, the requested unit scopes are the match.
+        const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
+        const pinned = this.#pinnedRowIds(base.table);
+        this.#applyBatch((batch) => {
+            this.#db.transaction(() => {
+                const deferred = evictScopedRows(this.#db, table, effective, pinned);
+                deleteWindowUnit(this.#db, baseKey, unit);
+                deleteSubscription(this.#db, subId);
+                if (deferred) {
+                    savePendingEviction(this.#db, subId, base.table, effective);
+                }
+                else {
+                    deletePendingEviction(this.#db, subId);
+                }
+            });
+            // I1: eviction is a bulk delete — a query over the evicted unit re-runs.
+            batch.table(table.name);
+            batch.scopeMap(table, effective);
+        });
+    }
+    /**
+     * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
+     * unit's rows are removed once no pending commit references them; a unit
+     * that re-entered the window in the meantime has no pending record left.
+     */
+    #drainPendingEvictions() {
+        const pending = loadPendingEvictions(this.#db);
+        if (pending.length === 0)
+            return;
+        for (const entry of pending) {
+            const table = this.#schema.tables.get(entry.table);
+            if (table === undefined) {
+                deletePendingEviction(this.#db, entry.subId);
+                continue;
+            }
+            const pinned = this.#pinnedRowIds(entry.table);
+            this.#applyBatch((batch) => {
+                let deferred = false;
+                this.#db.transaction(() => {
+                    deferred = evictScopedRows(this.#db, table, entry.effective, pinned);
+                    if (!deferred)
+                        deletePendingEviction(this.#db, entry.subId);
+                });
+                batch.table(table.name);
+                batch.scopeMap(table, entry.effective);
             });
         }
-        this.#syncInFlight = this.#startSyncCycle();
-        return this.#syncInFlight;
     }
-    #startSyncCycle() {
-        let sync;
+    /**
+     * §4.8 E1: primary keys of `table` referenced by any still-pending outbox
+     * commit — rows that MUST NOT be evicted until the commit drains.
+     */
+    #pinnedRowIds(table) {
+        const pinned = new Set();
+        for (const commit of listOutbox(this.#db)) {
+            for (const op of commit.operations) {
+                if (op.table === table)
+                    pinned.add(op.rowId);
+            }
+        }
+        return pinned;
+    }
+    // -- local mutations --------------------------------------------------------
+    /**
+     * Record one atomic local commit (§7.1): appended to the outbox in
+     * schema-agnostic form and applied optimistically to the local mirror.
+     * Returns the generated `clientCommitId`.
+     */
+    mutate(mutations) {
+        this.#requireStarted();
+        const clientCommitId = crypto.randomUUID();
+        const operations = mutations.map((mutation) => {
+            const table = this.#table(mutation.table);
+            if (mutation.op === 'delete') {
+                return {
+                    table: mutation.table,
+                    rowId: mutation.rowId,
+                    op: 'delete',
+                    ...(mutation.baseVersion !== undefined
+                        ? { baseVersion: mutation.baseVersion }
+                        : {}),
+                };
+            }
+            const values = recordToRowValues(table, mutation.values);
+            const pkValue = values[table.primaryKeyIndex];
+            if (typeof pkValue !== 'string' || pkValue.length === 0) {
+                throw new ClientSyncError('sync.invalid_request', `table ${table.name}: upsert requires a non-empty string primary key`);
+            }
+            const json = {};
+            table.columns.forEach((column, index) => {
+                json[column.name] = rowValueToJson(values[index] ?? null);
+            });
+            return {
+                table: mutation.table,
+                rowId: pkValue,
+                op: 'upsert',
+                ...(mutation.baseVersion !== undefined
+                    ? { baseVersion: mutation.baseVersion }
+                    : {}),
+                values: json,
+            };
+        });
+        this.#applyBatch((batch) => {
+            this.#db.transaction(() => {
+                appendOutboxCommit(this.#db, clientCommitId, operations, this.#now());
+                this.#applyOperationsLocally(operations, batch);
+            });
+        });
+        return clientCommitId;
+    }
+    // -- lease state (§7.3.5) ---------------------------------------------------
+    /** Merge and persist the lease state (opaque, §7.3.5). */
+    #setLeaseState(next) {
+        this.#leaseState = next;
+        setMeta(this.#db, 'leaseState', JSON.stringify(next));
+    }
+    /** The request-level lease error codes (§7.3.4): stop-and-surface. */
+    #isLeaseErrorCode(code) {
+        return (code === 'sync.auth_lease_required' || code === 'sync.auth_lease_revoked');
+    }
+    /**
+     * §7.4.4: encode every pending outbox commit with the current codec. A
+     * commit that cannot re-encode under the new schema (an
+     * `OutboxEncodeError` — a referenced column/table the bump removed) is
+     * dropped from the outbox and surfaced as a rejection (`sync.outbox_
+     * incompatible`); its purely-optimistic rows are undone (§7.2). Returns
+     * the encoded push frames index-aligned with the surviving `outbox`.
+     */
+    async #encodeOutboxForPush() {
+        const pending = listOutbox(this.#db);
+        const pushFrames = [];
+        const outbox = [];
+        let deferred = 0;
+        let ops = 0;
+        for (const commit of pending) {
+            // §6.1 splitBatch: whole commits in commit order, stopping before the
+            // per-request operation cap. A first commit that alone exceeds the cap
+            // is sent alone — the server rejects it loudly rather than the queue
+            // wedging silently. Deferred commits stay queued for the next round.
+            if (outbox.length > 0 &&
+                ops + commit.operations.length > MAX_OPS_PER_REQUEST) {
+                deferred += 1;
+                continue;
+            }
+            try {
+                pushFrames.push(
+                // §5.11: encrypted columns are encrypted at this encode-at-send
+                // seam before the row codec serializes them.
+                await encodeOutboxCommit(this.#schema, commit, this.#encryption));
+                outbox.push(commit);
+                ops += commit.operations.length;
+            }
+            catch (error) {
+                if (error instanceof OutboxEncodeError) {
+                    this.#dropIncompatibleCommit(commit, error.message);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return { pushFrames, outbox, deferred };
+    }
+    /**
+     * §7.4.4: drop a commit that cannot re-encode after a bump, mirroring the
+     * §7.2 `rejected` surface — the commit leaves the outbox, its
+     * purely-optimistic rows are undone, and a rejection record is raised.
+     */
+    #dropIncompatibleCommit(commit, message) {
+        this.#db.transaction(() => {
+            deleteOutboxCommit(this.#db, commit.clientCommitId);
+            for (const operation of commit.operations) {
+                if (operation.op !== 'upsert')
+                    continue;
+                const table = this.#schema.tables.get(operation.table);
+                if (table === undefined)
+                    continue;
+                const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
+                if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
+                    deleteLocalRow(this.#db, table, operation.rowId);
+                }
+            }
+        });
+        this.#rejections.push({
+            clientCommitId: commit.clientCommitId,
+            opIndex: 0,
+            code: OUTBOX_INCOMPATIBLE_CODE,
+            message,
+            retryable: false,
+            ...(commit.operations[0] !== undefined
+                ? { operation: commit.operations[0] }
+                : {}),
+        });
+    }
+    // -- sync -------------------------------------------------------------------
+    /**
+     * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
+     * concurrent `sync()` while one is already outstanding is rejected loudly
+     * (the app must coalesce its own wake-ups, §8.4) — this check is
+     * SYNCHRONOUS so the second caller sees the first still in flight before
+     * the op chain would otherwise queue it. The round then runs serialized on
+     * the operation chain so it never interleaves with a delta apply or a
+     * `setWindow` at an await point.
+     */
+    sync() {
+        this.#requireStarted();
+        if (this.#syncOutstanding) {
+            return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
+        }
+        this.#syncOutstanding = true;
+        return this.#serialize(() => this.#runSync()).finally(() => {
+            this.#syncOutstanding = false;
+        });
+    }
+    async #runSync() {
+        if (this.#schemaFloor !== undefined) {
+            return {
+                ...emptySummary(0),
+                bootstrapping: [],
+                schemaFloor: this.#schemaFloor,
+            };
+        }
+        this.#syncing = true;
+        // Cleared before the round, not after: a wake-up (or a delta dropped
+        // because this pull is mid-flight) that lands during the round must
+        // survive it — the reference server keeps no replay buffer (§8.2).
+        this.#needsPull = false;
         try {
-            sync = Promise.resolve(this.client.syncOnce());
+            // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
+            // them, so the server-side existence check (§6.6) passes.
+            if (this.#hasBlobs && this.#config.blobs !== undefined) {
+                await this.flushBlobUploads();
+            }
+            // §7.4.4: encode the outbox with the CURRENT codec; a commit that
+            // cannot express itself under the new schema (a dropped column/table)
+            // is removed from the push and surfaced as a rejection, never wedging
+            // the queue. `pushFrames` and `outbox` stay index-aligned for result
+            // mapping.
+            const { pushFrames, outbox, deferred } = await this.#encodeOutboxForPush();
+            const subs = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
+            const limits = this.#config.limits;
+            const frames = [
+                {
+                    type: 'REQ_HEADER',
+                    clientId: this.#clientId,
+                    schemaVersion: this.#schema.version,
+                },
+                ...pushFrames,
+                {
+                    type: 'PULL_HEADER',
+                    limitCommits: limits?.limitCommits ?? 0,
+                    limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
+                    maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
+                    accept: this.#acceptMask(),
+                },
+                ...subs.map((sub) => ({
+                    type: 'SUBSCRIPTION',
+                    id: sub.id,
+                    table: sub.table,
+                    scopes: sub.scopes,
+                    ...(sub.params !== undefined ? { params: sub.params } : {}),
+                    cursor: sub.cursor,
+                    ...(sub.bootstrapState !== undefined
+                        ? { bootstrapState: sub.bootstrapState }
+                        : {}),
+                })),
+            ];
+            const requestBytes = encodeMessage({
+                wireVersion: PROTOCOL_WIRE_VERSION,
+                msgKind: 'request',
+                frames,
+            });
+            const responseBytes = await this.#roundTrip(requestBytes);
+            const message = decodeMessage(responseBytes);
+            if (message.msgKind !== 'response') {
+                throw new ClientSyncError('sync.invalid_request', 'transport returned a non-response message');
+            }
+            const summary = await this.#processResponse(message, outbox, subs, 'pull');
+            // §4.8 E1: the push half may have drained commits that pinned rows of
+            // a shrunk window unit — retry any deferred evictions now.
+            this.#drainPendingEvictions();
+            if (deferred > 0) {
+                // §6.1 splitBatch remainder: more queued commits than this request
+                // could carry — keep the sync-needed signal raised for the host.
+                this.#needsPull = true;
+                return { ...summary, deferredCommits: deferred };
+            }
+            return summary;
         }
         catch (error) {
-            sync = Promise.reject(error);
+            // §7.3.5: a request-level lease code stops-and-surfaces — record it
+            // in leaseState (no local-data purge, §7.3.4) and re-throw. Not a
+            // silent retry: the app drives recovery to a live resolver. The
+            // error may arrive as a ClientSyncError or as a transport error
+            // carrying the server's `.code` (HTTP-JSON / loopback surface, §1.1).
+            const code = error.code;
+            if (typeof code === 'string' && this.#isLeaseErrorCode(code)) {
+                this.#setLeaseState({
+                    ...(this.#leaseState ?? {}),
+                    errorCode: code,
+                });
+            }
+            throw error;
         }
-        const finish = () => {
-            if (this.#syncInFlight === sync) {
-                this.#syncInFlight = undefined;
+        finally {
+            this.#syncing = false;
+        }
+    }
+    /**
+     * Pull repeatedly until quiescent: no commits delivered, no bootstrap
+     * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     */
+    async syncUntilIdle(maxRounds = 20) {
+        let last;
+        for (let round = 0; round < maxRounds; round++) {
+            last = await this.sync();
+            if (last.schemaFloor !== undefined)
+                return last;
+            if (last.commitsApplied === 0 &&
+                last.segmentRowsApplied === 0 &&
+                last.bootstrapping.length === 0 &&
+                last.resets.length === 0 &&
+                (last.deferredCommits ?? 0) === 0) {
+                return last;
             }
-            const waiters = this.#queuedSyncWaiters.splice(0);
-            if (waiters.length === 0)
-                return;
-            if (!this.#started) {
-                const error = new Error('Syncular lifecycle stopped before queued sync could run');
-                for (const waiter of waiters)
-                    waiter.reject(error);
-                return;
+        }
+        throw new ClientSyncError('sync.invalid_request', `sync did not reach idle within ${maxRounds} rounds`);
+    }
+    /**
+     * One request/response round trip (§8.7): over the socket whenever it
+     * is connected (Direction decision 1 — the socket IS the sync-round
+     * transport, not a fallback pair), otherwise through the configured
+     * `SyncTransport` seam (loopback/conformance hosts, HTTP-only
+     * producers).
+     */
+    #roundTrip(request) {
+        const socket = this.#socket;
+        if (socket === undefined)
+            return this.#config.transport(request);
+        return new Promise((resolve, reject) => {
+            // sync() already enforces one round in flight (§8.7).
+            this.#pendingRound = {
+                scanner: new MessageStreamScanner(),
+                resolve,
+                reject,
+            };
+            const tagged = new Uint8Array(request.length + 1);
+            tagged[0] = REALTIME_TAG_ROUND;
+            tagged.set(request, 1);
+            try {
+                socket.sendBytes(tagged);
+            }
+            catch (error) {
+                this.#pendingRound = undefined;
+                reject(new ClientSyncError('sync.transport_failed', `socket round send failed: ${error instanceof Error ? error.message : String(error)}`, true));
             }
-            const queued = this.#startSyncCycle();
-            this.#syncInFlight = queued;
-            queued.then((result) => {
-                for (const waiter of waiters)
-                    waiter.resolve(result);
-            }, (error) => {
-                for (const waiter of waiters)
-                    waiter.reject(error);
-            });
-        };
-        void sync.then(finish, finish).catch((error) => {
-            this.#rejectQueuedSyncWaiters(error);
         });
-        return sync;
-    }
-    #rejectQueuedSyncWaiters(error) {
-        const waiters = this.#queuedSyncWaiters.splice(0);
-        for (const waiter of waiters)
-            waiter.reject(error);
     }
-    #handleDiagnostic(event) {
-        if (event.source === 'sync' && event.details?.resyncRequired === true) {
-            void this.client
-                .forceSubscriptionsBootstrap()
-                .then(() => this.sync())
-                .catch(() => undefined);
+    /** Abort the in-flight socket round (socket closed or disconnected). */
+    #abortPendingRound(reason) {
+        const round = this.#pendingRound;
+        if (round === undefined)
             return;
+        this.#pendingRound = undefined;
+        round.reject(new ClientSyncError('sync.transport_failed', reason, true));
+    }
+    // -- realtime (§8 client side) ----------------------------------------------
+    async connectRealtime() {
+        this.#requireStarted();
+        const connector = this.#config.realtime;
+        if (connector === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
-        if (event.source !== 'realtime' ||
-            event.code !== 'realtime.state' ||
-            event.details?.state == null) {
+        this.#socket = await connector({
+            onText: (text) => this.#handleRealtimeText(text),
+            onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
+            onClose: () => {
+                this.#socket = undefined;
+                this.#presence.clear(); // §8.6.1: presence is per-connection
+                this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
+            },
+        });
+    }
+    disconnectRealtime() {
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.#presence.clear(); // §8.6.1: presence is per-connection
+        this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
+    }
+    /**
+     * §8.7 channel-tag routing (synchronous, so chunk order is preserved):
+     * `0x01` chunks feed the in-flight round's assembler; `0x00` messages
+     * are standalone deltas; unknown tags are ignored (forward compat).
+     */
+    #routeRealtimeBinary(bytes) {
+        if (bytes.length === 0)
+            return;
+        const tag = bytes[0];
+        const body = bytes.subarray(1);
+        if (tag === REALTIME_TAG_ROUND) {
+            const round = this.#pendingRound;
+            if (round === undefined)
+                return; // stale chunk after an abort
+            let done;
+            try {
+                done = round.scanner.push(body);
+            }
+            catch (error) {
+                this.#pendingRound = undefined;
+                round.reject(new ClientSyncError('sync.invalid_request', `malformed round response stream (§8.7): ${error instanceof Error ? error.message : String(error)}`));
+                return;
+            }
+            if (done === undefined)
+                return;
+            this.#pendingRound = undefined;
+            if (done.excess > 0) {
+                round.reject(new ClientSyncError('sync.invalid_request', 'response bytes past END of the round stream (§8.7)'));
+                return;
+            }
+            round.resolve(done.message.slice());
             return;
         }
-        const state = event.details.state;
-        if (state !== 'connected')
+        if (tag === REALTIME_TAG_DELTA) {
+            void this.#handleRealtimeBinary(body);
+        }
+        // Unknown tag: tolerated and ignored (§8.7 closed registry).
+    }
+    #handleRealtimeText(text) {
+        let parsed;
+        try {
+            parsed = parseRealtimeServerEvent(text);
+        }
+        catch {
+            return; // §8.1: tolerate garbled/unknown control messages
+        }
+        if (!parsed.known)
             return;
-        const wasReconnect = this.#hasConnectedRealtime;
-        this.#hasConnectedRealtime = true;
-        const shouldSync = this.options.syncOnRealtimeConnect !== false &&
-            (wasReconnect || this.options.initialSync === false);
-        if (!shouldSync)
+        const event = parsed.event;
+        if (event.event === 'hello') {
+            if (event.data.requiresSync) {
+                this.#needsPull = true;
+                this.#config.onSyncNeeded?.('hello');
+            }
             return;
-        void this.sync().catch(() => undefined);
+        }
+        if (event.event === 'sync') {
+            // §8.3: any wake-up means "run a pull soon", never data.
+            this.#needsPull = true;
+            this.#config.onSyncNeeded?.(event.data.reason);
+            return;
+        }
+        if (event.event === 'presence') {
+            this.#applyPresence(event.data);
+        }
     }
-    #subscribeNetworkEvents() {
-        const network = this.#network;
-        if (!network?.addEventListener || !network.removeEventListener)
+    /** §8.6 apply an inbound presence fanout to the local map. */
+    #applyPresence(data) {
+        // The publisher-directed error variant (§8.6.2) surfaces via the
+        // sync-needed reason channel is inappropriate; it is an out-of-band
+        // presence rejection — record nothing to the peer map, just ignore
+        // here (setPresence callers observe it through the callback if wired).
+        if (data.error !== undefined || data.kind === undefined)
             return;
-        const handleOnline = () => {
-            if (!this.#started)
+        const { scopeKey, kind, actorId, clientId } = data;
+        if (actorId === undefined || clientId === undefined)
+            return;
+        const peerKey = `${actorId} ${clientId}`;
+        let peers = this.#presence.get(scopeKey);
+        if (kind === 'leave') {
+            peers?.delete(peerKey);
+            if (peers !== undefined && peers.size === 0) {
+                this.#presence.delete(scopeKey);
+            }
+        }
+        else {
+            const doc = data.doc;
+            if (doc === null || doc === undefined)
                 return;
-            void this.#resumeOnline().catch(() => undefined);
-        };
-        network.addEventListener('online', handleOnline);
-        return () => {
-            network.removeEventListener?.('online', handleOnline);
-        };
+            if (peers === undefined) {
+                peers = new Map();
+                this.#presence.set(scopeKey, peers);
+            }
+            peers.set(peerKey, { actorId, clientId, doc });
+        }
+        this.#config.onPresence?.(scopeKey);
+        for (const listener of this.#presenceListeners) {
+            try {
+                listener(scopeKey);
+            }
+            catch {
+                // A UI listener must never break presence application.
+            }
+        }
+    }
+    async #handleRealtimeBinary(bytes) {
+        if (this.#syncing) {
+            // Fast path: a pull is mid-flight; let it win and recover the gap
+            // itself — re-pulling is idempotent, interleaved application is not
+            // worth it. (An optimization; the op chain below is the correctness
+            // mechanism — it also excludes a delta from racing a `setWindow` or a
+            // sync round that started between this check and the apply.)
+            this.#needsPull = true;
+            return;
+        }
+        // Serialize the apply on the operation chain: a delta must never
+        // interleave its transactions or share the `#batch` accumulator with a
+        // pull round or a `setWindow` at an await point (§8.2).
+        await this.#serialize(async () => {
+            try {
+                const message = decodeMessage(bytes);
+                if (message.msgKind !== 'response')
+                    return;
+                // §8.2: deltas apply like pull responses; ack after apply.
+                await this.#processResponse(message, [], undefined, 'delta');
+            }
+            catch {
+                // A delta that cannot be applied is recovered by a pull (§8.3).
+                this.#needsPull = true;
+                this.#config.onSyncNeeded?.('catchup-required');
+            }
+        });
+    }
+    #sendAck(cursor) {
+        this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
+    }
+    /** Ack the highest cursor that is contiguously applied for every sub. */
+    #ackAfterPull() {
+        if (this.#socket === undefined)
+            return;
+        const cursors = loadSubscriptions(this.#db)
+            .filter((sub) => sub.status === 'active' && sub.bootstrapState === undefined)
+            .map((sub) => sub.cursor)
+            .filter((cursor) => cursor >= 0);
+        if (cursors.length === 0)
+            return;
+        this.#sendAck(Math.min(...cursors));
+    }
+    // -- response processing ------------------------------------------------------
+    async #processResponse(message, sentCommits, sentSubs, mode) {
+        const summary = emptySummary(sentCommits.length);
+        const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
+        const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
+        const header = message.frames[0];
+        if (header?.type !== 'RESP_HEADER') {
+            throw new ClientSyncError('sync.invalid_request', 'missing RESP_HEADER');
+        }
+        if (header.requiredSchemaVersion !== undefined) {
+            // §1.6 schema floor: nothing else was processed — stop syncing and
+            // surface the upgrade requirement. A live-round floor always stops:
+            // the generated schema does not match what the server serves (behind,
+            // or ahead of a lagging server), and no local reset changes the
+            // version this client sends. The §7.4.2 trigger-2 convergence runs
+            // when the APP updates (recreating the client with a new generated
+            // schema), which fires the boot-time §7.4.1 marker check instead.
+            this.#schemaFloor = {
+                requiredSchemaVersion: header.requiredSchemaVersion,
+                ...(header.latestSchemaVersion !== undefined
+                    ? { latestSchemaVersion: header.latestSchemaVersion }
+                    : {}),
+            };
+            return {
+                ...summary,
+                bootstrapping: [],
+                schemaFloor: this.#schemaFloor,
+            };
+        }
+        let section;
+        let errorFrame;
+        let deltaCursor = -1;
+        // One apply batch per pull/delta round (I1): COMMIT + segment applies,
+        // the revocation purge, and the optimistic replay all coalesce into a
+        // single invalidation event emitted when this batch unwinds.
+        await this.#applyBatchAsync(async () => {
+            try {
+                for (const frame of message.frames.slice(1)) {
+                    switch (frame.type) {
+                        case 'RESP_HEADER':
+                            break;
+                        case 'LEASE':
+                            // §7.3.5: persist the opaque lease and clear any prior lease
+                            // error — a fresh lease means the outage/revocation is over.
+                            this.#setLeaseState({
+                                leaseId: frame.leaseId,
+                                expiresAtMs: frame.expiresAtMs,
+                            });
+                            break;
+                        case 'PUSH_RESULT':
+                            this.#handlePushResult(frame, commitsById, summary);
+                            break;
+                        case 'SUB_START': {
+                            const sub = subsById.get(frame.id);
+                            const fresh = sub !== undefined &&
+                                sub.cursor < 0 &&
+                                sub.bootstrapState === undefined &&
+                                frame.bootstrap;
+                            const skip = sub === undefined ||
+                                (mode === 'delta' &&
+                                    (sub.status !== 'active' ||
+                                        sub.bootstrapState !== undefined));
+                            section = { start: frame, sub, fresh, skip, cleared: false };
+                            break;
+                        }
+                        case 'COMMIT':
+                            if (section !== undefined && !section.skip) {
+                                await this.#applyCommit(frame, summary);
+                            }
+                            break;
+                        case 'SEGMENT_INLINE': {
+                            if (section === undefined ||
+                                section.skip ||
+                                section.sub === undefined) {
+                                break;
+                            }
+                            const segment = decodeRowsSegment(frame.payload);
+                            await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, { clearFirst, effective }, this.#encryption), section.fresh && !section.cleared);
+                            break;
+                        }
+                        case 'SEGMENT_REF': {
+                            if (section === undefined ||
+                                section.skip ||
+                                section.sub === undefined) {
+                                break;
+                            }
+                            // §4.2: a descriptor whose mediaType was not advertised is a
+                            // broken server — fail loud, never skip or guess.
+                            if (frame.mediaType === 'sqlite' &&
+                                (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
+                                throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
+                            }
+                            const bytes = await this.#downloadSegment(frame, section.sub);
+                            if (frame.mediaType === 'sqlite') {
+                                // §5.3: images are whole-table — a paged descriptor is
+                                // invalid, and the image is always its table's first page.
+                                if (frame.rowCursor !== undefined ||
+                                    frame.nextRowCursor !== undefined) {
+                                    throw new ClientSyncError('sync.invalid_request', 'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
+                                }
+                                await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
+                                    table: frame.table,
+                                    rowCount: frame.rowCount,
+                                    asOfCommitSeq: frame.asOfCommitSeq,
+                                    scopeDigest: frame.scopeDigest,
+                                }, { clearFirst, effective }), section.fresh && !section.cleared);
+                            }
+                            else {
+                                const segment = decodeRowsSegment(bytes);
+                                await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, { clearFirst, effective }, this.#encryption), section.fresh &&
+                                    !section.cleared &&
+                                    frame.rowCursor === undefined);
+                            }
+                            break;
+                        }
+                        case 'SUB_END': {
+                            if (section !== undefined &&
+                                !section.skip &&
+                                section.sub !== undefined) {
+                                const applied = this.#finishSection(section.sub, section.start, frame.nextCursor, frame.bootstrapState, summary);
+                                if (mode === 'delta' && applied) {
+                                    deltaCursor = Math.max(deltaCursor, frame.nextCursor);
+                                }
+                            }
+                            section = undefined;
+                            break;
+                        }
+                        case 'ERROR':
+                            // §1.4 rule 5 / §1.6: the request failed; the open
+                            // subscription's SUB_END values are never persisted.
+                            errorFrame = new ClientSyncError(frame.code, frame.message, frame.retryable);
+                            section = undefined;
+                            break;
+                        case 'UNKNOWN':
+                            break; // §1.2 rule 2: skipped, never interpreted
+                    }
+                    if (errorFrame !== undefined)
+                        break;
+                }
+            }
+            finally {
+                // §7.1: local reads see outbox state applied optimistically — replay
+                // the still-pending commits on top of the freshly applied server
+                // state (the simple reconciliation mandated for B3).
+                this.#replayOutbox();
+                // §5.9.7 B1: after every apply/replay, refcounts follow the live rows.
+                // A benign apply retains zero-ref bodies (LRU default); the revocation
+                // purge below deletes orphaned bodies with deleteOrphans (B2).
+                this.#reconcileBlobs(false);
+            }
+        });
+        if (errorFrame !== undefined)
+            throw errorFrame;
+        if (mode === 'delta') {
+            if (deltaCursor >= 0)
+                this.#sendAck(deltaCursor);
+        }
+        else {
+            this.#ackAfterPull();
+        }
+        const bootstrapping = loadSubscriptions(this.#db)
+            .filter((sub) => sub.status === 'active' && sub.bootstrapState !== undefined)
+            .map((sub) => sub.id);
+        // §7.4.5: the reset is over once the first post-reset pull round leaves
+        // no subscription mid-bootstrap — the tables are rebuilt and current.
+        if (this.#upgrading && mode === 'pull' && bootstrapping.length === 0) {
+            this.#setUpgrading(false);
+        }
+        return { ...summary, bootstrapping };
     }
-    async #resumeOnline() {
-        if (!this.#started || !this.#isOnline())
+    #handlePushResult(frame, commitsById, summary) {
+        const commit = commitsById.get(frame.clientCommitId);
+        if (commit === undefined)
+            return;
+        if (frame.status === 'applied' || frame.status === 'cached') {
+            // §6.3: applied and cached both drain the outbox — cached means
+            // "already applied, you may have missed the ack".
+            deleteOutboxCommit(this.#db, frame.clientCommitId);
+            summary.applied.push(frame.clientCommitId);
             return;
-        if (this.options.initialSync !== false) {
-            await this.#syncForLifecycle();
         }
-        if (this.options.realtime !== false && !this.#realtimeStarted) {
-            await this.#startRealtimeForLifecycle();
+        // rejected
+        const cacheMiss = frame.results.some((result) => result.status === 'error' &&
+            result.code === 'sync.idempotency_cache_miss' &&
+            result.retryable);
+        if (cacheMiss) {
+            // §6.3: a serving failure, not the commit's outcome — keep the
+            // commit queued and retry the identical push later.
+            summary.retryable.push(frame.clientCommitId);
+            return;
+        }
+        for (const result of frame.results) {
+            const operation = commit.operations[result.opIndex];
+            if (result.status === 'conflict') {
+                const conflict = {
+                    clientCommitId: frame.clientCommitId,
+                    opIndex: result.opIndex,
+                    table: operation?.table ?? '',
+                    rowId: operation?.rowId ?? '',
+                    code: result.code,
+                    message: result.message,
+                    serverVersion: result.serverVersion,
+                    serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
+                    ...(operation !== undefined ? { operation } : {}),
+                };
+                this.#conflicts.push(conflict);
+                summary.conflicts.push(conflict);
+                this.#config.onConflict?.(conflict);
+            }
+            else if (result.status === 'error') {
+                this.#rejections.push({
+                    clientCommitId: frame.clientCommitId,
+                    opIndex: result.opIndex,
+                    code: result.code,
+                    message: result.message,
+                    retryable: result.retryable,
+                    ...(operation !== undefined ? { operation } : {}),
+                });
+            }
+        }
+        // §7.2: stop optimistic display and decide about dependents — the
+        // commit leaves the outbox; rows it created that the server never
+        // confirmed are undone here, rows it overwrote reconcile via the pull
+        // half (the conflict record carries the server row for the app).
+        this.#db.transaction(() => {
+            deleteOutboxCommit(this.#db, frame.clientCommitId);
+            for (const operation of commit.operations) {
+                if (operation.op !== 'upsert')
+                    continue;
+                const table = this.#schema.tables.get(operation.table);
+                if (table === undefined)
+                    continue;
+                const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [operation.rowId])[0];
+                if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
+                    deleteLocalRow(this.#db, table, operation.rowId);
+                }
+            }
+        });
+        summary.rejected.push(frame.clientCommitId);
+    }
+    #decodeServerRow(tableName, payload) {
+        if (tableName === undefined)
+            return {};
+        const table = this.#schema.tables.get(tableName);
+        if (table === undefined)
+            return {};
+        const values = decodeRow(table.columns, payload);
+        const record = {};
+        table.columns.forEach((column, index) => {
+            record[column.name] = values[index] ?? null;
+        });
+        return record;
+    }
+    async #applyCommit(frame, summary) {
+        await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption);
+        summary.commitsApplied += 1;
+        // I1/I2: record touched tables and precise `prefix:value` scope keys —
+        // COMMIT changes carry per-row stored scopes (§4.5), the finest honest
+        // invalidation the wire provides.
+        const batch = this.#batch;
+        if (batch === undefined)
+            return;
+        for (const change of frame.changes) {
+            const tableName = frame.tables[change.tableIndex];
+            if (tableName === undefined)
+                continue;
+            const table = this.#schema.tables.get(tableName);
+            if (table === undefined)
+                continue;
+            batch.table(tableName);
+            batch.changeScopes(table, change.scopes);
         }
     }
-    async #syncForLifecycle() {
+    /**
+     * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
+     * (no local scope-column mapping) marks the subscription `failed` and
+     * stops syncing the table without failing the whole request.
+     */
+    async #applySegmentOrFail(section, summary, apply, clearFirst) {
+        const sub = section.sub;
+        if (sub === undefined)
+            return;
+        const table = this.#table(sub.table);
         try {
-            await this.sync();
+            summary.segmentRowsApplied += await apply(table, clearFirst, section.start.effectiveScopes);
+            section.cleared = true;
+            // I1/I2: segments carry only a table + scopeDigest, never per-row
+            // scope keys — invalidate the table plus the subscription's effective
+            // scope keys (the coarsest honest key for bulk data).
+            this.#batch?.table(table.name);
+            this.#batch?.scopeMap(table, section.start.effectiveScopes);
         }
         catch (error) {
-            if (!isSyncularOfflineError(error))
-                throw error;
+            if (error instanceof ClientSyncError &&
+                error.code === 'sync.scope_revoked') {
+                saveSubscription(this.#db, {
+                    id: sub.id,
+                    table: sub.table,
+                    scopes: sub.scopes,
+                    ...(sub.params !== undefined ? { params: sub.params } : {}),
+                    cursor: sub.cursor,
+                    ...(sub.effectiveScopes !== undefined
+                        ? { effectiveScopes: sub.effectiveScopes }
+                        : {}),
+                    status: 'failed',
+                    reasonCode: 'sync.scope_revoked',
+                });
+                summary.failed.push(sub.id);
+                section.skip = true;
+                return;
+            }
+            throw error;
         }
     }
-    async #startRealtimeForLifecycle() {
-        try {
-            await this.client.startRealtime(this.options.realtime);
-            this.#realtimeStarted = true;
+    async #downloadSegment(frame, sub) {
+        const downloader = this.#config.segments;
+        if (downloader === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'received SEGMENT_REF but no segment downloader is configured');
         }
-        catch (error) {
-            this.#realtimeStarted = false;
-            if (!isSyncularOfflineError(error))
-                throw error;
+        let bytes;
+        if (frame.url !== undefined) {
+            // §5.4: a url-carrying descriptor MUST be fetched from that URL —
+            // no fall-through to the direct endpoint; any failure invalidates
+            // the descriptor and re-pulling recovers (§1.4 rule 5 keeps the
+            // cursor/resume token unpersisted).
+            const fetchUrl = downloader.fetchUrl;
+            if (fetchUrl === undefined ||
+                (this.#acceptMask() & ACCEPT_SIGNED_URLS) === 0) {
+                throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF carries a url but accept bit 3 was not advertised (§5.4)');
+            }
+            if (frame.urlExpiresAtMs !== undefined &&
+                frame.urlExpiresAtMs <= this.#now()) {
+                // §5.4: MUST NOT start a fetch at/past expiry.
+                throw new ClientSyncError('sync.segment_expired', `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`, true);
+            }
+            bytes = await fetchUrl(frame.url);
+        }
+        else {
+            bytes = await downloader({
+                segmentId: frame.segmentId,
+                table: frame.table,
+                requestedScopesJson: canonicalScopeJson(sub.scopes),
+            });
+        }
+        // §5.1: verify the content address before applying; on mismatch the
+        // segment is discarded and the cursor/resume token stay unpersisted,
+        // so the next pull re-delivers.
+        const hash = await sha256Hex(bytes);
+        if (`sha256:${hash}` !== frame.segmentId) {
+            throw new ClientSyncError('sync.invalid_request', `segment ${frame.segmentId} failed content-address verification (§5.1)`, true);
         }
+        return bytes;
     }
-    #isOnline() {
-        return this.#network?.isOnline() !== false;
+    /** Returns whether SUB_END state was persisted (section applied). */
+    #finishSection(sub, start, nextCursor, bootstrapState, summary) {
+        if (start.status === 'active') {
+            // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
+            // §3.3: the effective-scope echo is persisted for the purge contract.
+            // An absent bootstrapState clears any previous resume token (§4.4:
+            // absent = bootstrap complete, or not bootstrapping).
+            saveSubscription(this.#db, {
+                id: sub.id,
+                table: sub.table,
+                scopes: sub.scopes,
+                ...(sub.params !== undefined ? { params: sub.params } : {}),
+                cursor: nextCursor,
+                ...(bootstrapState !== undefined ? { bootstrapState } : {}),
+                effectiveScopes: start.effectiveScopes,
+                status: 'active',
+            });
+            return true;
+        }
+        if (start.status === 'reset') {
+            // §4.6: discard cursor + resume token, keep local rows, re-bootstrap
+            // with cursor = -1 on the next pull. Staleness, not a purge.
+            saveSubscription(this.#db, {
+                id: sub.id,
+                table: sub.table,
+                scopes: sub.scopes,
+                ...(sub.params !== undefined ? { params: sub.params } : {}),
+                cursor: -1,
+                ...(sub.effectiveScopes !== undefined
+                    ? { effectiveScopes: sub.effectiveScopes }
+                    : {}),
+                status: 'active',
+                reasonCode: start.reasonCode,
+            });
+            summary.resets.push(sub.id);
+            return false;
+        }
+        // revoked (§3.3): purge rows matching the LAST-echoed effective scopes
+        // (never the requested map), drop doomed outbox commits, stop pulling.
+        const table = this.#table(sub.table);
+        const lastEffective = sub.effectiveScopes;
+        let failed = false;
+        if (lastEffective !== undefined && Object.keys(lastEffective).length > 0) {
+            try {
+                this.#db.transaction(() => {
+                    deleteScopedRows(this.#db, table, lastEffective);
+                });
+                // I1: the §3.3 purge is a bulk delete — invalidate the table + the
+                // purged effective scope keys so live queries over them re-run.
+                this.#batch?.table(table.name);
+                this.#batch?.scopeMap(table, lastEffective);
+                dropOutboxCommitsInScope(this.#db, table, lastEffective);
+                // §5.9.7 B2: revocation deletes now-unauthorized blob bodies —
+                // reconcile with deleteOrphans (evicted ≠ revoked).
+                this.#reconcileBlobs(true);
+            }
+            catch (error) {
+                if (error instanceof ClientSyncError &&
+                    error.code === 'sync.scope_revoked') {
+                    // Fail closed: no local mapping — surface a fatal configuration
+                    // error and stop syncing the table without clearing anything.
+                    failed = true;
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        saveSubscription(this.#db, {
+            id: sub.id,
+            table: sub.table,
+            scopes: sub.scopes,
+            ...(sub.params !== undefined ? { params: sub.params } : {}),
+            cursor: nextCursor,
+            ...(lastEffective !== undefined
+                ? { effectiveScopes: lastEffective }
+                : {}),
+            status: failed ? 'failed' : 'revoked',
+            reasonCode: start.reasonCode,
+        });
+        summary.revoked.push(sub.id);
+        if (failed)
+            summary.failed.push(sub.id);
+        return false;
     }
-    #startPolling() {
-        const interval = this.options.pollIntervalMs;
-        if (interval === false || interval === undefined || interval <= 0)
+    // -- optimistic state ----------------------------------------------------------
+    #applyOperationsLocally(operations, batch) {
+        for (const op of operations) {
+            const table = this.#table(op.table);
+            batch?.table(op.table);
+            if (op.op === 'delete') {
+                deleteLocalRow(this.#db, table, op.rowId);
+                continue;
+            }
+            const values = table.columns.map((column) => {
+                const value = op.values?.[column.name];
+                return value === undefined ? null : jsonToRowValue(value);
+            });
+            // Record the row's scope keys from its scope columns (I2 refinement).
+            if (batch !== undefined) {
+                for (const [variable, column] of table.scopeColumnByVariable) {
+                    const idx = table.columnIndex.get(column);
+                    const cell = idx === undefined ? undefined : values[idx];
+                    const prefix = table.scopePrefixByVariable.get(variable);
+                    if (prefix !== undefined && cell != null) {
+                        batch.scopeKey(`${prefix}:${String(cell)}`);
+                    }
+                }
+            }
+            const existing = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [op.rowId])[0];
+            const version = existing === undefined ? OPTIMISTIC_VERSION : existing.v;
+            upsertLocalRow(this.#db, table, values, version);
+        }
+    }
+    /** Re-apply every pending outbox commit on top of server state (§7.1). */
+    #replayOutbox() {
+        const pending = listOutbox(this.#db);
+        if (pending.length === 0)
             return;
-        this.#pollTimer = setInterval(() => {
-            if (!this.#isOnline())
-                return;
-            void this.#syncForLifecycle();
-        }, interval);
+        this.#applyBatch((batch) => {
+            this.#db.transaction(() => {
+                for (const commit of pending) {
+                    this.#applyOperationsLocally(commit.operations, batch);
+                }
+            });
+        });
     }
-    #stopPolling() {
-        if (!this.#pollTimer)
+    /**
+     * §5.9.7 B1/B2: recompute blob-cache refcounts from live `blob_ref`
+     * columns. No-op unless the schema has blob columns. `deleteOrphans`
+     * triggers the revocation-side body deletion (B2).
+     */
+    #reconcileBlobs(deleteOrphans) {
+        if (!this.#hasBlobs)
             return;
-        clearInterval(this.#pollTimer);
-        this.#pollTimer = undefined;
+        reconcileBlobRefcounts(this.#db, this.#schema, { deleteOrphans });
+    }
+    // -- helpers -----------------------------------------------------------------
+    #table(name) {
+        const table = this.#schema.tables.get(name);
+        if (table === undefined) {
+            throw new ClientSyncError('sync.unknown_table', `unknown local table ${JSON.stringify(name)}`);
+        }
+        return table;
+    }
+    #requireStarted() {
+        if (!this.#started) {
+            throw new ClientSyncError('sync.invalid_request', 'SyncClient.start() has not completed');
+        }
     }
 }
-//# sourceMappingURL=client.js.map