@syncular/client 0.20.0 → 0.20.1

package/README.md

@@ -676,7 +676,8 @@ through the core, without intermediate download updates.
 
 Import reports every 1,024 rows and its final count. `rowsProcessed` includes work
 inside the current transaction; a failed import can roll those rows back. SQLite
-images retain one atomic transaction. `complete` follows checkpoint persistence
+images commit in chunks of at most 1,024 rows and yield after each commit.
+Earlier committed chunks survive a later interruption. `complete` follows checkpoint persistence
 and optimistic-state reconciliation for the round. More bootstrap pages can
 remain; use subscription coverage to determine whether a query is complete.
 Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
@@ -723,3 +724,19 @@ request. Status and diagnostics use `COUNT(*)` without parsing pending bodies.
 Optimistic replay still reads the remaining outbox after each response. The
 100/1,000/10,000-commit workload and measured limits are recorded in
 [the reliability RFC](../../docs/RFC-RELIABILITY-DX.md#9-implementation-evidence-2026-09-05).
+
+## Reads during bootstrap and eviction
+
+Reactive queries read cached snapshots while window registration runs. Coverage
+continues to distinguish complete, pending, and missing windows; registration
+errors remain observable. Retained owners reuse acknowledged units immediately.
+
+Both segment formats yield between committed import chunks automatically.
+Window eviction deletes at most 1,024 unpinned rows per chunk and resumes from a
+durable pending record after interruption. Security purges remain atomic.
+See [windowing](https://syncular.dev/concepts-windowing/) and
+[bootstrap](https://syncular.dev/concepts-bootstrap/) for coverage and recovery.
+
+Custom database adapters implementing `withSqliteImage` must return a promise and
+await their callback before detaching the image. The callback can await between
+committed import chunks; no write transaction spans that await.

package/dist/apply.d.ts

@@ -43,12 +43,15 @@ export declare function deleteScopedRows(db: ClientDatabase, table: CompiledClie
  * scopes (same local-scope-column rule and fail-closed clause as
  * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
- * `true` iff any pinned row was left behind, so the caller knows to defer
- * the rest of the eviction until the outbox drains. Also removes the
+ * whether unpinned work remains and whether any scoped rows remain. Each
+ * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
  * evicted rows' `server_version` with them (E2 — no residual version
  * cache), which is automatic since the version column is per-row.
  */
-export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): boolean;
+export declare function evictScopedRows(db: ClientDatabase, table: CompiledClientTable, effective: ScopeMap, pinnedRowIds: ReadonlySet<string>): {
+    remaining: boolean;
+    deferred: boolean;
+};
 /** Descriptor fields a sqlite image is validated against (§5.3). */
 export interface SqliteSegmentDescriptor {
     readonly table: string;
@@ -57,11 +60,11 @@ export interface SqliteSegmentDescriptor {
     readonly scopeDigest: string;
 }
 /**
- * Apply a §5.3 sqlite-image segment in ONE local transaction: validate
+ * Apply a §5.3 sqlite image in committed chunks of at most 1,024 rows: validate
  * the in-file metadata against the descriptor, validate the data table's
  * column names/order against the generated schema, run the §5.6
- * first-page clear when fresh, then copy every row with a single
- * one primary-key upsert — `_syncular_version` lands in
+ * first-page clear when fresh, then bulk-copy each chunk through a
+ * primary-key upsert — `_syncular_version` lands in
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
  */
 export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledClientSchema, table: CompiledClientTable, bytes: Uint8Array, descriptor: SqliteSegmentDescriptor, options: {
@@ -69,7 +72,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
     readonly effective: ScopeMap;
     readonly transaction?: ApplyTransaction;
     readonly onProgress?: (rowsProcessed: number) => void;
-}): number;
+    readonly isCurrent?: () => boolean;
+}): Promise<number>;
 /**
  * Apply a decoded rows segment: each block in one local transaction
  * (§5.2/§1.4); `clearFirst` implements the §5.6 fresh-bootstrap first-page
@@ -83,4 +87,7 @@ export declare function applyRowsSegment(db: ClientDatabase, schema: CompiledCli
     readonly effective: ScopeMap;
     readonly transaction?: ApplyTransaction;
     readonly onProgress?: (rowsProcessed: number) => void;
+    readonly isCurrent?: () => boolean;
 }, encryption?: EncryptionConfig): Promise<number>;
+/** Let worker messages run only after the current SQLite transaction commits. */
+export declare function yieldToHost(): Promise<void>;

package/dist/apply.js

@@ -138,15 +138,15 @@ export function deleteScopedRows(db, table, effective) {
  * scopes (same local-scope-column rule and fail-closed clause as
  * {@link deleteScopedRows}) EXCEPT rows whose primary key is in
  * `pinnedRowIds` (E1 — pinned by a still-pending outbox commit). Returns
- * `true` iff any pinned row was left behind, so the caller knows to defer
- * the rest of the eviction until the outbox drains. Also removes the
+ * whether unpinned work remains and whether any scoped rows remain. Each
+ * call removes at most 1,024 rows; the caller commits before yielding. Also removes the
  * evicted rows' `server_version` with them (E2 — no residual version
  * cache), which is automatic since the version column is per-row.
  */
 export function evictScopedRows(db, table, effective, pinnedRowIds) {
     const entries = Object.entries(effective);
     if (entries.length === 0)
-        return false;
+        return { remaining: false, deferred: false };
     const clauses = [];
     const params = [];
     for (const [variable, values] of entries) {
@@ -155,7 +155,7 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
             throw new ClientSyncError('sync.scope_revoked', `table ${JSON.stringify(table.name)} has no local scope-column mapping for ${JSON.stringify(variable)} (§4.8/§3.3 fail-closed)`);
         }
         if (values.length === 0)
-            return false;
+            return { remaining: false, deferred: false };
         clauses.push(`${quoteIdent(column)} IN (${values.map(() => '?').join(', ')})`);
         params.push(...values);
     }
@@ -166,31 +166,28 @@ export function evictScopedRows(db, table, effective, pinnedRowIds) {
         pinnedClause = ` AND ${pk} NOT IN (${ids.map(() => '?').join(', ')})`;
         params.push(...ids);
     }
-    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}${pinnedClause}`, params);
-    if (pinnedRowIds.size === 0)
-        return false;
-    // A pin still matters only if a pinned row actually falls inside this
-    // unit's effective scopes; check by re-selecting the survivors.
-    const survivors = db.query(`SELECT ${pk} AS pk FROM ${quoteIdent(table.name)} WHERE ${clauses.join(' AND ')}`, params.slice(0, params.length - pinnedRowIds.size));
-    for (const row of survivors) {
-        if (pinnedRowIds.has(String(row.pk)))
-            return true;
-    }
-    return false;
+    const target = quoteIdent(table.name);
+    db.exec(`DELETE FROM ${target} WHERE ${pk} IN (
+      SELECT ${pk} FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1024
+    )`, params);
+    const remaining = db.query(`SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')}${pinnedClause} LIMIT 1`, params).length > 0;
+    const deferred = remaining ||
+        db.query(`SELECT 1 FROM ${target} WHERE ${clauses.join(' AND ')} LIMIT 1`, params.slice(0, params.length - pinnedRowIds.size)).length > 0;
+    return { remaining, deferred };
 }
 const IMAGE_ALIAS = 'syncular_image';
 function imageInvalid(detail) {
     throw new ClientSyncError('sync.invalid_request', `sqlite segment rejected: ${detail} (§5.3)`);
 }
 /**
- * Apply a §5.3 sqlite-image segment in ONE local transaction: validate
+ * Apply a §5.3 sqlite image in committed chunks of at most 1,024 rows: validate
  * the in-file metadata against the descriptor, validate the data table's
  * column names/order against the generated schema, run the §5.6
- * first-page clear when fresh, then copy every row with a single
- * one primary-key upsert — `_syncular_version` lands in
+ * first-page clear when fresh, then bulk-copy each chunk through a
+ * primary-key upsert — `_syncular_version` lands in
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
  */
