@syncular/client 0.20.1 → 0.21.1

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

@@ -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';
@@ -22,7 +23,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 +1391,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 +1406,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 +1462,6 @@ export class SyncClient {
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
                 values: json,
-                ...(changedFieldsByIndex[index] !== undefined
-                    ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
-                    : {}),
             };
         });
         this.#applyBatch((batch) => {
@@ -1471,40 +1508,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
@@ -1776,8 +1808,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;
             }
@@ -1786,6 +1830,10 @@ export class SyncClient {
                     this.#dropIncompatibleCommit(commit, error.message);
                     continue;
                 }
+                if (error instanceof EncryptError) {
+                    this.#dropIncompatibleCommit(commit, error.message, error.code);
+                    continue;
+                }
                 throw error;
             }
         }
@@ -1795,14 +1843,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
@@ -2688,6 +2737,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 +2800,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 +3215,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 +3249,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[], 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,11 +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();
-    const keyId = encryptionKeyId(config, table, rowId, values);
+    // 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)
@@ -82,9 +109,9 @@ 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);
+        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;
@@ -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

@@ -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);
     });
 }
 /**
@@ -134,9 +132,10 @@ function orderedValues(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') {
@@ -158,18 +157,18 @@ 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');
-            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,
             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;