@syncular/client 0.20.0 → 0.21.0

package/dist/client.js

@@ -9,7 +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 { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
+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';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.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. */
@@ -236,6 +236,7 @@ export class SyncClient {
         // an application-issued sync() call.
         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;
@@ -1126,22 +1127,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() {
         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));
     }
     subscriptions() {
@@ -1199,8 +1195,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.
      *
@@ -1258,7 +1254,7 @@ export class SyncClient {
             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;
             }
         });
@@ -1297,8 +1293,8 @@ export class SyncClient {
         return { units: live.map((u) => u.unit), pending };
     }
     /**
-     * §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
@@ -1306,19 +1302,21 @@ export class SyncClient {
      * with no local scope-column mapping, surfaces a configuration error and
      * evicts nothing (§4.8/§3.3).
      */
-    #evictUnit(baseKey, base, unit, subId) {
+    async #evictUnit(baseKey, base, unit, subId) {
         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 {
@@ -1330,13 +1328,17 @@ export class SyncClient {
             this.#needsPull = true;
             batch.status();
         });
+        if (remaining) {
+            await yieldToHost();
+            await this.#drainPendingEvictions();
+        }
     }
     /**
      * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
      * 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() {
+    async #drainPendingEvictions() {
         const pending = loadPendingEvictions(this.#db);
         if (pending.length === 0)
             return;
@@ -1346,16 +1348,23 @@ 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)
+            let remaining;
+            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);
         }
     }
     /**
@@ -1381,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 {
@@ -1396,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) {
@@ -1413,9 +1461,6 @@ export class SyncClient {
                     ? { baseVersion: mutation.baseVersion }
                     : {}),
                 values: json,
-                ...(changedFieldsByIndex[index] !== undefined
-                    ? { changedFields: [...(changedFieldsByIndex[index] ?? [])] }
-                    : {}),
             };
         });
         this.#applyBatch((batch) => {
@@ -1462,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
@@ -1920,6 +1960,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.
@@ -1981,7 +2022,7 @@ export class SyncClient {
             const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
             // §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' }
                 : { state: 'complete' });
@@ -2028,10 +2069,21 @@ 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) {
+    async syncUntilIdle(maxRounds) {
+        const budget = maxRounds ?? 20;
         let last;
-        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 &&
@@ -2043,7 +2095,7 @@ export class SyncClient {
                 return last;
             }
         }
-        throw new ClientSyncError('sync.invalid_request', `sync did not reach idle within ${maxRounds} rounds`);
+        throw new ClientSyncError('sync.invalid_request', 'sync did not reach idle within the round budget');
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it
@@ -2469,6 +2521,7 @@ export class SyncClient {
                         });
                         await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                             clearFirst,
+                            isCurrent: () => this.#localResetEpoch === resetEpoch,
                             onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                             effective,
                             transaction: (fn) => this.#applyBatch((batch) => {
@@ -2477,7 +2530,9 @@ export class SyncClient {
                                         this.#scopedRowsExist(table, effective))) {
                                     batch.table(table.name);
                                 }
-                                return fn();
+                                const result = fn();
+                                this.#replayOutbox();
+                                return result;
                             }),
                         }, this.#encryption), section.fresh && !section.cleared);
                         break;
@@ -2510,6 +2565,7 @@ export class SyncClient {
                                 scopeDigest: frame.scopeDigest,
                             }, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
                                 onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
@@ -2518,7 +2574,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }), section.fresh && !section.cleared);
                         }
@@ -2526,6 +2584,7 @@ export class SyncClient {
                             const segment = decodeRowsSegment(bytes);
                             await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
                                 onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
@@ -2534,7 +2593,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }, this.#encryption), section.fresh &&
                                 !section.cleared &&
@@ -2658,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);
@@ -2720,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);
@@ -3116,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) {
@@ -3134,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/database.d.ts

@@ -20,11 +20,12 @@ 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;
 }
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */

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

@@ -12,7 +12,7 @@ export declare class NodeClientDatabase implements ClientDatabase {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     transaction<T>(fn: () => T): T;
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 export declare function openNodeDatabase(path?: string): ClientDatabase;

package/dist/node-database.js

@@ -52,7 +52,7 @@ export class NodeClientDatabase {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage(bytes, alias, fn) {
+    async withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
         const path = join(dir, 'segment.db');
@@ -60,7 +60,7 @@ export class NodeClientDatabase {
             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/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),