@syncular/client 0.32.0 → 0.33.0

package/dist/apply.js

@@ -9,7 +9,7 @@ import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
  */
 import { decodeRow, } from '@syncular/core';
 import { ClientSyncError, invalidRequest } from './errors.js';
-import { quoteIdent, matchesLocalScopes, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
+import { quoteIdent, matchesLocalScopes, pkSqlValue, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
 function upsertSql(table) {
     const names = [
         ...table.columns.map((column) => quoteIdent(column.name)),
@@ -33,7 +33,7 @@ export function upsertLocalRow(db, table, values, syncVersion, serverWrite = tru
 export function deleteLocalRow(db, table, rowId, serverWrite = true) {
     if (serverWrite)
         retainedBaseWrite(db, table, rowId);
-    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [rowId]);
+    db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)]);
 }
 /**
  * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4).

package/dist/client.d.ts

@@ -639,6 +639,14 @@ export declare class SyncClient {
     /**
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     *
+     * §8.4: every host trigger drives this same client — the scheduler, the
+     * realtime supervisor's connect-time catch-up, and app code — so a call
+     * that arrives while a drive is in flight waits for that drive and then
+     * runs one follow-up drive. The follow-up is required, not defensive: the
+     * caller may have mutated the outbox after the in-flight drive captured it.
+     * Callers that arrive during the same drive with the same budget share that
+     * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
      */
     syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
     connectRealtime(): Promise<void>;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { BLOB_COMMIT_REFS } from './blob.js';
-import { hasUniqueIndex } from './schema.js';
+import { hasUniqueIndex, pkSqlValue } from './schema.js';
 import { OUTCOMES_TABLE } from './outcomes.js';
 import { OUTBOX_TABLE } from './outbox.js';
 import { RETAINED_ROWS } from './failed-overlay.js';
@@ -178,6 +178,14 @@ export class SyncClient {
      * (the fast-bail the delta path reads).
      */
     #syncOutstanding = false;
+    /**
+     * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
+     * the last scheduled drive settles, and `#syncIdlePending` holds the
+     * scheduled drives that have not started, keyed by round budget, so a
+     * caller joins a waiting drive with its budget instead of queueing another.
+     */
+    #syncIdleTail;
+    #syncIdlePending = new Map();
     /**
      * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
      * round captures this epoch together with its subscription state; a
@@ -756,6 +764,8 @@ export class SyncClient {
         this.#securityLifecycle = 'active';
         const startupWork = this.#schemaFloor === undefined &&
             (countOutbox(this.#db) > 0 ||
+                this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
+                loadPendingEvictions(this.#db).length > 0 ||
                 loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
         if (startupWork) {
             this.#setSyncNeeded(true);
@@ -1496,6 +1506,7 @@ export class SyncClient {
         const task = Promise.resolve().then(fn);
         this.#protectedAsync.add(task);
         const settled = () => {
+            this.#protectedAsync.delete(task);
             if (this.#realtimeConnectPromise === task)
                 this.#realtimeConnectPromise = undefined;
         };
@@ -1826,7 +1837,12 @@ export class SyncClient {
             if (!sameIntent) {
                 throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
             }
-            return;
+            // §3.3: a revoked registration keeps its id and intent but no progress.
+            // Subscribing again with the same intent re-arms it, so the next pull
+            // resolves its scopes from scratch. A `failed` registration is a
+            // configuration error and stays put.
+            if (existing.status !== 'revoked')
+                return;
         }
         saveSubscription(this.#db, definedObject({
             id: input.id,
@@ -2077,7 +2093,7 @@ export class SyncClient {
                 const scopeColumns = new Set(table.scopeColumnByVariable.values());
                 const pkColumn = table.columns[table.primaryKeyIndex];
                 const pkValue = requireRowId(normalized.get(pkColumn.name));
-                const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkValue])[0];
+                const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, pkValue)])[0];
                 if (!local)
                     throw new ClientSyncError('sync.row_missing', 'a sparse patch requires a local row');
                 for (const column of table.columns) {
@@ -2204,16 +2220,24 @@ export class SyncClient {
         const pkColumn = compiled.columns[compiled.primaryKeyIndex];
         const normalized = normalizeRecordKeys(compiled, partial);
         const pkOverride = normalized.get(pkColumn.name);
-        if (pkOverride !== undefined && pkOverride !== rowId) {
+        if (pkOverride !== undefined && String(pkOverride) !== rowId) {
             throw invalidRequest(`table ${compiled.name}: patch cannot change the primary key`);
         }
+        const pkType = localColumnType(pkColumn);
+        const typedPk = pkType === 'integer' &&
+            Number.isSafeInteger(Number(rowId)) &&
+            String(Number(rowId)) === rowId
+            ? Number(rowId)
+            : pkType === 'boolean' && (rowId === 'true' || rowId === 'false')
+                ? rowId === 'true'
+                : rowId;
         return this.#recordMutations([
             definedObject({
                 table,
                 op: 'patch',
                 values: {
                     ...Object.fromEntries(normalized),
-                    [pkColumn.name]: rowId,
+                    [pkColumn.name]: typedPk,
                 },
                 baseVersion: options?.baseVersion,
             }),
@@ -2524,7 +2548,7 @@ export class SyncClient {
                         const selector = this.#encryption?.keyIdColumns?.[table.name];
                         if (selector === undefined)
                             return undefined;
-                        const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [rowId])[0];
+                        const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
                         const value = row?.value;
                         return typeof value === 'string' && value.length > 0
                             ? value
@@ -2907,6 +2931,14 @@ export class SyncClient {
     /**
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+     *
+     * §8.4: every host trigger drives this same client — the scheduler, the
+     * realtime supervisor's connect-time catch-up, and app code — so a call
+     * that arrives while a drive is in flight waits for that drive and then
+     * runs one follow-up drive. The follow-up is required, not defensive: the
+     * caller may have mutated the outbox after the in-flight drive captured it.
+     * Callers that arrive during the same drive with the same budget share that
+     * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
      */
     async syncUntilIdle(maxRounds) {
         // §7.7: an explicit budget is a strict positive round count. Zero,
@@ -2914,6 +2946,31 @@ export class SyncClient {
         if (maxRounds !== undefined &&
             (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
             throw invalidRequest('maxRounds must be a positive integer');
+        const pending = this.#syncIdlePending.get(maxRounds);
+        if (pending !== undefined)
+            return pending;
+        const previous = this.#syncIdleTail;
+        let drive;
+        if (previous === undefined) {
+            drive = this.#syncIdleRounds(maxRounds);
+        }
+        else {
+            drive = previous.then(() => {
+                this.#syncIdlePending.delete(maxRounds);
+                return this.#syncIdleRounds(maxRounds);
+            });
+            this.#syncIdlePending.set(maxRounds, drive);
+        }
+        const tail = drive.then(() => undefined, () => undefined);
+        this.#syncIdleTail = tail;
+        void tail.then(() => {
+            if (this.#syncIdleTail === tail)
+                this.#syncIdleTail = undefined;
+        });
+        return drive;
+    }
+    /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
+    async #syncIdleRounds(maxRounds) {
         const budget = maxRounds ?? 20;
         const aggregate = {
             pushed: 0,
@@ -3085,15 +3142,6 @@ export class SyncClient {
         this.#setRealtimeState('connecting');
         const task = this.#runProtectedAsync(() => this.#connectRealtime(generation));
         this.#realtimeConnectPromise = task;
-        void task.then(() => {
-            if (this.#realtimeConnectPromise === task) {
-                this.#realtimeConnectPromise = undefined;
-            }
-        }, () => {
-            if (this.#realtimeConnectPromise === task) {
-                this.#realtimeConnectPromise = undefined;
-            }
-        });
         return task;
     }
     async #connectRealtime(generation) {
@@ -3753,7 +3801,7 @@ export class SyncClient {
         const mappings = [...table.scopeColumnByVariable].filter(([variable]) => table.scopePrefixByVariable.has(variable));
         if (mappings.length === 0)
             return false;
-        const row = this.#db.query(`SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [rowId])[0];
+        const row = this.#db.query(`SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
         if (row === undefined)
             return false;
         let recorded = false;
@@ -4048,7 +4096,7 @@ export class SyncClient {
             ...table.columns.map((column) => quoteIdent(column.name)),
             quoteIdent(SYNC_VERSION_COLUMN),
         ];
-        const row = this.#db.query(`SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [operation.rowId])[0];
+        const row = this.#db.query(`SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0];
         if (row === undefined)
             return { opIndex, existed: false };
         const values = {};
@@ -4088,7 +4136,7 @@ export class SyncClient {
             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];
+            const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0];
             if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
                 batch.table(table.name);
                 deleteLocalRow(this.#db, table, operation.rowId);
@@ -4164,7 +4212,7 @@ export class SyncClient {
             // sync.row_missing, and the local mirror never invents a base.
             const opValues = op.values ?? {};
             const full = table.columns.every((column) => column.name in opValues);
-            const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [op.rowId])[0];
+            const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, op.rowId)])[0];
             if (local === undefined && !full) {
                 if (batch !== undefined && !precise)
                     batch.table(op.table);
@@ -4382,7 +4430,12 @@ function definedObject(record) {
     return record;
 }
 function requireRowId(value) {
-    if (typeof value !== 'string' || !value.length)
-        throw invalidRequest('a mutation requires a non-empty string primary key');
-    return value;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value)) {
+        return String(value);
+    }
+    if (typeof value === 'boolean')
+        return String(value);
+    throw invalidRequest('a mutation requires a non-empty primary key');
 }

package/dist/failed-overlay.js

@@ -3,7 +3,7 @@ import { OUTCOMES_TABLE } from './outcomes.js';
 import { OUTBOX_TABLE } from './outbox.js';
 export const RETAINED_ROWS = '_syncular_failed_rows';
 import { ClientSyncError } from './errors.js';
-import { mapRowValues, fromSqlValue, jsonToRowValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
+import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
 import { deleteLocalRow, upsertLocalRow } from './apply.js';
 /** Protected failure state. The server base advances independently of intent. */
 export function ensureFailedOverlaySchema(db) {
@@ -131,7 +131,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
             if (table === undefined)
                 continue;
             if (acknowledged) {
-                if (!db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [operation.rowId]).length)
+                if (!db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)]).length)
                     operation = {
                         ...operation,
                         values: JSON.parse(row.intent),

package/dist/http.js

@@ -229,25 +229,30 @@ export function httpBlobTransport(blobsBaseUrl, options) {
                         : response.status === 401
                             ? 'sync.auth_required'
                             : 'sync.transport_failed');
-            // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
-            // an octet-stream body is inline bytes.
+            // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
+            // any other body is inline bytes. The body is read exactly once as bytes,
+            // so an inline blob stored as `application/json` stays readable.
             const contentType = response.headers.get('content-type') ?? '';
+            const bytes = new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status));
             if (contentType.includes('application/json')) {
-                const body = (await transfer('blob download body read failed', () => response.json(), response.status));
-                if (typeof body.url === 'string') {
+                let envelope = null;
+                try {
+                    envelope = JSON.parse(new TextDecoder().decode(bytes));
+                }
+                catch {
+                    // Not JSON: inline bytes.
+                }
+                if (typeof envelope?.url === 'string') {
                     return {
                         kind: 'url',
-                        url: body.url,
-                        ...(typeof body.urlExpiresAtMs === 'number'
-                            ? { urlExpiresAtMs: body.urlExpiresAtMs }
+                        url: envelope.url,
+                        ...(typeof envelope.urlExpiresAtMs === 'number'
+                            ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
                             : {}),
                     };
                 }
             }
-            return {
-                kind: 'bytes',
-                bytes: new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status)),
-            };
+            return { kind: 'bytes', bytes };
         },
         // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
         fetchUrl: async (url) => {

package/dist/remote.js

@@ -163,9 +163,15 @@ export class SyncRemoteClient {
                     ? coerceSqlRepresentation(column, normalized.get(column.name))
                     : undefined)
                 : recordToRowValues(table, mutation.values);
-            const rowId = values[table.primaryKeyIndex];
-            if (typeof rowId !== 'string' || rowId.length === 0) {
-                throw invalid('remote upsert requires a non-empty string primary key');
+            const rawRowId = values[table.primaryKeyIndex];
+            const rowId = typeof rawRowId === 'string' && rawRowId.length > 0
+                ? rawRowId
+                : (typeof rawRowId === 'number' && Number.isSafeInteger(rawRowId)) ||
+                    typeof rawRowId === 'boolean'
+                    ? String(rawRowId)
+                    : undefined;
+            if (rowId === undefined) {
+                throw invalid('remote upsert requires a non-empty primary key');
             }
             if (this.#encryption !== undefined && table.hasEncryptedColumns) {
                 values = await encryptRowValues(this.#encryption, table, rowId, values);

package/dist/schema.d.ts

@@ -95,6 +95,12 @@ export declare const OPTIMISTIC_VERSION = -1;
 export declare function stripSyncColumns(rows: SqlRow[]): SqlRow[];
 export declare function hasUniqueIndex(table: CompiledClientTable): boolean;
 export declare function matchesLocalScopes(table: CompiledClientTable, scopes: Readonly<Record<string, readonly string[]>>, values: Readonly<Record<string, JsonRowValue>>): boolean;
+/**
+ * §2.4: bind a rowId against the local primary-key column. An integer or
+ * boolean key matches only its canonical string form; any other rowId names
+ * no row, so it binds NULL instead of letting SQLite affinity coerce `042`.
+ */
+export declare function pkSqlValue(table: CompiledClientTable, rowId: string): SqlValue;
 export declare function quoteIdent(name: string): string;
 /**
  * §5.11: the app-side type of a column for local (plaintext) storage. For an

package/dist/schema.js

@@ -179,9 +179,30 @@ export function matchesLocalScopes(table, scopes, values) {
     return (entries.length > 0 &&
         entries.every(([variable, allowed]) => {
             const column = table.scopeColumnByVariable.get(variable);
-            return column !== undefined && allowed.includes(String(values[column]));
+            if (column === undefined)
+                return false;
+            const value = values[column];
+            return (value !== undefined && value !== null && allowed.includes(String(value)));
         }));
 }
+/**
+ * §2.4: bind a rowId against the local primary-key column. An integer or
+ * boolean key matches only its canonical string form; any other rowId names
+ * no row, so it binds NULL instead of letting SQLite affinity coerce `042`.
+ */
+export function pkSqlValue(table, rowId) {
+    const pkType = localColumnType(table.columns[table.primaryKeyIndex]);
+    if (pkType === 'boolean') {
+        return rowId === 'true' ? 1 : rowId === 'false' ? 0 : null;
+    }
+    if (pkType === 'integer') {
+        const parsed = Number(rowId);
+        return Number.isSafeInteger(parsed) && String(parsed) === rowId
+            ? parsed
+            : null;
+    }
+    return rowId;
+}
 export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
 }

package/dist/sync-scheduler.d.ts

@@ -2,8 +2,10 @@ import type { WakeReason } from '@syncular/core';
 import type { SecurityLifecycle } from './client.js';
 import type { SyncIntent } from './invalidation.js';
 export interface SyncSchedulerClient {
-    readonly syncNeeded: boolean;
-    readonly securityLifecycle: SecurityLifecycle;
+    statusSnapshot(): {
+        readonly syncNeeded: boolean;
+    };
+    securityLifecycle(): SecurityLifecycle;
     syncUntilIdle(maxRounds?: number): Promise<unknown>;
     onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
     onSyncIntent(listener: (intent: SyncIntent) => void): () => void;

package/dist/sync-scheduler.js

@@ -47,7 +47,7 @@ export function installSyncScheduler(client, options = {}) {
     const run = () => {
         if (stopped || running)
             return;
-        if (client.securityLifecycle === 'preflight') {
+        if (client.securityLifecycle() === 'preflight') {
             immediatePending = false;
             return;
         }
@@ -110,7 +110,8 @@ export function installSyncScheduler(client, options = {}) {
         consume({ kind: 'interactive' });
     });
     const unsubscribeIntent = client.onSyncIntent(consume);
-    if (client.syncNeeded && client.securityLifecycle === 'active') {
+    if (client.statusSnapshot().syncNeeded &&
+        client.securityLifecycle() === 'active') {
         consume({ kind: 'interactive' });
     }
     return {

package/dist/worker-entry.js

@@ -76,15 +76,21 @@ export function startSyncWorker(overrides = {}) {
     let backgroundTimer;
     let backgroundDue = Number.POSITIVE_INFINITY;
     function runAutoSync() {
-        autoSyncScheduled = false;
         if (closed ||
             client === undefined ||
             offline ||
             client.securityLifecycle() === 'preflight') {
+            autoSyncScheduled = false;
             return;
         }
         const running = client;
-        void serializedSync(() => running.syncUntilIdle())
+        void serializedSync(() => {
+            // The queued round owns the flag from here. Clearing it at entry would
+            // let every wake-up that arrives while this round waits behind the
+            // running one queue its own full drive (§8.4 coalescing).
+            autoSyncScheduled = false;
+            return running.syncUntilIdle();
+        })
             .then((summary) => {
             if (!closed)
                 post({ t: 'event', event: { kind: 'synced', summary } });
@@ -453,7 +459,9 @@ export function startSyncWorker(overrides = {}) {
         if (message.t === 'call') {
             run(message.id, () => dispatch(message), message.method === 'query'
                 ? (value) => queryTransferables(value)
-                : undefined);
+                : message.method === 'querySnapshot'
+                    ? (value) => queryTransferables(value.rows)
+                    : undefined);
         }
     });
     post({ t: 'ready' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.32.0"
+    "@syncular/core": "0.33.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.32.0",
+    "@syncular/server": "0.33.0",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/apply.ts

@@ -24,6 +24,7 @@ import {
   quoteIdent,
   matchesLocalScopes,
   type JsonRowValue,
+  pkSqlValue,
   SYNC_VERSION_COLUMN,
   toSqlValue,
   rowValueToJson,
@@ -77,7 +78,7 @@ export function deleteLocalRow(
   if (serverWrite) retainedBaseWrite(db, table, rowId);
   db.exec(
     `DELETE FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-    [rowId],
+    [pkSqlValue(table, rowId)],
   );
 }
 

package/src/client.ts

@@ -1,6 +1,6 @@
 import { BLOB_COMMIT_REFS } from './blob';
 import type { AuthorityReadPolicy, AuthoritySnapshot } from './authority';
-import { hasUniqueIndex } from './schema';
+import { hasUniqueIndex, pkSqlValue } from './schema';
 import { OUTCOMES_TABLE } from './outcomes';
 import { OUTBOX_TABLE } from './outbox';
 import { RETAINED_ROWS } from './failed-overlay';
@@ -893,6 +893,17 @@ export class SyncClient {
    * (the fast-bail the delta path reads).
    */
   #syncOutstanding = false;
+  /**
+   * Idle drives run one after another (§8.4): `#syncIdleTail` settles when
+   * the last scheduled drive settles, and `#syncIdlePending` holds the
+   * scheduled drives that have not started, keyed by round budget, so a
+   * caller joins a waiting drive with its budget instead of queueing another.
+   */
+  #syncIdleTail: Promise<void> | undefined;
+  readonly #syncIdlePending = new Map<
+    number | undefined,
+    Promise<SyncIdleResult>
+  >();
   /**
    * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
    * round captures this epoch together with its subscription state; a
@@ -1579,6 +1590,10 @@ export class SyncClient {
     const startupWork =
       this.#schemaFloor === undefined &&
       (countOutbox(this.#db) > 0 ||
+        this.#db.query(
+          `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
+        ).length > 0 ||
+        loadPendingEvictions(this.#db).length > 0 ||
         loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
     if (startupWork) {
       this.#setSyncNeeded(true);
@@ -2470,6 +2485,7 @@ export class SyncClient {
     const task = Promise.resolve().then(fn);
     this.#protectedAsync.add(task);
     const settled = () => {
+      this.#protectedAsync.delete(task);
       if (this.#realtimeConnectPromise === task)
         this.#realtimeConnectPromise = undefined;
     };
@@ -2898,7 +2914,11 @@ export class SyncClient {
           'subscription id already names different table, scopes, or params',
         );
       }
-      return;
+      // §3.3: a revoked registration keeps its id and intent but no progress.
+      // Subscribing again with the same intent re-arms it, so the next pull
+      // resolves its scopes from scratch. A `failed` registration is a
+      // configuration error and stays put.
+      if (existing.status !== 'revoked') return;
     }
     saveSubscription(
       this.#db,
@@ -3184,7 +3204,7 @@ export class SyncClient {
         const pkValue = requireRowId(normalized.get(pkColumn.name));
         const local = this.#db.query(
           `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-          [pkValue],
+          [pkSqlValue(table, pkValue)],
         )[0];
         if (!local)
           throw new ClientSyncError(
@@ -3351,18 +3371,27 @@ export class SyncClient {
     const pkColumn = compiled.columns[compiled.primaryKeyIndex] as RowColumn;
     const normalized = normalizeRecordKeys(compiled, partial);
     const pkOverride = normalized.get(pkColumn.name);
-    if (pkOverride !== undefined && pkOverride !== rowId) {
+    if (pkOverride !== undefined && String(pkOverride) !== rowId) {
       throw invalidRequest(
         `table ${compiled.name}: patch cannot change the primary key`,
       );
     }
+    const pkType = localColumnType(pkColumn);
+    const typedPk =
+      pkType === 'integer' &&
+      Number.isSafeInteger(Number(rowId)) &&
+      String(Number(rowId)) === rowId
+        ? Number(rowId)
+        : pkType === 'boolean' && (rowId === 'true' || rowId === 'false')
+          ? rowId === 'true'
+          : rowId;
     return this.#recordMutations([
       definedObject({
         table,
         op: 'patch',
         values: {
           ...Object.fromEntries(normalized),
-          [pkColumn.name]: rowId,
+          [pkColumn.name]: typedPk,
         },
         baseVersion: options?.baseVersion,
       }),
@@ -3745,7 +3774,7 @@ export class SyncClient {
               if (selector === undefined) return undefined;
               const row = this.#db.query(
                 `SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-                [rowId],
+                [pkSqlValue(table, rowId)],
               )[0];
               const value = row?.value;
               return typeof value === 'string' && value.length > 0
@@ -4213,6 +4242,14 @@ export class SyncClient {
   /**
    * Pull repeatedly until quiescent: no commits delivered, no bootstrap
    * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
+   *
+   * §8.4: every host trigger drives this same client — the scheduler, the
+   * realtime supervisor's connect-time catch-up, and app code — so a call
+   * that arrives while a drive is in flight waits for that drive and then
+   * runs one follow-up drive. The follow-up is required, not defensive: the
+   * caller may have mutated the outbox after the in-flight drive captured it.
+   * Callers that arrive during the same drive with the same budget share that
+   * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
    */
   async syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
     // §7.7: an explicit budget is a strict positive round count. Zero,
@@ -4222,6 +4259,34 @@ export class SyncClient {
       (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
     )
       throw invalidRequest('maxRounds must be a positive integer');
+    const pending = this.#syncIdlePending.get(maxRounds);
+    if (pending !== undefined) return pending;
+    const previous = this.#syncIdleTail;
+    let drive: Promise<SyncIdleResult>;
+    if (previous === undefined) {
+      drive = this.#syncIdleRounds(maxRounds);
+    } else {
+      drive = previous.then(() => {
+        this.#syncIdlePending.delete(maxRounds);
+        return this.#syncIdleRounds(maxRounds);
+      });
+      this.#syncIdlePending.set(maxRounds, drive);
+    }
+    const tail = drive.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.#syncIdleTail = tail;
+    void tail.then(() => {
+      if (this.#syncIdleTail === tail) this.#syncIdleTail = undefined;
+    });
+    return drive;
+  }
+
+  /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
+  async #syncIdleRounds(
+    maxRounds: number | undefined,
+  ): Promise<SyncIdleResult> {
     const budget = maxRounds ?? 20;
     const aggregate = {
       pushed: 0,
@@ -4428,18 +4493,6 @@ export class SyncClient {
       this.#connectRealtime(generation),
     );
     this.#realtimeConnectPromise = task;
-    void task.then(
-      () => {
-        if (this.#realtimeConnectPromise === task) {
-          this.#realtimeConnectPromise = undefined;
-        }
-      },
-      () => {
-        if (this.#realtimeConnectPromise === task) {
-          this.#realtimeConnectPromise = undefined;
-        }
-      },
-    );
     return task;
   }
 
@@ -5273,7 +5326,7 @@ export class SyncClient {
     if (mappings.length === 0) return false;
     const row = this.#db.query(
       `SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-      [rowId],
+      [pkSqlValue(table, rowId)],
     )[0];
     if (row === undefined) return false;
     let recorded = false;
@@ -5668,7 +5721,7 @@ export class SyncClient {
     ];
     const row = this.#db.query(
       `SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-      [operation.rowId],
+      [pkSqlValue(table, operation.rowId)],
     )[0];
     if (row === undefined) return { opIndex, existed: false };
     const values: Record<string, ReturnType<typeof rowValueToJson>> = {};
@@ -5732,7 +5785,7 @@ export class SyncClient {
       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],
+        [pkSqlValue(table, operation.rowId)],
       )[0];
       if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
         batch.table(table.name);
@@ -5826,7 +5879,7 @@ export class SyncClient {
       const full = table.columns.every((column) => column.name in opValues);
       const local = this.#db.query(
         `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-        [op.rowId],
+        [pkSqlValue(table, op.rowId)],
       )[0];
       if (local === undefined && !full) {
         if (batch !== undefined && !precise) batch.table(op.table);
@@ -6110,7 +6163,10 @@ function definedObject<const T extends object>(record: T): DefinedObject<T> {
 }
 
 function requireRowId(value: unknown): string {
-  if (typeof value !== 'string' || !value.length)
-    throw invalidRequest('a mutation requires a non-empty string primary key');
-  return value;
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isSafeInteger(value)) {
+    return String(value);
+  }
+  if (typeof value === 'boolean') return String(value);
+  throw invalidRequest('a mutation requires a non-empty primary key');
 }

package/src/failed-overlay.ts

@@ -13,6 +13,7 @@ import {
   mapRowValues,
   fromSqlValue,
   jsonToRowValue,
+  pkSqlValue,
   quoteIdent,
   rowValueToJson,
   SYNC_VERSION_COLUMN,
@@ -245,7 +246,7 @@ export function failedOverlayCommits(
         if (
           !db.query(
             `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
-            [operation.rowId],
+            [pkSqlValue(table, operation.rowId)],
           ).length
         )
           operation = {

package/src/http.ts

@@ -355,38 +355,35 @@ export function httpBlobTransport(
                 ? 'sync.auth_required'
                 : 'sync.transport_failed',
         );
-      // §5.9.5 always-issue: a JSON body with `url` means presigned delivery;
-      // an octet-stream body is inline bytes.
+      // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
+      // any other body is inline bytes. The body is read exactly once as bytes,
+      // so an inline blob stored as `application/json` stays readable.
       const contentType = response.headers.get('content-type') ?? '';
-      if (contentType.includes('application/json')) {
-        const body = (await transfer(
+      const bytes = new Uint8Array(
+        await transfer(
           'blob download body read failed',
-          () => response.json(),
+          () => response.arrayBuffer(),
           response.status,
-        )) as {
-          url?: string;
-          urlExpiresAtMs?: number;
-        };
-        if (typeof body.url === 'string') {
+        ),
+      );
+      if (contentType.includes('application/json')) {
+        let envelope: { url?: unknown; urlExpiresAtMs?: unknown } | null = null;
+        try {
+          envelope = JSON.parse(new TextDecoder().decode(bytes));
+        } catch {
+          // Not JSON: inline bytes.
+        }
+        if (typeof envelope?.url === 'string') {
           return {
             kind: 'url',
-            url: body.url,
-            ...(typeof body.urlExpiresAtMs === 'number'
-              ? { urlExpiresAtMs: body.urlExpiresAtMs }
+            url: envelope.url,
+            ...(typeof envelope.urlExpiresAtMs === 'number'
+              ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
               : {}),
           };
         }
       }
-      return {
-        kind: 'bytes',
-        bytes: new Uint8Array(
-          await transfer(
-            'blob download body read failed',
-            () => response.arrayBuffer(),
-            response.status,
-          ),
-        ),
-      };
+      return { kind: 'bytes', bytes };
     },
     // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
     fetchUrl: async (url) => {

package/src/remote.ts

@@ -326,9 +326,16 @@ export class SyncRemoteClient {
                 : undefined,
             )
           : recordToRowValues(table, mutation.values);
-      const rowId = values[table.primaryKeyIndex];
-      if (typeof rowId !== 'string' || rowId.length === 0) {
-        throw invalid('remote upsert requires a non-empty string primary key');
+      const rawRowId = values[table.primaryKeyIndex];
+      const rowId =
+        typeof rawRowId === 'string' && rawRowId.length > 0
+          ? rawRowId
+          : (typeof rawRowId === 'number' && Number.isSafeInteger(rawRowId)) ||
+              typeof rawRowId === 'boolean'
+            ? String(rawRowId)
+            : undefined;
+      if (rowId === undefined) {
+        throw invalid('remote upsert requires a non-empty primary key');
       }
       if (this.#encryption !== undefined && table.hasEncryptedColumns) {
         values = await encryptRowValues(this.#encryption, table, rowId, values);

package/src/schema.ts

@@ -298,11 +298,37 @@ export function matchesLocalScopes(
     entries.length > 0 &&
     entries.every(([variable, allowed]) => {
       const column = table.scopeColumnByVariable.get(variable);
-      return column !== undefined && allowed.includes(String(values[column]));
+      if (column === undefined) return false;
+      const value = values[column];
+      return (
+        value !== undefined && value !== null && allowed.includes(String(value))
+      );
     })
   );
 }
 
+/**
+ * §2.4: bind a rowId against the local primary-key column. An integer or
+ * boolean key matches only its canonical string form; any other rowId names
+ * no row, so it binds NULL instead of letting SQLite affinity coerce `042`.
+ */
+export function pkSqlValue(
+  table: CompiledClientTable,
+  rowId: string,
+): SqlValue {
+  const pkType = localColumnType(table.columns[table.primaryKeyIndex]!);
+  if (pkType === 'boolean') {
+    return rowId === 'true' ? 1 : rowId === 'false' ? 0 : null;
+  }
+  if (pkType === 'integer') {
+    const parsed = Number(rowId);
+    return Number.isSafeInteger(parsed) && String(parsed) === rowId
+      ? parsed
+      : null;
+  }
+  return rowId;
+}
+
 export function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
 }

package/src/sync-scheduler.ts

@@ -3,8 +3,8 @@ import type { SecurityLifecycle } from './client';
 import type { SyncIntent } from './invalidation';
 
 export interface SyncSchedulerClient {
-  readonly syncNeeded: boolean;
-  readonly securityLifecycle: SecurityLifecycle;
+  statusSnapshot(): { readonly syncNeeded: boolean };
+  securityLifecycle(): SecurityLifecycle;
   syncUntilIdle(maxRounds?: number): Promise<unknown>;
   onSyncNeeded(
     listener: (reason: 'startup' | 'hello' | WakeReason) => void,
@@ -79,7 +79,7 @@ export function installSyncScheduler(
 
   const run = (): void => {
     if (stopped || running) return;
-    if (client.securityLifecycle === 'preflight') {
+    if (client.securityLifecycle() === 'preflight') {
       immediatePending = false;
       return;
     }
@@ -144,7 +144,10 @@ export function installSyncScheduler(
     consume({ kind: 'interactive' });
   });
   const unsubscribeIntent = client.onSyncIntent(consume);
-  if (client.syncNeeded && client.securityLifecycle === 'active') {
+  if (
+    client.statusSnapshot().syncNeeded &&
+    client.securityLifecycle() === 'active'
+  ) {
     consume({ kind: 'interactive' });
   }
 

package/src/worker-entry.ts

@@ -164,17 +164,23 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   let backgroundDue = Number.POSITIVE_INFINITY;
 
   function runAutoSync(): void {
-    autoSyncScheduled = false;
     if (
       closed ||
       client === undefined ||
       offline ||
       client.securityLifecycle() === 'preflight'
     ) {
+      autoSyncScheduled = false;
       return;
     }
     const running = client;
-    void serializedSync(() => running.syncUntilIdle())
+    void serializedSync(() => {
+      // The queued round owns the flag from here. Clearing it at entry would
+      // let every wake-up that arrives while this round waits behind the
+      // running one queue its own full drive (§8.4 coalescing).
+      autoSyncScheduled = false;
+      return running.syncUntilIdle();
+    })
       .then((summary) => {
         if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
         if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
@@ -584,7 +590,12 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         () => dispatch(message),
         message.method === 'query'
           ? (value) => queryTransferables(value as readonly unknown[])
-          : undefined,
+          : message.method === 'querySnapshot'
+            ? (value) =>
+                queryTransferables(
+                  (value as { readonly rows: readonly unknown[] }).rows,
+                )
+            : undefined,
       );
     }
   });