@syncular/client 0.21.0 → 0.22.0

package/dist/client.js

@@ -9,6 +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 { EncryptError } from '@syncular/core';
 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';
@@ -1412,12 +1413,31 @@ export class SyncClient {
                 // present ones.
                 const normalized = normalizeRecordKeys(table, mutation.values);
                 const scopeColumns = new Set(table.scopeColumnByVariable.values());
+                const pkColumn = table.columns[table.primaryKeyIndex];
                 const json = {};
                 for (const column of table.columns) {
                     if (!normalized.has(column.name))
                         continue;
-                    if (scopeColumns.has(column.name)) {
-                        throw new ClientSyncError('sync.invalid_request', `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
+                    // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
+                    // server accepts a present scope column whose value equals the
+                    // stored row and applies it as a no-op, so a decoded envelope
+                    // round-trips. The local row is the only value the client can
+                    // prove equality against; when the row is absent locally the
+                    // client cannot prove equality against the server's stored row
+                    // and fails closed. A primary key that is also a scope column
+                    // needs no stored-row read: the primary key in a sparse payload is
+                    // by construction the row id being patched (§6.1), so its value is
+                    // proven equal already.
+                    if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
+                        const pkValue = normalized.get(pkColumn.name);
+                        const local = typeof pkValue === 'string' && pkValue.length > 0
+                            ? this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [pkValue])[0]
+                            : undefined;
+                        if (local === undefined ||
+                            !Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
+                            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
+                        }
+                        continue;
                     }
                     const value = normalized.get(column.name);
                     if (value === undefined || value === null) {
@@ -1429,7 +1449,6 @@ export class SyncClient {
                     }
                     json[column.name] = rowValueToJson(coerceSqlRepresentation(column, value));
                 }
-                const pkColumn = table.columns[table.primaryKeyIndex];
                 const pkValue = json[pkColumn.name];
                 if (typeof pkValue !== 'string' || pkValue.length === 0) {
                     throw new ClientSyncError('sync.invalid_request', `table ${table.name}: upsert requires a non-empty string primary key`);
@@ -1807,8 +1826,20 @@ export class SyncClient {
             try {
                 pushFrames.push(
                 // §5.11: encrypted columns are encrypted at this encode-at-send
-                // seam before the row codec serializes them.
-                await encodeOutboxCommit(this.#schema, commit, this.#encryption));
+                // seam before the row codec serializes them. The stored local row
+                // supplies an ABSENT key-id selector (§6.1 presence set first,
+                // stored row second); an unresolvable key becomes a durable
+                // rejection for that commit, never a sync() throw.
+                await encodeOutboxCommit(this.#schema, commit, this.#encryption, (table, rowId) => {
+                    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 value = row?.value;
+                    return typeof value === 'string' && value.length > 0
+                        ? value
+                        : undefined;
+                }));
                 outbox.push(commit);
                 ops += commit.operations.length;
             }
@@ -1817,6 +1848,10 @@ export class SyncClient {
                     this.#dropIncompatibleCommit(commit, error.message);
                     continue;
                 }
+                if (error instanceof EncryptError) {
+                    this.#dropIncompatibleCommit(commit, error.message, error.code);
+                    continue;
+                }
                 throw error;
             }
         }
@@ -1826,14 +1861,15 @@ export class SyncClient {
      * §7.4.4: drop a commit that cannot re-encode after a bump, mirroring the
      * §7.2 `rejected` surface — the commit leaves the outbox, its
      * purely-optimistic rows are undone, and a rejection record is raised.
+     * §5.11: the same drop carries an encode-seam `client.encrypt_failed`.
      */
-    #dropIncompatibleCommit(commit, message) {
+    #dropIncompatibleCommit(commit, message, code = OUTBOX_INCOMPATIBLE_CODE) {
         this.#applyBatch((batch) => {
             this.#rollbackFailedCommit(commit, batch);
             const rejection = {
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
-                code: OUTBOX_INCOMPATIBLE_CODE,
+                code,
                 message,
                 retryable: false,
                 ...(commit.operations[0] !== undefined

package/dist/encryption.d.ts

@@ -57,7 +57,7 @@ export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringCo
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
  * unencrypted (§5.11).
  */
-export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[]): Promise<T[]>;
+export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[], storedKeyId?: string): Promise<T[]>;
 /**
  * Decrypt the encrypted columns of a decoded positional row value array
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows

package/dist/encryption.js

@@ -8,7 +8,7 @@
  * bridge between the positional `RowValue[]` and the `@syncular/core` §5.11
  * envelope primitives.
  */
-import { DecryptError, decryptValue, encryptValue, KEY_LENGTH, } from '@syncular/core';
+import { DecryptError, decryptValue, EncryptError, encryptValue, KEY_LENGTH, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
 /**
  * Convert a portable keyring into the direct-client encryption contract.
@@ -36,7 +36,7 @@ function encryptionKeyId(config, table, rowId, values) {
     if (config.keyIdFor !== undefined) {
         const selected = config.keyIdFor(table.name, rowId, values);
         if (selected.length === 0) {
-            throw new DecryptError(`empty encryption key id selected for table ${JSON.stringify(table.name)}`);
+            throw new EncryptError(`empty encryption key id selected for table ${JSON.stringify(table.name)}`);
         }
         return selected;
     }
@@ -45,14 +45,14 @@ function encryptionKeyId(config, table, rowId, values) {
         return table.name;
     const index = table.columns.findIndex((column) => column.name === selectorColumn);
     if (index < 0) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`);
     }
     if (table.columns[index]?.encrypted === true) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`);
     }
     const selected = values[index];
     if (typeof selected !== 'string' || selected.length === 0) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`);
     }
     return selected;
 }