-export function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
+export async function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
     const withImage = db.withSqliteImage?.bind(db);
     if (withImage === undefined) {
         throw new ClientSyncError('sync.invalid_request', 'received a sqlite segment but the database backend cannot import images (§4.2: do not advertise accept bit 2)');
@@ -198,7 +195,7 @@ export function applySqliteSegment(db, schema, table, bytes, descriptor, options
     if (descriptor.table !== table.name) {
         imageInvalid(`descriptor table ${JSON.stringify(descriptor.table)}`);
     }
-    return withImage(bytes, IMAGE_ALIAS, () => {
+    return withImage(bytes, IMAGE_ALIAS, async () => {
         // 1. Metadata vs descriptor (§5.3 rule 2). A file that is not a
         //    SQLite database or lacks the metadata table fails right here.
         let meta;
@@ -244,51 +241,58 @@ export function applySqliteSegment(db, schema, table, bytes, descriptor, options
             expected.some((name, index) => actual[index] !== name)) {
             throw new ClientSyncError('sync.schema_mismatch', `sqlite segment for ${JSON.stringify(table.name)} does not match the generated schema: columns [${actual.join(', ')}] (§5.3)`);
         }
-        // 3. One transaction: fresh-bootstrap clear, then primary-key upsert.
+        const primaryKeys = info.filter((column) => Number(column.pk) > 0);
+        if (primaryKeys.length !== 1 || primaryKeys[0]?.name !== table.primaryKey)
+            imageInvalid('image primary key does not match generated schema');
+        const source = `${IMAGE_ALIAS}.${quoteIdent(table.name)}`;
+        const count = Number(db.query(`SELECT count(*) AS n FROM ${source}`)[0]?.n);
+        if (count !== descriptor.rowCount)
+            imageInvalid('image row count does not match descriptor');
         const names = table.columns.map((column) => quoteIdent(column.name));
         const insertNames = [...names, quoteIdent(SYNC_VERSION_COLUMN)];
+        const primaryKey = quoteIdent(table.primaryKey);
         const updates = insertNames
-            .filter((name) => name !== quoteIdent(table.primaryKey))
+            .filter((name) => name !== primaryKey)
             .map((name) => `${name}=excluded.${name}`)
             .join(', ');
-        return (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-            if (options.clearFirst) {
-                deleteScopedRows(db, table, options.effective);
+        let after;
+        let applied = 0;
+        for (;;) {
+            if (options.isCurrent?.() === false)
+                return applied;
+            const boundary = db.query(`SELECT ${primaryKey} AS boundary FROM ${source}
+         ${after === undefined ? '' : `WHERE ${primaryKey} > ?`}
+         ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, after === undefined ? [] : [after])[0]?.boundary;
+            if (boundary === null)
+                imageInvalid('image primary key must not be null');
+            const predicates = [];
+            const params = [];
+            if (after !== undefined) {
+                predicates.push(`${primaryKey} > ?`);
+                params.push(after);
+            }
+            if (boundary !== undefined) {
+                predicates.push(`${primaryKey} <= ?`);
+                params.push(boundary);
             }
-            const source = `${IMAGE_ALIAS}.${quoteIdent(table.name)}`;
-            const primaryKey = quoteIdent(table.primaryKey);
-            let after;
-            let applied = 0;
-            for (;;) {
-                const boundary = db.query(`SELECT ${primaryKey} AS boundary FROM ${source}
-           ${after === undefined ? '' : `WHERE ${primaryKey} > ?`}
-           ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, after === undefined ? [] : [after])[0]?.boundary;
-                const predicates = [];
-                const params = [];
-                if (after !== undefined) {
-                    predicates.push(`${primaryKey} > ?`);
-                    params.push(after);
-                }
-                if (boundary !== undefined) {
-                    predicates.push(`${primaryKey} <= ?`);
-                    params.push(boundary);
-                }
+            (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
+                if (after === undefined && options.clearFirst)
+                    deleteScopedRows(db, table, options.effective);
                 db.exec(`INSERT INTO ${quoteIdent(table.name)} (${insertNames.join(', ')})
            SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')}
            FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}
            ON CONFLICT (${primaryKey}) DO UPDATE SET ${updates}`, params);
                 applied += Number(db.query('SELECT changes() AS n')[0]?.n ?? 0);
-                if (boundary === undefined)
-                    break;
-                options.onProgress?.(applied);
-                after = boundary;
-            }
-            if (applied !== descriptor.rowCount) {
-                imageInvalid(`image holds ${applied} rows, descriptor says ${descriptor.rowCount}`);
-            }
+            });
             options.onProgress?.(applied);
-            return applied;
-        });
+            await yieldToHost();
+            if (boundary === undefined || applied === count)
+                break;
+            after = boundary;
+        }
+        if (applied !== count)
+            imageInvalid('image applied row count does not match descriptor');
+        return applied;
     });
 }
 /**
@@ -305,6 +309,8 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
     let first = true;
     const blocks = segment.blocks.length > 0 ? segment.blocks : [[]];
     for (const block of blocks) {
+        if (options.isCurrent?.() === false)
+            break;
         // §5.11: decrypt this block's rows before opening the sync transaction
         // (WebCrypto is async; the SQLite transaction is not). Decrypt failure
         // aborts before any write in this block.
@@ -318,6 +324,8 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
                 : row.values;
             rows.push({ values, serverVersion: row.serverVersion });
         }
+        if (options.isCurrent?.() === false)
+            break;
         const clearThisBlock = first && options.clearFirst;
         first = false;
         if (!clearThisBlock && rows.length === 0)
@@ -333,7 +341,21 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
                     options.onProgress?.(applied);
             }
         });
+        options.onProgress?.(applied);
+        await yieldToHost();
     }
     options.onProgress?.(applied);
     return applied;
 }
+/** Let worker messages run only after the current SQLite transaction commits. */
+export function yieldToHost() {
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            channel.port1.close();
+            channel.port2.close();
+            resolve();
+        };
+        channel.port2.postMessage(null);
+    });
+}

