@syncular/client 0.20.1 → 0.21.0

package/README.md

@@ -321,10 +321,10 @@ they are never encoded on the wire or exposed through pending commits, outcome
 envelopes, diagnostics, preferences, or telemetry.
 
 Use `patch(table, rowId, partial, { baseVersion? })` for editor-style partial
-updates. The wire still carries a full row, but the durable local operation
-records a sorted `changedFields` list so conflict and rejection UI knows which
-fields the user intended to touch. That intent is local-only and never enters
-`PUSH_COMMIT`; full-row `mutate` operations omit it.
+updates. The wire carries a sparse operation: the primary key plus the supplied
+columns are present, and the durable local operation keeps the same presence
+set so conflict and rejection UI knows which columns the user touched. A
+full-row `mutate` marks every column present.
 
 ## Application-authorized local security purge
 

package/dist/client.d.ts

@@ -415,12 +415,12 @@ export declare class SyncClient {
     /** Host-facing mutation result with explicit network work intent (§7.5). */
     mutateCommand(mutations: readonly MutationInput[]): CommandResult<string>;
     /**
-     * Partial-update convenience over the §6.1 full-row wire: read the
-     * current LOCAL row, merge `partial` over it, and record one full-row
-     * upsert through `mutate()`. `partial` keys follow the same two-casing
-     * rule as mutation values (snake_case or camelCase). The row must be
-     * locally present (subscribed/windowed-in); patching an absent row is
-     * an error — there is no base to merge into.
+     * Partial update over the §6.1 sparse wire: record one upsert whose
+     * presence set is the primary key plus the supplied non-scope columns.
+     * `partial` keys follow the same two-casing rule as mutation values
+     * (snake_case or camelCase). Absent columns keep their stored value on
+     * the server and in the local overlay; when the local row is absent the
+     * overlay leaves it absent (§7.1) and the server answers per §5.2.
      */
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;

package/dist/client.js

@@ -22,7 +22,7 @@ import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, }
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
-import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
+import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
 /** Stable client-local error while protected operations are preflight-gated. */
