@syncular/client 0.31.0 → 0.32.1

package/README.md

@@ -284,7 +284,7 @@ stable code-like values (`A-Z`, `a-z`, `0-9`, dot, underscore, dash).
 During Vite development, retain the React client resource only while its
 captured generated schema version and published Syncular runtime identity both
 match. The
-[schema-and-runtime-aware Vite guide](https://syncular.dev/guide-vite/) uses
+[schema-and-runtime-aware Vite guide](https://syncular.dev/platform-web-install/#configure-vite) uses
 `retainViteSyncClientResource` to close the old worker before constructing a
 schema-bump or package-upgrade replacement; hot-reloading query code alone does
 not migrate the worker-owned database.

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.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';
@@ -756,6 +756,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 +1498,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;
         };
@@ -2077,7 +2080,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 +2207,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 +2535,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
@@ -3085,15 +3096,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 +3755,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 +4050,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 +4090,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 +4166,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 +4384,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/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/worker-entry.js

@@ -453,7 +453,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.31.0",
+  "version": "0.32.1",
   "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.31.0"
+    "@syncular/core": "0.32.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.31.0",
+    "@syncular/server": "0.32.1",
     "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';
@@ -1579,6 +1579,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 +2474,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;
     };
@@ -3184,7 +3189,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 +3356,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 +3759,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
@@ -4428,18 +4442,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 +5275,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 +5670,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 +5734,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 +5828,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 +6112,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/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/worker-entry.ts

@@ -584,7 +584,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,
       );
     }
   });