package/dist/bun-database.d.ts

@@ -21,7 +21,7 @@ export declare class BunClientDatabase implements ClientDatabase {
      * §5.3 image import: bun:sqlite attaches files, not buffers, so the
      * image lands in a private temp file for the duration of the ATTACH.
      */
-    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 export declare function openBunDatabase(path?: string): ClientDatabase;

package/dist/bun-database.js

@@ -50,7 +50,7 @@ export class BunClientDatabase {
      * §5.3 image import: bun:sqlite attaches files, not buffers, so the
      * image lands in a private temp file for the duration of the ATTACH.
      */
-    withSqliteImage(bytes, alias, fn) {
+    async withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
         const path = join(dir, 'segment.db');
@@ -58,7 +58,7 @@ export class BunClientDatabase {
             writeFileSync(path, bytes);
             this.db.run(`ATTACH DATABASE ? AS ${alias}`, [path]);
             try {
-                return fn();
+                return await fn();
             }
             finally {
                 this.db.run(`DETACH DATABASE ${alias}`);

package/dist/client.d.ts

@@ -91,8 +91,8 @@ export interface SyncClientLimits {
     readonly maxSnapshotPages?: number;
     /**
      * §4.2 accept bitmask; defaults to inline + external rows (0b0011)
-     * plus sqlite images (bit 2) when the database backend implements
-     * `withSqliteImage` and a segment downloader is configured (§5.3).
+     * plus SQLite images and signed URLs when supported. Both image chunks
+     * and rows blocks commit before yielding to local reads (§7.7).
      */
     readonly accept?: number;
     /**
@@ -383,8 +383,8 @@ export declare class SyncClient {
      * 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
+     * sync); removed units are unsubscribed with their first eviction chunk
+     * 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.
      *

package/dist/client.js

@@ -9,7 +9,7 @@ import { ProgressEmitter, } from './progress.js';
  * `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 { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
@@ -236,6 +236,7 @@ export class SyncClient {
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
             (countOutbox(this.#db) > 0 ||
+                loadPendingEvictions(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
@@ -1126,22 +1127,17 @@ export class SyncClient {
         }
         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).
-     */
+    /** Advertise supported segment formats; all imports yield between commits. */
     #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) |
+            (typeof this.#db.withSqliteImage === 'function' && segments !== undefined
+                ? ACCEPT_SQLITE
+                : 0) |
             (urlCapable ? ACCEPT_SIGNED_URLS : 0));
     }
     subscriptions() {
@@ -1199,8 +1195,8 @@ export class SyncClient {
      * 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
+     * sync); removed units are unsubscribed with their first eviction chunk
+     * 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.
      *
@@ -1258,7 +1254,7 @@ export class SyncClient {
             for (const { unit, subId } of live) {
                 if (wanted.has(unit))
                     continue;
-                this.#evictUnit(baseKey, base, unit, subId);
+                await this.#evictUnit(baseKey, base, unit, subId);
                 changed = true;
             }
         });
@@ -1297,8 +1293,8 @@ export class SyncClient {
         return { units: live.map((u) => u.unit), pending };
     }
     /**
-     * §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
+     * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
+     * its first chunk with unsubscription. 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
@@ -1306,19 +1302,21 @@ export class SyncClient {
      * with no local scope-column mapping, surfaces a configuration error and
      * evicts nothing (§4.8/§3.3).
      */
-    #evictUnit(baseKey, base, unit, subId) {
+    async #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);
+        let remaining = false;
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
-                const deferred = evictScopedRows(this.#db, table, effective, pinned);
+                const result = evictScopedRows(this.#db, table, effective, pinned);
+                remaining = result.remaining;
                 deleteWindowUnit(this.#db, baseKey, unit);
                 deleteSubscription(this.#db, subId);
-                if (deferred) {
+                if (result.deferred) {
                     savePendingEviction(this.#db, subId, base.table, effective);
                 }
                 else {
@@ -1330,13 +1328,17 @@ export class SyncClient {
             this.#needsPull = true;
             batch.status();
         });
+        if (remaining) {
+            await yieldToHost();
+            await this.#drainPendingEvictions();
+        }
     }
     /**
      * §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() {
+    async #drainPendingEvictions() {
         const pending = loadPendingEvictions(this.#db);
         if (pending.length === 0)
             return;
@@ -1346,16 +1348,23 @@ export class SyncClient {
                 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)
+            let remaining;
+            do {
+                if (!loadPendingEvictions(this.#db).some((item) => item.subId === entry.subId))
+                    break;
+                // Local writes may add pins while the worker yields between chunks.
+                const pinned = this.#pinnedRowIds(entry.table);
+                remaining = false;
+                this.#applyBatch((batch) => {
+                    const result = evictScopedRows(this.#db, table, entry.effective, pinned);
+                    remaining = result.remaining;
+                    if (!result.deferred)
                         deletePendingEviction(this.#db, entry.subId);
+                    batch.scopeMap(table, entry.effective);
                 });
-                batch.scopeMap(table, entry.effective);
-            });
+                if (remaining)
+                    await yieldToHost();
+            } while (remaining);
         }
     }
     /**
@@ -1920,6 +1929,7 @@ export class SyncClient {
         // survive it — the reference server keeps no replay buffer (§8.2).
         this.#setSyncNeeded(false);
         try {
+            await this.#drainPendingEvictions();
             const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
             // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
             // them, so the server-side existence check (§6.6) passes.
@@ -1981,7 +1991,7 @@ export class SyncClient {
             const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
             // §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();
+            await this.#drainPendingEvictions();
             this.#progress.update(summary.failed.length > 0
                 ? { state: 'failed', errorCode: 'sync.scope_revoked' }
                 : { state: 'complete' });
@@ -2028,10 +2038,21 @@ export class SyncClient {
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
      */
-    async syncUntilIdle(maxRounds = 20) {
+    async syncUntilIdle(maxRounds) {
+        const budget = maxRounds ?? 20;
         let last;
-        for (let round = 0; round < maxRounds; round++) {
+        for (let round = 0; round < budget; round++) {
+            const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]));
             last = await this.sync();
+            if (maxRounds === undefined &&
+                last.segmentRowsApplied > 0 &&
+                last.bootstrapping.length > 0 &&
+                before !==
+                    JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
+                        sub.id,
+                        sub.bootstrapState,
+                    ])))
+                round = -1;
             if (last.schemaFloor !== undefined)
                 return last;
             if (last.commitsApplied === 0 &&
@@ -2043,7 +2064,7 @@ export class SyncClient {
                 return last;
             }
         }
-        throw new ClientSyncError('sync.invalid_request', `sync did not reach idle within ${maxRounds} rounds`);
+        throw new ClientSyncError('sync.invalid_request', 'sync did not reach idle within the round budget');
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it
@@ -2469,6 +2490,7 @@ export class SyncClient {
                         });
                         await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                             clearFirst,
+                            isCurrent: () => this.#localResetEpoch === resetEpoch,
                             onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                             effective,
                             transaction: (fn) => this.#applyBatch((batch) => {
@@ -2477,7 +2499,9 @@ export class SyncClient {
                                         this.#scopedRowsExist(table, effective))) {
                                     batch.table(table.name);
                                 }
-                                return fn();
+                                const result = fn();
+                                this.#replayOutbox();
+                                return result;
                             }),
                         }, this.#encryption), section.fresh && !section.cleared);
                         break;
@@ -2510,6 +2534,7 @@ export class SyncClient {
                                 scopeDigest: frame.scopeDigest,
                             }, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
                                 onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
@@ -2518,7 +2543,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }), section.fresh && !section.cleared);
                         }