@@ -1390,10 +1390,10 @@ export class SyncClient {
     mutate(mutations) {
         return this.#recordMutations(mutations);
     }
-    #recordMutations(mutations, changedFieldsByIndex = []) {
+    #recordMutations(mutations, partial = false) {
         this.#requireActive();
         const clientCommitId = crypto.randomUUID();
-        const operations = mutations.map((mutation, index) => {
+        const operations = mutations.map((mutation) => {
             const table = this.#table(mutation.table);
             if (mutation.op === 'delete') {
                 return {
@@ -1405,6 +1405,45 @@ export class SyncClient {
                         : {}),
                 };
             }
+            if (partial) {
+                // §6.7 patch: the values map IS the presence set — the primary key
+                // plus the supplied non-scope columns. Absent columns keep their
+                // stored value; the overlay and the server both apply only the
+                // present ones.
+                const normalized = normalizeRecordKeys(table, mutation.values);
+                const scopeColumns = new Set(table.scopeColumnByVariable.values());
+                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)`);
+                    }
+                    const value = normalized.get(column.name);
+                    if (value === undefined || value === null) {
+                        if (!column.nullable) {
+                            throw new ClientSyncError('sync.invalid_request', `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`);
+                        }
+                        json[column.name] = null;
+                        continue;
+                    }
+                    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`);
+                }
+                return {
+                    table: mutation.table,
+                    rowId: pkValue,
+                    op: 'upsert',
+                    ...(mutation.baseVersion !== undefined
+                        ? { baseVersion: mutation.baseVersion }
+                        : {}),
+                    values: json,
+                };
+            }
             const values = recordToRowValues(table, mutation.values);
             const pkValue = values[table.primaryKeyIndex];
             if (typeof pkValue !== 'string' || pkValue.length === 0) {
@@ -1422,9 +1461,6 @@ export class SyncClient {
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
                 values: json,
-                ...(changedFieldsByIndex[index] !== undefined
-                    ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
-                    : {}),
             };
         });
         this.#applyBatch((batch) => {
@@ -1471,40 +1507,35 @@ export class SyncClient {
         };
     }
     /**
-     * Partial-update convenience over the §6.1 full-row wire: read the
-     * current LOCAL row, merge `partial` over it, and record one full-row
-     * upsert through `mutate()`. `partial` keys follow the same two-casing
-     * rule as mutation values (snake_case or camelCase). The row must be
-     * locally present (subscribed/windowed-in); patching an absent row is
-     * an error — there is no base to merge into.
+     * Partial update over the §6.1 sparse wire: record one upsert whose
+     * presence set is the primary key plus the supplied non-scope columns.
+     * `partial` keys follow the same two-casing rule as mutation values
+     * (snake_case or camelCase). Absent columns keep their stored value on
+     * the server and in the local overlay; when the local row is absent the
+     * overlay leaves it absent (§7.1) and the server answers per §5.2.
      */
     patch(table, rowId, partial, options) {
         this.#requireActive();
         const compiled = this.#table(table);
         const pkColumn = compiled.columns[compiled.primaryKeyIndex];
-        const rows = this.#db.query(`SELECT * FROM ${quoteIdent(compiled.name)} WHERE ${quoteIdent(pkColumn.name)} = ?`, [rowId]);
-        const row = rows[0];
-        if (row === undefined) {
-            throw new ClientSyncError('sync.invalid_request', `table ${compiled.name}: no local row with primary key ${JSON.stringify(rowId)} to patch`);
-        }
-        const record = {};
-        for (const column of compiled.columns) {
-            record[column.name] = fromSqlValue(column, row[column.name] ?? null);
-        }
-        const normalizedPartial = normalizeRecordKeys(compiled, partial);
-        for (const [name, value] of normalizedPartial) {
-            record[name] = value;
+        const normalized = normalizeRecordKeys(compiled, partial);
+        const pkOverride = normalized.get(pkColumn.name);
+        if (pkOverride !== undefined && pkOverride !== rowId) {
+            throw new ClientSyncError('sync.invalid_request', `table ${compiled.name}: patch cannot change the primary key`);
         }
         return this.#recordMutations([
             {
                 table,
                 op: 'upsert',
-                values: record,
+                values: {
+                    ...Object.fromEntries(normalized),
+                    [pkColumn.name]: rowId,
+                },
                 ...(options?.baseVersion !== undefined
                     ? { baseVersion: options.baseVersion }
                     : {}),
             },
-        ], [[...normalizedPartial.keys()].sort()]);
+        ], true);
     }
     /**
      * Apply one host-authorized local security purge. The host must stop/gate
@@ -2688,6 +2719,7 @@ export class SyncClient {
                     message: result.message,
                     serverVersion: result.serverVersion,
                     serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
+                    conflictColumns: this.#decodeConflictColumns(operation?.table, result.conflictColumns),
                     ...(operation !== undefined ? { operation } : {}),
                 };
                 this.#conflicts.push(conflict);
@@ -2750,6 +2782,25 @@ export class SyncClient {
         });
         return record;
     }
+    /**
+     * §6.3 `conflictColumns`: decode the presence-layout bitmap into the names
+     * of the present columns whose `column_version` exceeded `baseVersion`. A
+     * custom merge recomputes exactly these columns (§6.5).
+     */
+    #decodeConflictColumns(tableName, bitmap) {
+        if (tableName === undefined)
+            return [];
+        const table = this.#schema.tables.get(tableName);
+        if (table === undefined)
+            return [];
+        const names = [];
+        table.columns.forEach((column, index) => {
+            const byte = bitmap[index >> 3] ?? 0;
+            if (((byte >> (index & 7)) & 1) === 1)
+                names.push(column.name);
+        });
+        return names;
+    }
     async #applyCommit(frame, summary) {
         await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
             this.#recordCommitChanges(batch, frame);
@@ -3146,9 +3197,25 @@ export class SyncClient {
                 deleteLocalRow(this.#db, table, op.rowId);
                 continue;
             }
+            // §7.1 overlay: apply the operation's PRESENT columns over the current
+            // local row. A partial operation over an absent local row leaves it
+            // absent — the server answers it with sync.row_deleted or
+            // 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];
+            if (local === undefined && !full) {
+                if (batch !== undefined && !precise)
+                    batch.table(op.table);
+                continue;
+            }
             const values = table.columns.map((column) => {
-                const value = op.values?.[column.name];
-                return value === undefined ? null : jsonToRowValue(value);
+                const value = opValues[column.name];
+                if (value !== undefined)
+                    return jsonToRowValue(value);
+                return local === undefined
+                    ? null
+                    : fromSqlValue(column, local[column.name] ?? null);
             });
             // Record the row's scope keys from its scope columns (I2 refinement).
             if (batch !== undefined) {
@@ -3164,8 +3231,9 @@ export class SyncClient {
                 if (!precise)
                     batch.table(table.name);
             }
-            const existing = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [op.rowId])[0];
-            const version = existing === undefined ? OPTIMISTIC_VERSION : existing.v;
+            const version = local === undefined
+                ? OPTIMISTIC_VERSION
+                : local[SYNC_VERSION_COLUMN];
             upsertLocalRow(this.#db, table, values, version);
         }
     }

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(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly RowValue[]): Promise<RowValue[]>;
+export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[]): 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