@@ -68,13 +68,38 @@ function declaredTypeOf(column) {
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
  * unencrypted (§5.11).
  */
-export async function encryptRowValues(config, table, rowId, values) {
+export async function encryptRowValues(config, table, rowId, values, storedKeyId) {
     if (!table.hasEncryptedColumns)
         return values.slice();
     const out = values.slice();
-    // A sparse operation's absent columns are densified to null for key
-    // selection only; the encryption loop leaves them untouched.
-    const keyId = encryptionKeyId(config, table, rowId, values.map((value) => value ?? null));
+    // Sparse semantics: absent (undefined) and NULL columns are never
+    // re-encrypted, so a patch that presents no encrypted value needs no key.
+    let hasPresentEncrypted = false;
+    for (let i = 0; i < table.columns.length; i++) {
+        if (table.columns[i]?.encrypted !== true)
+            continue;
+        const value = out[i];
+        if (value !== undefined && value !== null) {
+            hasPresentEncrypted = true;
+            break;
+        }
+    }
+    if (!hasPresentEncrypted)
+        return out;
+    // Key selection reads the presence set first, then the stored local row.
+    // Absent slots densify to null for selection only; the loop below still
+    // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
+    // slot is filled from the stored row, never a present NULL.
+    const selected = values.map((value) => value ?? null);
+    const selectorColumn = config.keyIdColumns?.[table.name];
+    if (selectorColumn !== undefined &&
+        config.keyIdFor === undefined &&
+        storedKeyId !== undefined) {
+        const index = table.columns.findIndex((column) => column.name === selectorColumn);
+        if (index >= 0 && values[index] === undefined)
+            selected[index] = storedKeyId;
+    }
+    const keyId = encryptionKeyId(config, table, rowId, selected);
     for (let i = 0; i < table.columns.length; i++) {
         const column = table.columns[i];
         if (column === undefined || !column.encrypted)
@@ -84,7 +109,7 @@ export async function encryptRowValues(config, table, rowId, values) {
             continue; // NULL stays NULL
         const key = config.keyProvider(keyId);
         if (key === undefined) {
-            throw new DecryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);
+            throw new EncryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);
         }
         out[i] = (await encryptValue(declaredTypeOf(column), value, keyId, key, config.nonceSource));
     }

package/dist/outbox.d.ts

@@ -61,9 +61,10 @@ export declare class OutboxEncodeError extends ClientSyncError {
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
-export declare function encodeOutboxCommit(schema: CompiledClientSchema, commit: OutboxCommit, encryption?: EncryptionConfig): Promise<PushCommitFrame>;
+export declare function encodeOutboxCommit(schema: CompiledClientSchema, commit: OutboxCommit, encryption?: EncryptionConfig, storedKeyIdFor?: (table: CompiledClientTable, rowId: string) => string | undefined): Promise<PushCommitFrame>;
 /**
  * §3.3: drop pending commits that write into a revoked scope instead of
  * replaying them into guaranteed rejections. A whole commit is dropped when

package/dist/outbox.js

@@ -132,9 +132,10 @@ function sparseValues(table, values) {
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
-export async function encodeOutboxCommit(schema, commit, encryption) {
+export async function encodeOutboxCommit(schema, commit, encryption, storedKeyIdFor) {
     const operations = [];
     for (const op of commit.operations) {
         if (op.op === 'delete') {
@@ -160,7 +161,7 @@ export async function encodeOutboxCommit(schema, commit, encryption) {
         if (encryption !== undefined && table.hasEncryptedColumns) {
             // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
             const { encryptRowValues } = await import('./encryption.js');
-            values = await encryptRowValues(encryption, table, op.rowId, values);
+            values = await encryptRowValues(encryption, table, op.rowId, values, storedKeyIdFor?.(table, op.rowId));
         }
         operations.push({
             table: op.table,

package/dist/reactive-store.js

@@ -82,15 +82,21 @@ function scheduleMicrotask(task) {
 }
 function batchMatches(batch, spec) {
     for (const change of batch.tables) {
-        const dependency = spec.dependencies.find((candidate) => candidate.table === change.table);
-        if (dependency === undefined)
-            continue;
-        if (dependency.scopeKeys === undefined || change.scopeKeys === undefined) {
-            return true;
-        }
-        for (const key of dependency.scopeKeys) {
-            if (change.scopeKeys.has(key))
+        // A composed spec carries one dependency per query branch. Every
+        // dependency on the changed table is consulted: a scoped dependency
+        // that does not cover the change must not mask a sibling dependency
+        // on the same table that does.
+        for (const dependency of spec.dependencies) {
+            if (dependency.table !== change.table)
+                continue;
+            if (dependency.scopeKeys === undefined ||
+                change.scopeKeys === undefined) {
                 return true;
+            }
+            for (const key of dependency.scopeKeys) {
+                if (change.scopeKeys.has(key))
+                    return true;
+            }
         }
     }
     for (const change of batch.windows) {
@@ -268,8 +274,27 @@ class QueryEntry {
             this.#onAvailabilityChange();
             if (this.spec.claimCoverage !== false) {
                 const claims = [];
+                // A composed spec carries one coverage entry per query branch, and
+                // several branches can target the same base. One claim per distinct
+                // base covers the union of their units; a later entry for the same
+                // base does not replace the earlier one.
+                const unitsByBase = new Map();
                 for (const coverage of this.spec.coverage ?? []) {
-                    claims.push(this.store.setWindowClaim(this.#owner, coverage.base, coverage.units));
+                    const baseKey = windowBaseKey(coverage.base);
+                    const existing = unitsByBase.get(baseKey);
+                    if (existing === undefined) {
+                        unitsByBase.set(baseKey, {
+                            base: coverage.base,
+                            units: new Set(coverage.units),
+                        });
+                    }
+                    else {
+                        for (const unit of coverage.units)
+                            existing.units.add(unit);
+                    }
+                }
+                for (const { base, units } of unitsByBase.values()) {
+                    claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
                 }
                 const generation = this.#generation;
                 this.#claimPending = claims.length > 0;

package/dist/schema.js

@@ -31,6 +31,17 @@ export function compileClientSchema(schema) {
         if (primaryKeyIndex === undefined) {
             throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
         }
+        // §2.4 primary-key eligibility: a primary key MUST render to a `rowId`
+        // string every implementation produces identically and local storage
+        // resolves without deferring to a SQLite build.
+        const primaryKeyColumn = table.columns[primaryKeyIndex];
+        if (primaryKeyColumn !== undefined &&
+            primaryKeyColumn.type !== 'string' &&
+            primaryKeyColumn.type !== 'integer' &&
+            primaryKeyColumn.type !== 'boolean' &&
+            primaryKeyColumn.type !== 'json') {
+            throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json`);
+        }
         if (table.scopes.length === 0) {
             throw new Error(`table ${table.name}: every synced table declares at least one scope pattern (§3.1)`);
         }

package/package.json

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

package/src/client.ts

@@ -37,6 +37,7 @@ import {
   type SubStartFrame,
   type WakeReason,
 } from '@syncular/core';
+import { EncryptError } from '@syncular/core';
 import {
   applyCommitFrame,
   applyRowsSegment,
@@ -2152,14 +2153,49 @@ export class SyncClient {
         // present ones.
         const normalized = normalizeRecordKeys(table, mutation.values);
         const scopeColumns = new Set(table.scopeColumnByVariable.values());
+        const pkColumn = table.columns[table.primaryKeyIndex] as RowColumn;
         const json: Record<string, JsonRowValue> = {};
         for (const column of table.columns) {
           if (!normalized.has(column.name)) continue;
-          if (scopeColumns.has(column.name)) {
-            throw new ClientSyncError(
-              'sync.invalid_request',
-              `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`,
-            );
+          // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
+          // server accepts a present scope column whose value equals the
+          // stored row and applies it as a no-op, so a decoded envelope
+          // round-trips. The local row is the only value the client can
+          // prove equality against; when the row is absent locally the
+          // client cannot prove equality against the server's stored row
+          // and fails closed. A primary key that is also a scope column
+          // needs no stored-row read: the primary key in a sparse payload is
+          // by construction the row id being patched (§6.1), so its value is
+          // proven equal already.
+          if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
+            const pkValue = normalized.get(pkColumn.name);
+            const local =
+              typeof pkValue === 'string' && pkValue.length > 0
+                ? this.#db.query(
+                    `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
+                    [pkValue],
+                  )[0]
+                : undefined;
+            if (
+              local === undefined ||
+              !Object.is(
+                rowValueToJson(
+                  fromSqlValue(column, local[column.name] ?? null),
+                ),
+                rowValueToJson(
+                  coerceSqlRepresentation(
+                    column,
+                    normalized.get(column.name),
+                  ) as RowValue,
+                ),
+              )
+            ) {
+              throw new ClientSyncError(
+                'sync.invalid_request',
+                `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`,
+              );
+            }
+            continue;
           }
           const value = normalized.get(column.name);
           if (value === undefined || value === null) {
@@ -2176,7 +2212,6 @@ export class SyncClient {
             coerceSqlRepresentation(column, value) as RowValue,
           );
         }
-        const pkColumn = table.columns[table.primaryKeyIndex] as RowColumn;
         const pkValue = json[pkColumn.name];
         if (typeof pkValue !== 'string' || pkValue.length === 0) {
           throw new ClientSyncError(
@@ -2638,8 +2673,27 @@ export class SyncClient {
       try {
         pushFrames.push(
           // §5.11: encrypted columns are encrypted at this encode-at-send
-          // seam before the row codec serializes them.
-          await encodeOutboxCommit(this.#schema, commit, this.#encryption),
+          // seam before the row codec serializes them. The stored local row
+          // supplies an ABSENT key-id selector (§6.1 presence set first,
+          // stored row second); an unresolvable key becomes a durable
+          // rejection for that commit, never a sync() throw.
+          await encodeOutboxCommit(
+            this.#schema,
+            commit,
+            this.#encryption,
+            (table, rowId) => {
+              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 value = row?.value;
+              return typeof value === 'string' && value.length > 0
+                ? value
+                : undefined;
+            },
+          ),
         );
         outbox.push(commit);
         ops += commit.operations.length;
@@ -2648,6 +2702,10 @@ export class SyncClient {
           this.#dropIncompatibleCommit(commit, error.message);
           continue;
         }
+        if (error instanceof EncryptError) {
+          this.#dropIncompatibleCommit(commit, error.message, error.code);
+          continue;
+        }
         throw error;
       }
     }
@@ -2658,14 +2716,19 @@ export class SyncClient {
    * §7.4.4: drop a commit that cannot re-encode after a bump, mirroring the
    * §7.2 `rejected` surface — the commit leaves the outbox, its
    * purely-optimistic rows are undone, and a rejection record is raised.
+   * §5.11: the same drop carries an encode-seam `client.encrypt_failed`.
    */
-  #dropIncompatibleCommit(commit: OutboxCommit, message: string): void {
+  #dropIncompatibleCommit(
+    commit: OutboxCommit,
+    message: string,
+    code: string = OUTBOX_INCOMPATIBLE_CODE,
+  ): void {
     this.#applyBatch((batch) => {
       this.#rollbackFailedCommit(commit, batch);
       const rejection: RejectionRecord = {
         clientCommitId: commit.clientCommitId,
         opIndex: 0,
-        code: OUTBOX_INCOMPATIBLE_CODE,
+        code,
         message,
         retryable: false,
         ...(commit.operations[0] !== undefined

package/src/encryption.ts

@@ -12,6 +12,7 @@ import {
   type DeclaredType,
   DecryptError,
   decryptValue,
+  EncryptError,
   encryptValue,
   KEY_LENGTH,
   type NonceSource,
@@ -99,7 +100,7 @@ function encryptionKeyId(
   if (config.keyIdFor !== undefined) {
     const selected = config.keyIdFor(table.name, rowId, values);
     if (selected.length === 0) {
-      throw new DecryptError(
+      throw new EncryptError(
         `empty encryption key id selected for table ${JSON.stringify(table.name)}`,
       );
     }
@@ -111,18 +112,18 @@ function encryptionKeyId(
     (column) => column.name === selectorColumn,
   );
   if (index < 0) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`,
     );
   }
   if (table.columns[index]?.encrypted === true) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`,
     );
   }
   const selected = values[index];
   if (typeof selected !== 'string' || selected.length === 0) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`,
     );
   }
@@ -147,17 +148,40 @@ export async function encryptRowValues<T extends RowValue | undefined>(
   table: CompiledClientTable,
   rowId: string,
   values: readonly T[],
+  storedKeyId?: string,
 ): Promise<T[]> {
   if (!table.hasEncryptedColumns) return values.slice();
   const out = values.slice();
-  // A sparse operation's absent columns are densified to null for key
-  // selection only; the encryption loop leaves them untouched.
-  const keyId = encryptionKeyId(
-    config,
-    table,
-    rowId,
-    values.map((value) => value ?? null),
-  );
+  // Sparse semantics: absent (undefined) and NULL columns are never
+  // re-encrypted, so a patch that presents no encrypted value needs no key.
+  let hasPresentEncrypted = false;
+  for (let i = 0; i < table.columns.length; i++) {
+    if (table.columns[i]?.encrypted !== true) continue;
+    const value = out[i];
+    if (value !== undefined && value !== null) {
+      hasPresentEncrypted = true;
+      break;
+    }
+  }
+  if (!hasPresentEncrypted) return out;
+  // Key selection reads the presence set first, then the stored local row.
+  // Absent slots densify to null for selection only; the loop below still
+  // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
+  // slot is filled from the stored row, never a present NULL.
+  const selected: RowValue[] = values.map((value) => value ?? null);
+  const selectorColumn = config.keyIdColumns?.[table.name];
+  if (
+    selectorColumn !== undefined &&
+    config.keyIdFor === undefined &&
+    storedKeyId !== undefined
+  ) {
+    const index = table.columns.findIndex(
+      (column) => column.name === selectorColumn,
+    );
+    if (index >= 0 && values[index] === undefined)
+      selected[index] = storedKeyId;
+  }
+  const keyId = encryptionKeyId(config, table, rowId, selected);
   for (let i = 0; i < table.columns.length; i++) {
     const column = table.columns[i];
     if (column === undefined || !column.encrypted) continue;
@@ -165,7 +189,7 @@ export async function encryptRowValues<T extends RowValue | undefined>(
     if (value === null || value === undefined) continue; // NULL stays NULL
     const key = config.keyProvider(keyId);
     if (key === undefined) {
-      throw new DecryptError(
+      throw new EncryptError(
         `no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`,
       );
     }

package/src/outbox.ts

@@ -237,12 +237,17 @@ function sparseValues(
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
 export async function encodeOutboxCommit(
   schema: CompiledClientSchema,
   commit: OutboxCommit,
   encryption?: EncryptionConfig,
+  storedKeyIdFor?: (
+    table: CompiledClientTable,
+    rowId: string,
+  ) => string | undefined,
 ): Promise<PushCommitFrame> {
   const operations: PushOperation[] = [];
   for (const op of commit.operations) {
@@ -274,7 +279,13 @@ export async function encodeOutboxCommit(
     if (encryption !== undefined && table.hasEncryptedColumns) {
       // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
       const { encryptRowValues } = await import('./encryption');
-      values = await encryptRowValues(encryption, table, op.rowId, values);
+      values = await encryptRowValues(
+        encryption,
+        table,
+        op.rowId,
+        values,
+        storedKeyIdFor?.(table, op.rowId),
+      );
     }
     operations.push({
       table: op.table,

package/src/reactive-store.ts

@@ -196,15 +196,21 @@ function batchMatches<Row>(
   spec: ReactiveQuerySpec<Row>,
 ): boolean {
   for (const change of batch.tables) {
-    const dependency = spec.dependencies.find(
-      (candidate) => candidate.table === change.table,
-    );
-    if (dependency === undefined) continue;
-    if (dependency.scopeKeys === undefined || change.scopeKeys === undefined) {
-      return true;
-    }
-    for (const key of dependency.scopeKeys) {
-      if (change.scopeKeys.has(key)) return true;
+    // A composed spec carries one dependency per query branch. Every
+    // dependency on the changed table is consulted: a scoped dependency
+    // that does not cover the change must not mask a sibling dependency
+    // on the same table that does.
+    for (const dependency of spec.dependencies) {
+      if (dependency.table !== change.table) continue;
+      if (
+        dependency.scopeKeys === undefined ||
+        change.scopeKeys === undefined
+      ) {
+        return true;
+      }
+      for (const key of dependency.scopeKeys) {
+        if (change.scopeKeys.has(key)) return true;
+      }
     }
   }
   for (const change of batch.windows) {
@@ -389,14 +395,28 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
       this.#onAvailabilityChange();
       if (this.spec.claimCoverage !== false) {
         const claims: Promise<void>[] = [];
+        // A composed spec carries one coverage entry per query branch, and
+        // several branches can target the same base. One claim per distinct
+        // base covers the union of their units; a later entry for the same
+        // base does not replace the earlier one.
+        const unitsByBase = new Map<
+          string,
+          { base: WindowBase; units: Set<string> }
+        >();
         for (const coverage of this.spec.coverage ?? []) {
-          claims.push(
-            this.store.setWindowClaim(
-              this.#owner,
-              coverage.base,
-              coverage.units,
-            ),
-          );
+          const baseKey = windowBaseKey(coverage.base);
+          const existing = unitsByBase.get(baseKey);
+          if (existing === undefined) {
+            unitsByBase.set(baseKey, {
+              base: coverage.base,
+              units: new Set(coverage.units),
+            });
+          } else {
+            for (const unit of coverage.units) existing.units.add(unit);
+          }
+        }
+        for (const { base, units } of unitsByBase.values()) {
+          claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
         }
         const generation = this.#generation;
         this.#claimPending = claims.length > 0;

package/src/schema.ts

@@ -121,6 +121,21 @@ export function compileClientSchema(
         `table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`,
       );
     }
+    // §2.4 primary-key eligibility: a primary key MUST render to a `rowId`
+    // string every implementation produces identically and local storage
+    // resolves without deferring to a SQLite build.
+    const primaryKeyColumn = table.columns[primaryKeyIndex];
+    if (
+      primaryKeyColumn !== undefined &&
+      primaryKeyColumn.type !== 'string' &&
+      primaryKeyColumn.type !== 'integer' &&
+      primaryKeyColumn.type !== 'boolean' &&
+      primaryKeyColumn.type !== 'json'
+    ) {
+      throw new Error(
+        `table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} has an ineligible column type (§2.4); a primary key must be string, integer, boolean, or json`,
+      );
+    }
     if (table.scopes.length === 0) {
       throw new Error(
         `table ${table.name}: every synced table declares at least one scope pattern (§3.1)`,