@syncular/client 0.20.0 → 0.21.0

package/src/client.ts

@@ -44,6 +44,7 @@ import {
   deleteLocalRow,
   deleteScopedRows,
   evictScopedRows,
+  yieldToHost,
   upsertLocalRow,
 } from './apply';
 import {
@@ -157,6 +158,8 @@ import {
   ensureLocalBookkeepingSchema,
   ensureLocalSyncedSchema,
   fromSqlValue,
+  coerceSqlRepresentation,
+  type JsonRowValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
   normalizeRecordKeys,
@@ -286,8 +289,8 @@ export interface SyncClientLimits {
   readonly maxSnapshotPages?: number;
   /**
    * §4.2 accept bitmask; defaults to inline + external rows (0b0011)
-   * plus sqlite images (bit 2) when the database backend implements
-   * `withSqliteImage` and a segment downloader is configured (§5.3).
+   * plus SQLite images and signed URLs when supported. Both image chunks
+   * and rows blocks commit before yielding to local reads (§7.7).
    */
   readonly accept?: number;
   /**
@@ -748,6 +751,7 @@ export class SyncClient {
     const startupWork =
       this.#schemaFloor === undefined &&
       (countOutbox(this.#db) > 0 ||
+        loadPendingEvictions(this.#db).length > 0 ||
         subscriptions.some((sub) => sub.status === 'active'));
     if (startupWork && this.#securityLifecycle === 'active') {
       this.#needsPull = true;
@@ -1820,23 +1824,17 @@ export class SyncClient {
     socket.send(encodePresencePublish(scopeKey, doc));
   }
 
-  /**
-   * §4.2 accept mask: the configured override, or the rows baseline plus
-   * bit 2 when the backend can import sqlite images (§5.3) and a segment
-   * downloader exists (sqlite segments are never inline, §5.7), plus
-   * bit 3 when the downloader exposes a direct URL fetch (§5.4
-   * capability negotiation).
-   */
+  /** Advertise supported segment formats; all imports yield between commits. */
   #acceptMask(): number {
     const configured = this.#config.limits?.accept;
     if (configured !== undefined) return configured;
     const segments = this.#config.segments;
-    const sqliteCapable =
-      typeof this.#db.withSqliteImage === 'function' && segments !== undefined;
     const urlCapable = typeof segments?.fetchUrl === 'function';
     return (
       ACCEPT_ROWS_BASELINE |
-      (sqliteCapable ? ACCEPT_SQLITE : 0) |
+      (typeof this.#db.withSqliteImage === 'function' && segments !== undefined
+        ? ACCEPT_SQLITE
+        : 0) |
       (urlCapable ? ACCEPT_SIGNED_URLS : 0)
     );
   }
@@ -1909,8 +1907,8 @@ export class SyncClient {
    * Set the live window units for a base (§4.8): a value-sharded family of
    * subscriptions, one per unit. Computes the diff against the registry —
    * added units get fresh subscriptions (image-lane bootstrap on the next
-   * sync); removed units are unsubscribed and evicted, fused in one local
-   * transaction (E1–E4). Idempotent: calling with the same units is a
+   * sync); removed units are unsubscribed with their first eviction chunk
+   * in one local transaction (E1–E4). Idempotent: calling with the same units is a
    * no-op. Re-entry (a unit removed then re-added) cancels any deferred
    * eviction and fresh-bootstraps.
    *
@@ -1975,7 +1973,7 @@ export class SyncClient {
       // Shrink: units live but not wanted → unsubscribe fused with eviction.
       for (const { unit, subId } of live) {
         if (wanted.has(unit)) continue;
-        this.#evictUnit(baseKey, base, unit, subId);
+        await this.#evictUnit(baseKey, base, unit, subId);
         changed = true;
       }
     });
@@ -2018,8 +2016,8 @@ export class SyncClient {
   }
 
   /**
-   * §4.8 E1–E4: evict one departing unit, fused with its unsubscription in
-   * one transaction. Deletes the unit's rows EXCEPT those pinned by a
+   * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
+   * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
    * pending outbox commit (E1); if any pin remains, records a deferred
    * eviction retried on the next outbox drain. Discards the subscription's
    * cursor/resume/effective-echo (E3) and its version state with the rows
@@ -2027,24 +2025,26 @@ export class SyncClient {
    * with no local scope-column mapping, surfaces a configuration error and
    * evicts nothing (§4.8/§3.3).
    */
-  #evictUnit(
+  async #evictUnit(
     baseKey: string,
     base: WindowBase,
     unit: string,
     subId: string,
-  ): void {
+  ): Promise<void> {
     const table = this.#table(base.table);
     const sub = getSubscription(this.#db, subId);
     // The rows a unit holds live under its LAST effective scopes if it ever
     // synced; before first sync, the requested unit scopes are the match.
     const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
     const pinned = this.#pinnedRowIds(base.table);
+    let remaining = false;
     this.#applyBatch((batch) => {
       this.#db.transaction(() => {
-        const deferred = evictScopedRows(this.#db, table, effective, pinned);
+        const result = evictScopedRows(this.#db, table, effective, pinned);
+        remaining = result.remaining;
         deleteWindowUnit(this.#db, baseKey, unit);
         deleteSubscription(this.#db, subId);
-        if (deferred) {
+        if (result.deferred) {
           savePendingEviction(this.#db, subId, base.table, effective);
         } else {
           deletePendingEviction(this.#db, subId);
@@ -2055,6 +2055,10 @@ export class SyncClient {
       this.#needsPull = true;
       batch.status();
     });
+    if (remaining) {
+      await yieldToHost();
+      await this.#drainPendingEvictions();
+    }
   }
 
   /**
@@ -2062,7 +2066,7 @@ export class SyncClient {
    * unit's rows are removed once no pending commit references them; a unit
    * that re-entered the window in the meantime has no pending record left.
    */
-  #drainPendingEvictions(): void {
+  async #drainPendingEvictions(): Promise<void> {
     const pending = loadPendingEvictions(this.#db);
     if (pending.length === 0) return;
     for (const entry of pending) {
@@ -2071,15 +2075,30 @@ export class SyncClient {
         deletePendingEviction(this.#db, entry.subId);
         continue;
       }
-      const pinned = this.#pinnedRowIds(entry.table);
-      this.#applyBatch((batch) => {
-        let deferred = false;
-        this.#db.transaction(() => {
-          deferred = evictScopedRows(this.#db, table, entry.effective, pinned);
-          if (!deferred) deletePendingEviction(this.#db, entry.subId);
+      let remaining: boolean;
+      do {
+        if (
+          !loadPendingEvictions(this.#db).some(
+            (item) => item.subId === entry.subId,
+          )
+        )
+          break;
+        // Local writes may add pins while the worker yields between chunks.
+        const pinned = this.#pinnedRowIds(entry.table);
+        remaining = false;
+        this.#applyBatch((batch) => {
+          const result = evictScopedRows(
+            this.#db,
+            table,
+            entry.effective,
+            pinned,
+          );
+          remaining = result.remaining;
+          if (!result.deferred) deletePendingEviction(this.#db, entry.subId);
+          batch.scopeMap(table, entry.effective);
         });
-        batch.scopeMap(table, entry.effective);
-      });
+        if (remaining) await yieldToHost();
+      } while (remaining);
     }
   }
 
@@ -2110,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 {
@@ -2126,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) {
@@ -2146,9 +2214,6 @@ export class SyncClient {
           ? { baseVersion: mutation.baseVersion }
           : {}),
         values: json,
-        ...(changedFieldsByIndex[index] !== undefined
-          ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
-          : {}),
       };
     });
     this.#applyBatch((batch) => {
@@ -2201,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,
@@ -2217,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,
     );
   }
 
@@ -2753,6 +2810,7 @@ export class SyncClient {
     // survive it — the reference server keeps no replay buffer (§8.2).
     this.#setSyncNeeded(false);
     try {
+      await this.#drainPendingEvictions();
       const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
       // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
       // them, so the server-side existence check (§6.6) passes.
@@ -2830,7 +2888,7 @@ export class SyncClient {
       );
       // §4.8 E1: the push half may have drained commits that pinned rows of
       // a shrunk window unit — retry any deferred evictions now.
-      this.#drainPendingEvictions();
+      await this.#drainPendingEvictions();
       this.#progress.update(
         summary.failed.length > 0
           ? { state: 'failed', errorCode: 'sync.scope_revoked' }
@@ -2879,10 +2937,27 @@ export class SyncClient {
    * Pull repeatedly until quiescent: no commits delivered, no bootstrap
    * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
    */
-  async syncUntilIdle(maxRounds = 20): Promise<SyncSummary> {
+  async syncUntilIdle(maxRounds?: number): Promise<SyncSummary> {
+    const budget = maxRounds ?? 20;
     let last: SyncSummary | undefined;
-    for (let round = 0; round < maxRounds; round++) {
+    for (let round = 0; round < budget; round++) {
+      const before = JSON.stringify(
+        loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]),
+      );
       last = await this.sync();
+      if (
+        maxRounds === undefined &&
+        last.segmentRowsApplied > 0 &&
+        last.bootstrapping.length > 0 &&
+        before !==
+          JSON.stringify(
+            loadSubscriptions(this.#db).map((sub) => [
+              sub.id,
+              sub.bootstrapState,
+            ]),
+          )
+      )
+        round = -1;
       if (last.schemaFloor !== undefined) return last;
       if (
         last.commitsApplied === 0 &&
@@ -2897,7 +2972,7 @@ export class SyncClient {
     }
     throw new ClientSyncError(
       'sync.invalid_request',
-      `sync did not reach idle within ${maxRounds} rounds`,
+      'sync did not reach idle within the round budget',
     );
   }
 
@@ -3428,6 +3503,7 @@ export class SyncClient {
                   segment,
                   {
                     clearFirst,
+                    isCurrent: () => this.#localResetEpoch === resetEpoch,
                     onProgress: (rowsProcessed) =>
                       this.#progress.update({ rowsProcessed }),
                     effective,
@@ -3440,7 +3516,9 @@ export class SyncClient {
                         ) {
                           batch.table(table.name);
                         }
-                        return fn();
+                        const result = fn();
+                        this.#replayOutbox();
+                        return result;
                       }),
                   },
                   this.#encryption,
@@ -3499,6 +3577,7 @@ export class SyncClient {
                     },
                     {
                       clearFirst,
+                      isCurrent: () => this.#localResetEpoch === resetEpoch,
                       onProgress: (rowsProcessed) =>
                         this.#progress.update({ rowsProcessed }),
                       effective,
@@ -3511,7 +3590,9 @@ export class SyncClient {
                           ) {
                             batch.table(table.name);
                           }
-                          return fn();
+                          const result = fn();
+                          this.#replayOutbox();
+                          return result;
                         }),
                     },
                   ),
@@ -3530,6 +3611,7 @@ export class SyncClient {
                     segment,
                     {
                       clearFirst,
+                      isCurrent: () => this.#localResetEpoch === resetEpoch,
                       onProgress: (rowsProcessed) =>
                         this.#progress.update({ rowsProcessed }),
                       effective,
@@ -3542,7 +3624,9 @@ export class SyncClient {
                           ) {
                             batch.table(table.name);
                           }
-                          return fn();
+                          const result = fn();
+                          this.#replayOutbox();
+                          return result;
                         }),
                     },
                     this.#encryption,
@@ -3691,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);
@@ -3760,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,
@@ -4274,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) {
@@ -4291,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/database.ts

@@ -22,11 +22,16 @@ export interface ClientDatabase {
   /**
    * Optional sqlite-image capability (SPEC §5.3): expose `bytes` as an
    * attached read-only database schema named `alias` for the duration of
-   * `fn`, then detach. Presence of this method is what makes the client
+   * `fn`, awaiting its result before detaching. No transaction spans its awaits.
+   * Presence of this method is what makes the client
    * advertise `accept` bit 2 (§4.2). MUST be called outside any open
    * transaction (SQLite cannot ATTACH inside one); `fn` may open its own.
    */
-  withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+  withSqliteImage?<T>(
+    bytes: Uint8Array,
+    alias: string,
+    fn: () => T | Promise<T>,
+  ): Promise<T>;
   close(): void;
 }
 

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/node-database.ts

@@ -63,7 +63,11 @@ export class NodeClientDatabase implements ClientDatabase {
   }
 
   /** §5.3 image import through a private file attached for one callback. */
-  withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T {
+  async withSqliteImage<T>(
+    bytes: Uint8Array,
+    alias: string,
+    fn: () => T | Promise<T>,
+  ): Promise<T> {
     assertImageAlias(alias);
     const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
     const path = join(dir, 'segment.db');
@@ -71,7 +75,7 @@ export class NodeClientDatabase implements ClientDatabase {
       writeFileSync(path, bytes);
       this.db.prepare(`ATTACH DATABASE ? AS ${alias}`).run(path);
       try {
-        return fn();
+        return await fn();
       } finally {
         this.db.prepare(`DETACH DATABASE ${alias}`).run();
       }

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 {