@syncular/client 0.21.1 → 0.22.0

package/dist/client.js

@@ -1413,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) {
@@ -1430,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`);

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.1",
+  "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.1"
+    "@syncular/core": "0.22.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.21.1",
+    "@syncular/server": "0.22.0",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -2153,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) {
@@ -2177,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(

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)`,