@@ -72,7 +72,9 @@ export async function encryptRowValues(config, table, rowId, values) {
     if (!table.hasEncryptedColumns)
         return values.slice();
     const out = values.slice();
-    const keyId = encryptionKeyId(config, table, rowId, values);
+    // 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));
     for (let i = 0; i < table.columns.length; i++) {
         const column = table.columns[i];
         if (column === undefined || !column.encrypted)
@@ -84,7 +86,7 @@ export async function encryptRowValues(config, table, rowId, values) {
         if (key === undefined) {
             throw new DecryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);
         }
-        out[i] = await encryptValue(declaredTypeOf(column), value, keyId, key, config.nonceSource);
+        out[i] = (await encryptValue(declaredTypeOf(column), value, keyId, key, config.nonceSource));
     }
     return out;
 }

package/dist/outbox.d.ts

@@ -16,13 +16,13 @@ export interface OutboxOperation {
     readonly op: 'upsert' | 'delete';
     /** Optimistic-concurrency token (§6.2); absent = last-write-wins. */
     readonly baseVersion?: number;
-    /** Full-row values keyed by column name; present iff `op` is `upsert`. */
-    readonly values?: Readonly<Record<string, JsonRowValue>>;
     /**
-     * Local-only normalized columns intentionally supplied to `patch()`.
-     * Absent for full-row mutate/upsert because intent is then unknown.
+     * The PRESENT columns keyed by column name; present iff `op` is `upsert`.
+     * A key the operation writes carries its value; a column the operation
+     * leaves unchanged has no key (§6.1 sparse rows, §7.2.1: intent is the
+     * presence set — `mutate` marks every column, `patch` the supplied ones).
      */
-    readonly changedFields?: readonly string[];
+    readonly values?: Readonly<Record<string, JsonRowValue>>;
 }
 export interface OutboxCommit {
     readonly seq: number;

package/dist/outbox.js

@@ -5,7 +5,7 @@
  * request is built — a commit recorded under schema N replays after an
  * upgrade to N+1 by re-encoding.
  */
-import { encodeRow, } from '@syncular/core';
+import { encodeSparseRow, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
 import { jsonToRowValue, } from './schema.js';
 export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
@@ -114,7 +114,7 @@ export class OutboxEncodeError extends ClientSyncError {
         super('sync.outbox_incompatible', message, false);
     }
 }
-function orderedValues(table, values) {
+function sparseValues(table, values) {
     // Any persisted key that is not a column of the CURRENT schema means the
     // bump removed (or renamed) it — the commit cannot be expressed now.
     for (const key of Object.keys(values)) {
@@ -124,9 +124,7 @@ function orderedValues(table, values) {
     }
     return table.columns.map((column) => {
         const value = values[column.name];
-        if (value === undefined)
-            return null;
-        return jsonToRowValue(value);
+        return value === undefined ? undefined : jsonToRowValue(value);
     });
 }
 /**
@@ -158,7 +156,7 @@ export async function encodeOutboxCommit(schema, commit, encryption) {
         if (op.values === undefined) {
             throw new ClientSyncError('sync.invalid_request', `outbox upsert on ${op.table}/${op.rowId} has no values`);
         }
-        let values = orderedValues(table, op.values);
+        let values = sparseValues(table, op.values);
         if (encryption !== undefined && table.hasEncryptedColumns) {
             // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
             const { encryptRowValues } = await import('./encryption.js');
@@ -169,7 +167,7 @@ export async function encodeOutboxCommit(schema, commit, encryption) {
             rowId: op.rowId,
             op: 'upsert',
             ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
-            payload: encodeRow(table.columns, values),
+            payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
         });
     }
     return {

package/dist/outcomes.d.ts

@@ -19,6 +19,12 @@ export interface ConflictRecord {
     readonly serverVersion: number;
     /** The current server row, decoded — resolve without a round-trip. */
     readonly serverRow: Readonly<Record<string, RowValue>>;
+    /**
+     * §6.3: the present columns whose `column_version` exceeded the losing
+     * operation's `baseVersion`. A custom merge recomputes exactly these;
+     * keep-server and keep-local ignore them (§6.5).
+     */
+    readonly conflictColumns: readonly string[];
     /** The losing local operation (absent only for malformed op indexes). */
     readonly operation?: OutboxOperation;
 }

package/dist/outcomes.js

@@ -26,6 +26,8 @@ function decodeResults(raw) {
             status: 'conflict',
             conflict: {
                 ...result.conflict,
+                // Pre-column-version journal entries carry no conflictColumns.
+                conflictColumns: result.conflict.conflictColumns ?? [],
                 serverRow: Object.fromEntries(Object.entries(result.conflict.serverRow).map(([key, value]) => [
                     key,
                     jsonToRowValue(value),

package/dist/remote.js

@@ -2,7 +2,7 @@
  * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
  * through the existing push path without creating a local replica or outbox.
  */
-import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, } from '@syncular/core';
+import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
 import { encryptRowValues } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { compileClientSchema, recordToRowValues, } from './schema.js';
@@ -71,6 +71,7 @@ export class SyncRemoteClient {
     #operationSocketGeneration = 0;
     #watches = new Map();
     #encryption;
+    /** Pinned by config, or acquired on the first prepared commit (§2.1). */
     #logEpoch;
     constructor(config) {
         if (config.clientId.length === 0) {
@@ -101,6 +102,41 @@ export class SyncRemoteClient {
         if (input.mutations.length === 0) {
             throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
         }
+        let logEpoch = this.#logEpoch;
+        if (logEpoch === undefined) {
+            // §2.1: a push round binds to the partition log epoch; an acquisition
+            // round carries no push commits.
+            if (this.#transport === undefined) {
+                throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
+            }
+            const acquisition = decodeMessage(await this.#transport(encodeMessage({
+                wireVersion: PROTOCOL_WIRE_VERSION,
+                msgKind: 'request',
+                frames: [
+                    {
+                        type: 'REQ_HEADER',
+                        clientId: this.#clientId,
+                        schemaVersion: schema.version,
+                    },
+                    // A pull that asks for nothing: the round exists for its epoch.
+                    {
+                        type: 'PULL_HEADER',
+                        limitCommits: 0,
+                        limitSnapshotRows: 0,
+                        maxSnapshotPages: 0,
+                        accept: 0b0011,
+                    },
+                ],
+            })));
+            const acquisitionHeader = acquisition.frames[0];
+            if (acquisition.msgKind !== 'response' ||
+                acquisitionHeader?.type !== 'RESP_HEADER' ||
+                acquisitionHeader.logEpoch === undefined) {
+                throw new ClientSyncError('client.invalid_host_response', 'remote epoch acquisition returned an invalid response');
+            }
+            logEpoch = acquisitionHeader.logEpoch;
+            this.#logEpoch = logEpoch;
+        }
         const operations = [];
         for (const mutation of input.mutations) {
             const table = schema.tables.get(mutation.table);
@@ -136,22 +172,20 @@ export class SyncRemoteClient {
                 ...(mutation.baseVersion !== undefined
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
-                payload: encodeRow(table.columns, values),
+                payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
             });
         }
         return {
             requestId: input.requestId,
             bytes: encodeMessage({
-                wireVersion: this.#logEpoch === undefined ? 1 : 2,
+                wireVersion: PROTOCOL_WIRE_VERSION,
                 msgKind: 'request',
                 frames: [
                     {
                         type: 'REQ_HEADER',
                         clientId: this.#clientId,
                         schemaVersion: schema.version,
-                        ...(this.#logEpoch !== undefined
-                            ? { logEpoch: this.#logEpoch }
-                            : {}),
+                        logEpoch,
                     },
                     {
                         type: 'PUSH_COMMIT',

package/dist/schema.d.ts

@@ -138,6 +138,14 @@ export declare function fromSqlValue(column: RowColumn, value: SqlValue): RowVal
  * reserved `_sync_*` names); giving one column in both casings is an error.
  */
 export declare function normalizeRecordKeys(table: CompiledClientTable, record: Readonly<Record<string, unknown>>): Map<string, unknown>;
+/**
+ * Accept the local SQL representation of a value alongside the app-facing
+ * one, so a row read straight off the mirror (`SELECT *`) feeds back into
+ * `mutate()` without per-column fixups: SQLite stores booleans as 0/1 and
+ * may surface integers as bigint. Anything else passes through untouched —
+ * the codec still fails loud on genuine type garbage at encode time.
+ */
+export declare function coerceSqlRepresentation(column: RowColumn, value: unknown): unknown;
 /**
  * App-facing record → schema-ordered row values for the codec and the
  * local mirror. Missing keys become NULL; unknown keys fail loud (see

package/dist/schema.js

@@ -195,6 +195,9 @@ function sqlType(column) {
 /** §7.4.1 persisted local schema-version marker (`_syncular_meta` key). */
 export const LOCAL_SCHEMA_VERSION_KEY = 'localSchemaVersion';
 function createSyncedTable(db, table) {
+    // §6.11: a declared reference is deliberately NOT emitted here. Windowing
+    // evicts a parent independently of its children, so local SQLite never
+    // enforces a reference; the server enforces it.
     const columns = table.columns.map((column) => {
         const notNull = column.nullable ? '' : ' NOT NULL';
         const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
@@ -513,7 +516,7 @@ export function normalizeRecordKeys(table, record) {
  * may surface integers as bigint. Anything else passes through untouched —
  * the codec still fails loud on genuine type garbage at encode time.
  */
-function coerceSqlRepresentation(column, value) {
+export function coerceSqlRepresentation(column, value) {
     switch (localColumnType(column)) {
         case 'boolean':
             return value === 0 ? false : value === 1 ? true : value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.20.1",
+  "version": "0.21.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.20.1"
+    "@syncular/core": "0.21.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.20.1",
+    "@syncular/server": "0.21.0",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -158,6 +158,8 @@ import {
   ensureLocalBookkeepingSchema,
   ensureLocalSyncedSchema,
   fromSqlValue,
+  coerceSqlRepresentation,
+  type JsonRowValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
   normalizeRecordKeys,
@@ -2127,11 +2129,11 @@ export class SyncClient {
 
   #recordMutations(
     mutations: readonly MutationInput[],
-    changedFieldsByIndex: readonly (readonly string[] | undefined)[] = [],
+    partial = false,
   ): string {
     this.#requireActive();
     const clientCommitId = crypto.randomUUID();
-    const operations: OutboxOperation[] = mutations.map((mutation, index) => {
+    const operations: OutboxOperation[] = mutations.map((mutation) => {
       const table = this.#table(mutation.table);
       if (mutation.op === 'delete') {
         return {
@@ -2143,6 +2145,55 @@ export class SyncClient {
             : {}),
         };
       }
+      if (partial) {
+        // §6.7 patch: the values map IS the presence set — the primary key
+        // plus the supplied non-scope columns. Absent columns keep their
+        // stored value; the overlay and the server both apply only the
+        // present ones.
+        const normalized = normalizeRecordKeys(table, mutation.values);
+        const scopeColumns = new Set(table.scopeColumnByVariable.values());
+        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)`,
+            );
+          }
+          const value = normalized.get(column.name);
+          if (value === undefined || value === null) {
+            if (!column.nullable) {
+              throw new ClientSyncError(
+                'sync.invalid_request',
+                `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`,
+              );
+            }
+            json[column.name] = null;
+            continue;
+          }
+          json[column.name] = rowValueToJson(
+            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(
+            'sync.invalid_request',
+            `table ${table.name}: upsert requires a non-empty string primary key`,
+          );
+        }
+        return {
+          table: mutation.table,
+          rowId: pkValue,
+          op: 'upsert',
+          ...(mutation.baseVersion !== undefined
+            ? { baseVersion: mutation.baseVersion }
+            : {}),
+          values: json,
+        };
+      }
       const values = recordToRowValues(table, mutation.values);
       const pkValue = values[table.primaryKeyIndex];
       if (typeof pkValue !== 'string' || pkValue.length === 0) {
@@ -2163,9 +2214,6 @@ export class SyncClient {
           ? { baseVersion: mutation.baseVersion }
           : {}),
         values: json,
-        ...(changedFieldsByIndex[index] !== undefined
-          ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
-          : {}),
       };
     });
     this.#applyBatch((batch) => {
@@ -2218,12 +2266,12 @@ export class SyncClient {
   }
 
   /**
-   * Partial-update convenience over the §6.1 full-row wire: read the
-   * current LOCAL row, merge `partial` over it, and record one full-row
-   * upsert through `mutate()`. `partial` keys follow the same two-casing
-   * rule as mutation values (snake_case or camelCase). The row must be
-   * locally present (subscribed/windowed-in); patching an absent row is
-   * an error — there is no base to merge into.
+   * Partial update over the §6.1 sparse wire: record one upsert whose
+   * presence set is the primary key plus the supplied non-scope columns.
+   * `partial` keys follow the same two-casing rule as mutation values
+   * (snake_case or camelCase). Absent columns keep their stored value on
+   * the server and in the local overlay; when the local row is absent the
+   * overlay leaves it absent (§7.1) and the server answers per §5.2.
    */
   patch(
     table: string,
@@ -2234,37 +2282,29 @@ export class SyncClient {
     this.#requireActive();
     const compiled = this.#table(table);
     const pkColumn = compiled.columns[compiled.primaryKeyIndex] as RowColumn;
-    const rows = this.#db.query(
-      `SELECT * FROM ${quoteIdent(compiled.name)} WHERE ${quoteIdent(pkColumn.name)} = ?`,
-      [rowId],
-    );
-    const row = rows[0];
-    if (row === undefined) {
+    const normalized = normalizeRecordKeys(compiled, partial);
+    const pkOverride = normalized.get(pkColumn.name);
+    if (pkOverride !== undefined && pkOverride !== rowId) {
       throw new ClientSyncError(
         'sync.invalid_request',
-        `table ${compiled.name}: no local row with primary key ${JSON.stringify(rowId)} to patch`,
+        `table ${compiled.name}: patch cannot change the primary key`,
       );
     }
-    const record: Record<string, unknown> = {};
-    for (const column of compiled.columns as readonly RowColumn[]) {
-      record[column.name] = fromSqlValue(column, row[column.name] ?? null);
-    }
-    const normalizedPartial = normalizeRecordKeys(compiled, partial);
-    for (const [name, value] of normalizedPartial) {
-      record[name] = value;
-    }
     return this.#recordMutations(
       [
         {
           table,
           op: 'upsert',
-          values: record,
+          values: {
+            ...Object.fromEntries(normalized),
+            [pkColumn.name]: rowId,
+          },
           ...(options?.baseVersion !== undefined
             ? { baseVersion: options.baseVersion }
             : {}),
         },
       ],
-      [[...normalizedPartial.keys()].sort()],
+      true,
     );
   }
 
@@ -3735,6 +3775,10 @@ export class SyncClient {
           message: result.message,
           serverVersion: result.serverVersion,
           serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
+          conflictColumns: this.#decodeConflictColumns(
+            operation?.table,
+            result.conflictColumns,
+          ),
           ...(operation !== undefined ? { operation } : {}),
         };
         this.#conflicts.push(conflict);
@@ -3804,6 +3848,26 @@ export class SyncClient {
     return record;
   }
 
+  /**
+   * §6.3 `conflictColumns`: decode the presence-layout bitmap into the names
+   * of the present columns whose `column_version` exceeded `baseVersion`. A
+   * custom merge recomputes exactly these columns (§6.5).
+   */
+  #decodeConflictColumns(
+    tableName: string | undefined,
+    bitmap: Uint8Array,
+  ): readonly string[] {
+    if (tableName === undefined) return [];
+    const table = this.#schema.tables.get(tableName);
+    if (table === undefined) return [];
+    const names: string[] = [];
+    table.columns.forEach((column, index) => {
+      const byte = bitmap[index >> 3] ?? 0;
+      if (((byte >> (index & 7)) & 1) === 1) names.push(column.name);
+    });
+    return names;
+  }
+
   async #applyCommit(
     frame: CommitFrame,
     summary: MutableSummary,
@@ -4318,9 +4382,26 @@ export class SyncClient {
         deleteLocalRow(this.#db, table, op.rowId);
         continue;
       }
+      // §7.1 overlay: apply the operation's PRESENT columns over the current
+      // local row. A partial operation over an absent local row leaves it
+      // absent — the server answers it with sync.row_deleted or
+      // 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];
+      if (local === undefined && !full) {
+        if (batch !== undefined && !precise) batch.table(op.table);
+        continue;
+      }
       const values = table.columns.map((column) => {
-        const value = op.values?.[column.name];
-        return value === undefined ? null : jsonToRowValue(value);
+        const value = opValues[column.name];
+        if (value !== undefined) return jsonToRowValue(value);
+        return local === undefined
+          ? null
+          : fromSqlValue(column, local[column.name] ?? null);
       });
       // Record the row's scope keys from its scope columns (I2 refinement).
       if (batch !== undefined) {
@@ -4335,12 +4416,10 @@ export class SyncClient {
         }
         if (!precise) batch.table(table.name);
       }
-      const existing = this.#db.query(
-        `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
-        [op.rowId],
-      )[0];
       const version =
-        existing === undefined ? OPTIMISTIC_VERSION : (existing.v as number);
+        local === undefined
+          ? OPTIMISTIC_VERSION
+          : (local[SYNC_VERSION_COLUMN] as number);
       upsertLocalRow(this.#db, table, values, version);
     }
   }

package/src/encryption.ts

@@ -142,15 +142,22 @@ function declaredTypeOf(column: RowColumn): DeclaredType {
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
  * unencrypted (§5.11).
  */
-export async function encryptRowValues(
+export async function encryptRowValues<T extends RowValue | undefined>(
   config: EncryptionConfig,
   table: CompiledClientTable,
   rowId: string,
-  values: readonly RowValue[],
-): Promise<RowValue[]> {
+  values: readonly T[],
+): Promise<T[]> {
   if (!table.hasEncryptedColumns) return values.slice();
   const out = values.slice();
-  const keyId = encryptionKeyId(config, table, rowId, values);
+  // 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),
+  );
   for (let i = 0; i < table.columns.length; i++) {
     const column = table.columns[i];
     if (column === undefined || !column.encrypted) continue;
@@ -162,13 +169,13 @@ export async function encryptRowValues(
         `no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`,
       );
     }
-    out[i] = await encryptValue(
+    out[i] = (await encryptValue(
       declaredTypeOf(column),
       value as PlainValue,
       keyId,
       key,
       config.nonceSource,
-    );
+    )) as T;
   }
   return out;
 }

package/src/outbox.ts

@@ -6,10 +6,11 @@
  * upgrade to N+1 by re-encoding.
  */
 import {
-  encodeRow,
+  encodeSparseRow,
   type PushCommitFrame,
   type PushOperation,
   type ScopeMap,
+  type SparseRowValue,
 } from '@syncular/core';
 import type { ClientDatabase, SqlRow } from './database';
 import type { EncryptionConfig } from './encryption';
@@ -27,13 +28,13 @@ export interface OutboxOperation {
   readonly op: 'upsert' | 'delete';
   /** Optimistic-concurrency token (§6.2); absent = last-write-wins. */
   readonly baseVersion?: number;
-  /** Full-row values keyed by column name; present iff `op` is `upsert`. */
-  readonly values?: Readonly<Record<string, JsonRowValue>>;
   /**
-   * Local-only normalized columns intentionally supplied to `patch()`.
-   * Absent for full-row mutate/upsert because intent is then unknown.
+   * The PRESENT columns keyed by column name; present iff `op` is `upsert`.
+   * A key the operation writes carries its value; a column the operation
+   * leaves unchanged has no key (§6.1 sparse rows, §7.2.1: intent is the
+   * presence set — `mutate` marks every column, `patch` the supplied ones).
    */
-  readonly changedFields?: readonly string[];
+  readonly values?: Readonly<Record<string, JsonRowValue>>;
 }
 
 export interface OutboxCommit {
@@ -212,10 +213,10 @@ export class OutboxEncodeError extends ClientSyncError {
   }
 }
 
-function orderedValues(
+function sparseValues(
   table: CompiledClientTable,
   values: Readonly<Record<string, JsonRowValue>>,
-) {
+): SparseRowValue[] {
   // Any persisted key that is not a column of the CURRENT schema means the
   // bump removed (or renamed) it — the commit cannot be expressed now.
   for (const key of Object.keys(values)) {
@@ -227,8 +228,7 @@ function orderedValues(
   }
   return table.columns.map((column) => {
     const value = values[column.name];
-    if (value === undefined) return null;
-    return jsonToRowValue(value);
+    return value === undefined ? undefined : jsonToRowValue(value);
   });
 }
 
@@ -270,7 +270,7 @@ export async function encodeOutboxCommit(
         `outbox upsert on ${op.table}/${op.rowId} has no values`,
       );
     }
-    let values = orderedValues(table, op.values);
+    let values = sparseValues(table, op.values);
     if (encryption !== undefined && table.hasEncryptedColumns) {
       // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
       const { encryptRowValues } = await import('./encryption');
@@ -281,7 +281,7 @@ export async function encodeOutboxCommit(
       rowId: op.rowId,
       op: 'upsert',
       ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
-      payload: encodeRow(table.columns, values),
+      payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
     });
   }
   return {

package/src/outcomes.ts

@@ -22,6 +22,12 @@ export interface ConflictRecord {
   readonly serverVersion: number;
   /** The current server row, decoded — resolve without a round-trip. */
   readonly serverRow: Readonly<Record<string, RowValue>>;
+  /**
+   * §6.3: the present columns whose `column_version` exceeded the losing
+   * operation's `baseVersion`. A custom merge recomputes exactly these;
+   * keep-server and keep-local ignore them (§6.5).
+   */
+  readonly conflictColumns: readonly string[];
   /** The losing local operation (absent only for malformed op indexes). */
   readonly operation?: OutboxOperation;
 }
@@ -94,8 +100,13 @@ export interface ResolveCommitOutcomeInput {
   readonly replacementClientCommitId?: string;
 }
 
-interface StoredConflictRecord extends Omit<ConflictRecord, 'serverRow'> {
+interface StoredConflictRecord extends Omit<
+  ConflictRecord,
+  'serverRow' | 'conflictColumns'
+> {
   readonly serverRow: Readonly<Record<string, JsonRowValue>>;
+  /** Absent in journal entries written before wire version 3. */
+  readonly conflictColumns?: readonly string[];
 }
 
 type StoredCommitOperationOutcome =
@@ -130,6 +141,8 @@ function decodeResults(raw: string): CommitOperationOutcome[] {
       status: 'conflict',
       conflict: {
         ...result.conflict,
+        // Pre-column-version journal entries carry no conflictColumns.
+        conflictColumns: result.conflict.conflictColumns ?? [],
         serverRow: Object.fromEntries(
           Object.entries(result.conflict.serverRow).map(([key, value]) => [
             key,

package/src/remote.ts

@@ -9,7 +9,8 @@ import {
   encodeMessage,
   encodeRemoteOperationRequest,
   encodeRemoteOperationRealtimeMessage,
-  encodeRow,
+  encodeSparseRow,
+  PROTOCOL_WIRE_VERSION,
   type PushOperation,
   type PushOperationResult,
   type PushResultDetailsFrame,
@@ -204,7 +205,8 @@ export class SyncRemoteClient {
     }
   >();
   readonly #encryption: EncryptionConfig | undefined;
-  readonly #logEpoch: string | undefined;
+  /** Pinned by config, or acquired on the first prepared commit (§2.1). */
+  #logEpoch: string | undefined;
 
   constructor(config: SyncRemoteClientConfig) {
     if (config.clientId.length === 0) {
@@ -242,6 +244,53 @@ export class SyncRemoteClient {
         'a remote commit must carry at least one mutation (§6.1)',
       );
     }
+    let logEpoch = this.#logEpoch;
+    if (logEpoch === undefined) {
+      // §2.1: a push round binds to the partition log epoch; an acquisition
+      // round carries no push commits.
+      if (this.#transport === undefined) {
+        throw new ClientSyncError(
+          'client.remote_sync_unconfigured',
+          'SyncRemoteClient has no sync transport for ordinary commits',
+        );
+      }
+      const acquisition = decodeMessage(
+        await this.#transport(
+          encodeMessage({
+            wireVersion: PROTOCOL_WIRE_VERSION,
+            msgKind: 'request',
+            frames: [
+              {
+                type: 'REQ_HEADER',
+                clientId: this.#clientId,
+                schemaVersion: schema.version,
+              },
+              // A pull that asks for nothing: the round exists for its epoch.
+              {
+                type: 'PULL_HEADER',
+                limitCommits: 0,
+                limitSnapshotRows: 0,
+                maxSnapshotPages: 0,
+                accept: 0b0011,
+              },
+            ],
+          }),
+        ),
+      );
+      const acquisitionHeader = acquisition.frames[0];
+      if (
+        acquisition.msgKind !== 'response' ||
+        acquisitionHeader?.type !== 'RESP_HEADER' ||
+        acquisitionHeader.logEpoch === undefined
+      ) {
+        throw new ClientSyncError(
+          'client.invalid_host_response',
+          'remote epoch acquisition returned an invalid response',
+        );
+      }
+      logEpoch = acquisitionHeader.logEpoch;
+      this.#logEpoch = logEpoch;
+    }
     const operations: PushOperation[] = [];
     for (const mutation of input.mutations) {
       const table = schema.tables.get(mutation.table);
@@ -277,22 +326,20 @@ export class SyncRemoteClient {
         ...(mutation.baseVersion !== undefined
           ? { baseVersion: mutation.baseVersion }
           : {}),
-        payload: encodeRow(table.columns, values),
+        payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
       });
     }
     return {
       requestId: input.requestId,
       bytes: encodeMessage({
-        wireVersion: this.#logEpoch === undefined ? 1 : 2,
+        wireVersion: PROTOCOL_WIRE_VERSION,
         msgKind: 'request',
         frames: [
           {
             type: 'REQ_HEADER',
             clientId: this.#clientId,
             schemaVersion: schema.version,
-            ...(this.#logEpoch !== undefined
-              ? { logEpoch: this.#logEpoch }
-              : {}),
+            logEpoch,
           },
           {
             type: 'PUSH_COMMIT',

package/src/schema.ts

@@ -318,6 +318,9 @@ function createSyncedTable(
   db: ClientDatabase,
   table: CompiledClientTable,
 ): void {
+  // §6.11: a declared reference is deliberately NOT emitted here. Windowing
+  // evicts a parent independently of its children, so local SQLite never
+  // enforces a reference; the server enforces it.
   const columns = table.columns.map((column) => {
     const notNull = column.nullable ? '' : ' NOT NULL';
     const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
@@ -716,7 +719,10 @@ export function normalizeRecordKeys(
  * may surface integers as bigint. Anything else passes through untouched —
  * the codec still fails loud on genuine type garbage at encode time.
  */
-function coerceSqlRepresentation(column: RowColumn, value: unknown): unknown {
+export function coerceSqlRepresentation(
+  column: RowColumn,
+  value: unknown,
+): unknown {
   switch (localColumnType(column)) {
     case 'boolean':
       return value === 0 ? false : value === 1 ? true : value;