@@ -2526,6 +2553,7 @@ export class SyncClient {
                             const segment = decodeRowsSegment(bytes);
                             await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
                                 onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
@@ -2534,7 +2562,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }, this.#encryption), section.fresh &&
                                 !section.cleared &&

package/dist/database.d.ts

@@ -20,11 +20,12 @@ export interface ClientDatabase {
     /**
      * Optional sqlite-image capability (SPEC §5.3): expose `bytes` as an
      * attached read-only database schema named `alias` for the duration of
-     * `fn`, then detach. Presence of this method is what makes the client
+     * `fn`, awaiting its result before detaching. No transaction spans its awaits.
+     * Presence of this method is what makes the client
      * advertise `accept` bit 2 (§4.2). MUST be called outside any open
      * transaction (SQLite cannot ATTACH inside one); `fn` may open its own.
      */
-    withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */

package/dist/node-database.d.ts

@@ -12,7 +12,7 @@ export declare class NodeClientDatabase implements ClientDatabase {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     transaction<T>(fn: () => T): T;
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 export declare function openNodeDatabase(path?: string): ClientDatabase;

package/dist/node-database.js

@@ -52,7 +52,7 @@ export class NodeClientDatabase {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage(bytes, alias, fn) {
+    async withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
         const path = join(dir, 'segment.db');
@@ -60,7 +60,7 @@ export class NodeClientDatabase {
             writeFileSync(path, bytes);
             this.db.prepare(`ATTACH DATABASE ? AS ${alias}`).run(path);
             try {
-                return fn();
+                return await fn();
             }
             finally {
                 this.db.prepare(`DETACH DATABASE ${alias}`).run();