@syncular/client 0.68.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/apply.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { hasUniqueIndex } from './schema.js';
2
- import { OUTBOX_IMAGES, countOutbox } from './outbox.js';
2
+ import { chainsOn, countOutbox, listOutbox, OUTBOX_IMAGES, OUTBOX_TABLE, } from './outbox.js';
3
3
  import { RETAINED_ROWS } from './failed-overlay.js';
4
4
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
5
5
  /**
@@ -108,6 +108,18 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
108
108
  const { rowId, rowVersion } = frame.changes[index];
109
109
  const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
110
110
  db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
111
+ // §7.1 chained base: this change names the version an acknowledged own
112
+ // commit wrote; pending upserts chained on it move to that version.
113
+ for (const { op } of db.query(`SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`, [change.table.name, rowId, frame.commitSeq])) {
114
+ const earlier = JSON.parse(op);
115
+ for (const commit of listOutbox(db, scope))
116
+ db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
117
+ JSON.stringify(commit.operations.map((operation) => chainsOn(earlier, operation)
118
+ ? { ...operation, baseVersion: rowVersion }
119
+ : operation)),
120
+ commit.seq,
121
+ ]);
122
+ }
111
123
  db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
112
124
  if (!land)
113
125
  continue;
package/dist/client.d.ts CHANGED
@@ -630,11 +630,16 @@ export declare class SyncClient {
630
630
  /**
631
631
  * Record one atomic local commit (§7.1): appended to the outbox in
632
632
  * schema-agnostic form and applied optimistically to the local mirror.
633
- * Returns the generated `clientCommitId`.
633
+ * Returns the generated `clientCommitId`, or the caller's unused one
634
+ * (`client.commit_id_reused` when this replica holds it).
634
635
  */
635
- mutate(mutations: readonly MutationInput[]): string;
636
+ mutate(mutations: readonly MutationInput[], options?: {
637
+ readonly clientCommitId?: string;
638
+ }): string;
636
639
  /** Host-facing mutation result with explicit network work intent (§7.5). */
637
- mutateCommand(mutations: readonly MutationInput[]): CommandResult<string>;
640
+ mutateCommand(mutations: readonly MutationInput[], options?: {
641
+ readonly clientCommitId?: string;
642
+ }): CommandResult<string>;
638
643
  /**
639
644
  * Partial update over the §6.1 sparse wire: record one upsert whose
640
645
  * presence set is the primary key plus the supplied non-scope columns.
package/dist/client.js CHANGED
@@ -14,7 +14,7 @@ import { ProgressEmitter, } from './progress.js';
14
14
  * ownership behind `LeaderLock`. One combined push+pull request per
15
15
  * `sync()` round (§7.2); local reads go straight to the database.
16
16
  */
17
- import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, } from '@syncular/core';
17
+ import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, definedObject, } from '@syncular/core';
18
18
  import { EncryptError } from '@syncular/core';
19
19
  import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
@@ -26,7 +26,7 @@ import { singleOwnerLock, } from './leader-lock.js';
26
26
  import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
27
27
  import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
28
28
  import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
29
- import { appendOutboxCommit, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
29
+ import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
30
30
  import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
31
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
32
  import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
@@ -941,8 +941,7 @@ export class SyncClient {
941
941
  });
942
942
  };
943
943
  const deliveryOf = (id) => {
944
- const pending = this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [id]).length > 0;
945
- if (pending)
944
+ if (this.#outboxCommitExists(id))
946
945
  return { status: 'pending', clientCommitId: id };
947
946
  const outcome = persistedCommitOutcome(this.#db, id);
948
947
  return outcome === undefined
@@ -2222,14 +2221,22 @@ export class SyncClient {
2222
2221
  /**
2223
2222
  * Record one atomic local commit (§7.1): appended to the outbox in
2224
2223
  * schema-agnostic form and applied optimistically to the local mirror.
2225
- * Returns the generated `clientCommitId`.
2224
+ * Returns the generated `clientCommitId`, or the caller's unused one
2225
+ * (`client.commit_id_reused` when this replica holds it).
2226
2226
  */
2227
- mutate(mutations) {
2228
- return this.#recordMutations(mutations);
2227
+ mutate(mutations, options) {
2228
+ return this.#recordMutations(mutations, options?.clientCommitId);
2229
2229
  }
2230
- #recordMutations(mutations) {
2230
+ #recordMutations(mutations, supplied) {
2231
2231
  this.#requireActive();
2232
- const clientCommitId = crypto.randomUUID();
2232
+ // §7.1: a supplied ID is non-empty (§6.1) and unknown to this replica.
2233
+ if (supplied === '')
2234
+ throw invalidRequest('clientCommitId is empty');
2235
+ if (supplied !== undefined &&
2236
+ (this.#outboxCommitExists(supplied) ||
2237
+ readCommitOutcome(this.#db, supplied)))
2238
+ throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
2239
+ const clientCommitId = supplied ?? crypto.randomUUID();
2233
2240
  const operations = mutations.map((mutation) => {
2234
2241
  const table = this.#table(mutation.table);
2235
2242
  if (mutation.op === 'delete') {
@@ -2259,6 +2266,7 @@ export class SyncClient {
2259
2266
  for (const column of table.columns) {
2260
2267
  if (!normalized.has(column.name))
2261
2268
  continue;
2269
+ const at = { table: table.name, column: column.name };
2262
2270
  // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
2263
2271
  // server accepts a present scope column whose value equals the
2264
2272
  // stored row and applies it as a no-op, so a decoded envelope
@@ -2271,14 +2279,14 @@ export class SyncClient {
2271
2279
  // proven equal already.
2272
2280
  if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
2273
2281
  if (!Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
2274
- throw invalidRequest(`table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`);
2282
+ throw invalidRequest('patch cannot write a scope column (§3.4)', false, at);
2275
2283
  }
2276
2284
  continue;
2277
2285
  }
2278
2286
  const value = normalized.get(column.name);
2279
2287
  if (value === undefined || value === null) {
2280
2288
  if (!column.nullable) {
2281
- throw invalidRequest(`table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`);
2289
+ throw invalidRequest('a non-nullable column is null (§6.1)', false, at);
2282
2290
  }
2283
2291
  json[column.name] = null;
2284
2292
  continue;
@@ -2363,9 +2371,9 @@ export class SyncClient {
2363
2371
  return clientCommitId;
2364
2372
  }
2365
2373
  /** Host-facing mutation result with explicit network work intent (§7.5). */
2366
- mutateCommand(mutations) {
2374
+ mutateCommand(mutations, options) {
2367
2375
  return {
2368
- value: this.mutate(mutations),
2376
+ value: this.mutate(mutations, options),
2369
2377
  effects: {
2370
2378
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2371
2379
  },
@@ -2386,7 +2394,9 @@ export class SyncClient {
2386
2394
  const normalized = normalizeRecordKeys(compiled, partial);
2387
2395
  const pkOverride = normalized.get(pkColumn.name);
2388
2396
  if (pkOverride !== undefined && String(pkOverride) !== rowId) {
2389
- throw invalidRequest(`table ${compiled.name}: patch cannot change the primary key`);
2397
+ throw invalidRequest('patch cannot change the primary key', false, {
2398
+ table,
2399
+ });
2390
2400
  }
2391
2401
  const pkType = localColumnType(pkColumn);
2392
2402
  const typedPk = pkType === 'integer' &&
@@ -2697,7 +2707,10 @@ export class SyncClient {
2697
2707
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
2698
2708
  // commit that alone exceeds the operation cap is a typed capacity error
2699
2709
  // and stays queued; a later one defers with the complete suffix.
2700
- if (maxCommits !== undefined && pushFrames.length >= maxCommits) {
2710
+ // §7.1 chained base: a commit chained on an earlier commit of this
2711
+ // request waits for that commit's change, which supplies its version.
2712
+ if ((maxCommits !== undefined && pushFrames.length >= maxCommits) ||
2713
+ outbox.some((earlier) => earlier.operations.some((prior) => commit.operations.some((operation) => chainsOn(prior, operation))))) {
2701
2714
  deferred = pendingCount - processed;
2702
2715
  break;
2703
2716
  }
@@ -2721,12 +2734,8 @@ export class SyncClient {
2721
2734
  });
2722
2735
  }
2723
2736
  catch (error) {
2724
- if (error instanceof OutboxEncodeError) {
2725
- this.#dropIncompatibleCommit(commit, error.message);
2726
- processed += 1;
2727
- continue;
2728
- }
2729
- if (error instanceof EncryptError) {
2737
+ if (error instanceof OutboxEncodeError ||
2738
+ error instanceof EncryptError) {
2730
2739
  this.#dropIncompatibleCommit(commit, error.message, error.code);
2731
2740
  processed += 1;
2732
2741
  continue;
@@ -5036,13 +5045,6 @@ export class SyncClient {
5036
5045
  }
5037
5046
  }
5038
5047
  }
5039
- function definedObject(record) {
5040
- for (const key of Object.keys(record)) {
5041
- if (record[key] === undefined)
5042
- delete record[key];
5043
- }
5044
- return record;
5045
- }
5046
5048
  function requireRowId(value) {
5047
5049
  if (typeof value === 'string' && value.length > 0)
5048
5050
  return value;
package/dist/errors.d.ts CHANGED
@@ -34,7 +34,7 @@ export declare class ClientSyncError extends Error {
34
34
  constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
35
35
  }
36
36
  /** Shared invalid-request construction for client validators and transport guards. */
37
- export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
37
+ export declare function invalidRequest(message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>): ClientSyncError;
38
38
  /** Shared retryable `sync.transport_failed` construction for client transports. */
39
39
  export declare function transportFailed(message: string, details?: Readonly<Record<string, unknown>>): ClientSyncError;
40
40
  /**
package/dist/errors.js CHANGED
@@ -40,8 +40,8 @@ export class ClientSyncError extends Error {
40
40
  }
41
41
  }
42
42
  /** Shared invalid-request construction for client validators and transport guards. */
43
- export function invalidRequest(message, retryable = false) {
44
- return new ClientSyncError('sync.invalid_request', message, retryable);
43
+ export function invalidRequest(message, retryable = false, details) {
44
+ return new ClientSyncError('sync.invalid_request', message, retryable, details);
45
45
  }
46
46
  /** Shared retryable `sync.transport_failed` construction for client transports. */
47
47
  export function transportFailed(message, details) {
@@ -4,7 +4,6 @@ import type { CompiledClientSchema, CompiledClientTable, JsonRowValue } from './
4
4
  import type { RowValue } from '@syncular/core';
5
5
  import type { RetainedCommitRow } from './outcomes.js';
6
6
  import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
7
- /** Protected failure state. The server base advances independently of intent. */
8
7
  export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
9
8
  export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
10
9
  export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[], commitSeq?: number): void;
@@ -6,6 +6,7 @@ import { ClientSyncError } from './errors.js';
6
6
  import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
7
7
  import { deleteLocalRow, upsertLocalRow } from './apply.js';
8
8
  /** Protected failure state. The server base advances independently of intent. */
9
+ const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
9
10
  export function ensureFailedOverlaySchema(db) {
10
11
  db.exec(`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`);
11
12
  const columns = db.query(`PRAGMA table_info(${RETAINED_ROWS})`);
@@ -37,7 +38,7 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
37
38
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
38
39
  })));
39
40
  }
40
- db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
41
+ db.exec(SET_UNIQUE_CONFLICTS, [
41
42
  conflicts.length
42
43
  ? JSON.stringify(conflicts.sort((a, b) => table.indexes.findIndex((index) => index.name === a.index) -
43
44
  table.indexes.findIndex((index) => index.name === b.index)))
@@ -143,7 +144,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
143
144
  const authorized = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue)).filter((conflict) => conflict.serverVersion >= 0 &&
144
145
  !db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
145
146
  if (authorized.length)
146
- db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
147
+ db.exec(SET_UNIQUE_CONFLICTS, [
147
148
  JSON.stringify(authorized.map((conflict) => ({
148
149
  ...conflict,
149
150
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
package/dist/http.js CHANGED
@@ -264,15 +264,9 @@ export function httpBlobTransport(blobsBaseUrl, options) {
264
264
  catch {
265
265
  // Not JSON: inline bytes.
266
266
  }
267
- if (typeof envelope?.url === 'string') {
268
- return {
269
- kind: 'url',
270
- url: envelope.url,
271
- ...(typeof envelope.urlExpiresAtMs === 'number'
272
- ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
273
- : {}),
274
- };
275
- }
267
+ const grant = envelope && urlGrant(envelope);
268
+ if (grant)
269
+ return grant;
276
270
  }
277
271
  return { kind: 'bytes', bytes };
278
272
  },
@@ -304,18 +298,8 @@ export function httpBlobTransport(blobsBaseUrl, options) {
304
298
  if (!response.ok)
305
299
  await throwHttpError(response);
306
300
  const body = (await transfer('blob grant read failed', () => response.json(), response.status));
307
- if (typeof body.url === 'string') {
308
- return {
309
- kind: 'url',
310
- url: body.url,
311
- ...(typeof body.urlExpiresAtMs === 'number'
312
- ? { urlExpiresAtMs: body.urlExpiresAtMs }
313
- : {}),
314
- };
315
- }
316
- if (body.present === true)
317
- return { kind: 'present' };
318
- return { kind: 'none' };
301
+ return (urlGrant(body) ??
302
+ (body.present === true ? { kind: 'present' } : { kind: 'none' }));
319
303
  },
320
304
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
321
305
  uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
@@ -392,3 +376,15 @@ export function webSocketRealtimeConnector(realtimeUrl) {
392
376
  };
393
377
  });
394
378
  }
379
+ /** §5.9.3, §5.9.5: a JSON body with a string `url` is a presigned grant. */
380
+ function urlGrant(body) {
381
+ return typeof body.url === 'string'
382
+ ? {
383
+ kind: 'url',
384
+ url: body.url,
385
+ ...(typeof body.urlExpiresAtMs === 'number'
386
+ ? { urlExpiresAtMs: body.urlExpiresAtMs }
387
+ : {}),
388
+ }
389
+ : undefined;
390
+ }
@@ -149,7 +149,9 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
149
149
  localRevision(): Promise<bigint>;
150
150
  statusSnapshot(): Promise<SyncStatusSnapshot>;
151
151
  diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
152
- mutate(mutations: readonly MutationInput[]): Promise<string>;
152
+ mutate(mutations: readonly MutationInput[], options?: {
153
+ readonly clientCommitId?: string;
154
+ }): Promise<string>;
153
155
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
154
156
  readonly baseVersion?: number;
155
157
  }): Promise<string>;
@@ -533,9 +533,12 @@ export class NativeBridgeClient {
533
533
  role: 'single',
534
534
  });
535
535
  }
536
- async mutate(mutations) {
536
+ async mutate(mutations, options) {
537
537
  const result = (await this.command('mutate', {
538
538
  mutations: encodeValue(mutations),
539
+ ...(options?.clientCommitId === undefined
540
+ ? {}
541
+ : { clientCommitId: options.clientCommitId }),
539
542
  }));
540
543
  return result.clientCommitId;
541
544
  }
package/dist/outbox.d.ts CHANGED
@@ -38,6 +38,11 @@ export interface OutboxCommit {
38
38
  readonly createdAtMs: number;
39
39
  readonly operations: readonly OutboxOperation[];
40
40
  }
41
+ /**
42
+ * §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
43
+ * and presents only columns `earlier` presents.
44
+ */
45
+ export declare function chainsOn(earlier: OutboxOperation, later: OutboxOperation): boolean;
41
46
  /** Protected local rollback image; never encoded or exposed in outcomes. */
42
47
  export interface OutboxBeforeImage {
43
48
  readonly opIndex: number;
@@ -68,7 +73,7 @@ export declare function replaceOutboxBeforeImages(db: ClientDatabase, commit: Pi
68
73
  * so the caller can drop the commit through the rejection channel.
69
74
  */
70
75
  export declare class OutboxEncodeError extends ClientSyncError {
71
- constructor(message: string);
76
+ constructor();
72
77
  }
73
78
  /**
74
79
  * Encode one outbox commit as a `PUSH_COMMIT` frame with the current
package/dist/outbox.js CHANGED
@@ -8,9 +8,22 @@ export const OUTBOX_IMAGES = '_syncular_outbox_before_images';
8
8
  * request is built — a commit recorded under schema N replays after an
9
9
  * upgrade to N+1 by re-encoding.
10
10
  */
11
- import { encodeSparseRow, } from '@syncular/core';
11
+ import { definedObject, encodeSparseRow, } from '@syncular/core';
12
12
  import { ClientSyncError, invalidRequest } from './errors.js';
13
13
  import { jsonToRowValue, } from './schema.js';
14
+ /**
15
+ * §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
16
+ * and presents only columns `earlier` presents.
17
+ */
18
+ export function chainsOn(earlier, later) {
19
+ // Only an upsert carries values, and it always carries its primary key.
20
+ return (later.op === 'upsert' &&
21
+ earlier.rowId === later.rowId &&
22
+ earlier.table === later.table &&
23
+ later.baseVersion > 0 &&
24
+ earlier.baseVersion === later.baseVersion &&
25
+ Object.keys(later.values ?? {}).every((column) => earlier.values?.[column] !== undefined));
26
+ }
14
27
  export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
15
28
  if (operations.length === 0) {
16
29
  throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
@@ -110,8 +123,8 @@ export function replaceOutboxBeforeImages(db, commit, replacements) {
110
123
  * so the caller can drop the commit through the rejection channel.
111
124
  */
112
125
  export class OutboxEncodeError extends ClientSyncError {
113
- constructor(message) {
114
- super('sync.outbox_incompatible', message, false);
126
+ constructor() {
127
+ super('sync.outbox_incompatible', 'the persisted commit cannot encode under the current schema', false);
115
128
  }
116
129
  }
117
130
  function sparseValues(table, values, insert) {
@@ -119,7 +132,7 @@ function sparseValues(table, values, insert) {
119
132
  // bump removed (or renamed) it — the commit cannot be expressed now.
120
133
  for (const key of Object.keys(values)) {
121
134
  if (!table.columnIndex.has(key)) {
122
- throw new OutboxEncodeError(`outbox column ${JSON.stringify(key)} is absent from table ${JSON.stringify(table.name)} (§7.4.4)`);
135
+ throw new OutboxEncodeError();
123
136
  }
124
137
  }
125
138
  return table.columns.map((column) => {
@@ -130,7 +143,7 @@ function sparseValues(table, values, insert) {
130
143
  return undefined;
131
144
  // §7.1: an insert-intent operation presents every current column.
132
145
  if (!column.nullable) {
133
- throw new OutboxEncodeError('an outbox insert lacks a non-nullable column (§7.4.4)');
146
+ throw new OutboxEncodeError();
134
147
  }
135
148
  return null;
136
149
  });
@@ -147,23 +160,21 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
147
160
  const operations = [];
148
161
  for (const op of commit.operations) {
149
162
  if (op.op === 'delete') {
150
- operations.push({
163
+ operations.push(definedObject({
151
164
  table: op.table,
152
165
  rowId: op.rowId,
153
166
  op: 'delete',
154
- ...(op.baseVersion !== undefined
155
- ? { baseVersion: op.baseVersion }
156
- : {}),
157
- });
167
+ baseVersion: op.baseVersion,
168
+ }));
158
169
  continue;
159
170
  }
160
171
  const table = schema.tables.get(op.table);
161
172
  if (table === undefined) {
162
173
  // §7.4.4: the bump removed this table — the commit cannot be encoded.
163
- throw new OutboxEncodeError(`outbox table ${JSON.stringify(op.table)} is absent from the current schema (§7.4.4)`);
174
+ throw new OutboxEncodeError();
164
175
  }
165
176
  if (op.values === undefined) {
166
- throw invalidRequest(`outbox upsert on ${op.table}/${op.rowId} has no values`);
177
+ throw invalidRequest('an outbox upsert has no values');
167
178
  }
168
179
  let values = sparseValues(table, op.values, op.insert === true);
169
180
  if (table.hasEncryptedColumns) {
@@ -171,13 +182,13 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
171
182
  const { encryptRowValues } = await import('./encryption.js');
172
183
  values = await encryptRowValues(encryption, table, op.rowId, values, storedKeyIdFor?.(table, op.rowId));
173
184
  }
174
- operations.push({
185
+ operations.push(definedObject({
175
186
  table: op.table,
176
187
  rowId: op.rowId,
177
188
  op: 'upsert',
178
- ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
189
+ baseVersion: op.baseVersion,
179
190
  payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
180
- });
191
+ }));
181
192
  }
182
193
  return {
183
194
  type: 'PUSH_COMMIT',
package/dist/outcomes.js CHANGED
@@ -187,10 +187,13 @@ export function recordCommitOutcome(db, outcome) {
187
187
  ]);
188
188
  return commitOutcome(db, outcome.clientCommitId);
189
189
  }
190
- export function commitOutcome(db, clientCommitId) {
191
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
190
+ function outcomeRow(db, clientCommitId) {
191
+ return db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
192
192
  clientCommitId,
193
193
  ])[0];
194
+ }
195
+ export function commitOutcome(db, clientCommitId) {
196
+ const row = outcomeRow(db, clientCommitId);
194
197
  return row === undefined ? undefined : parseOutcome(db, row);
195
198
  }
196
199
  /**
@@ -200,9 +203,7 @@ export function commitOutcome(db, clientCommitId) {
200
203
  * native sidecar reports, never a raw `SyntaxError`.
201
204
  */
202
205
  export function persistedCommitOutcome(db, clientCommitId) {
203
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
204
- clientCommitId,
205
- ])[0];
206
+ const row = outcomeRow(db, clientCommitId);
206
207
  if (row === undefined)
207
208
  return undefined;
208
209
  function corrupt() {
@@ -377,8 +377,8 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
377
377
  setWindow: async (base, units) => {
378
378
  await requireClient().setWindowCommand(base, units);
379
379
  },
380
- mutate: (mutations) => {
381
- return requireClient().mutateCommand(mutations).value;
380
+ mutate: (mutations, options) => {
381
+ return requireClient().mutateCommand(mutations, options).value;
382
382
  },
383
383
  patch: (table, rowId, partial, options) => {
384
384
  // Same §8.4 rule as `mutate`: a local write must push without the app
@@ -264,7 +264,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
264
264
  unsubscribe(id: string): Promise<void>;
265
265
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
266
266
  windowState(base: WindowBase): Promise<WindowState>;
267
- mutate(mutations: readonly MutationInput[]): Promise<string>;
267
+ mutate(mutations: readonly MutationInput[], options?: {
268
+ readonly clientCommitId?: string;
269
+ }): Promise<string>;
268
270
  /** Partial-update convenience: read-merge-write one full-row upsert. */
269
271
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
270
272
  readonly baseVersion?: number;
@@ -351,8 +351,8 @@ export class SyncClientHandle {
351
351
  windowState(base) {
352
352
  return this.#call('windowState', [base]);
353
353
  }
354
- mutate(mutations) {
355
- return this.#call('mutate', [mutations]);
354
+ mutate(mutations, options) {
355
+ return this.#call('mutate', [mutations, options]);
356
356
  }
357
357
  /** Partial-update convenience: read-merge-write one full-row upsert. */
358
358
  patch(table, rowId, partial, options) {
@@ -141,7 +141,9 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
141
141
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
142
142
  /** §4.8 completeness oracle: the windowed-in values of a base. */
143
143
  windowState(base: WindowBase): WindowState;
144
- mutate(mutations: readonly MutationInput[]): string;
144
+ mutate(mutations: readonly MutationInput[], options?: {
145
+ readonly clientCommitId?: string;
146
+ }): string;
145
147
  /** Partial-update convenience: read-merge-write one full-row upsert. */
146
148
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
147
149
  readonly baseVersion?: number;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.68.0",
3
+ "version": "0.69.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.68.0"
124
+ "@syncular/core": "0.69.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.68.0",
128
+ "@syncular/server": "0.69.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -1,5 +1,12 @@
1
1
  import { hasUniqueIndex } from './schema';
2
- import { OUTBOX_IMAGES, countOutbox } from './outbox';
2
+ import {
3
+ chainsOn,
4
+ countOutbox,
5
+ listOutbox,
6
+ OUTBOX_IMAGES,
7
+ OUTBOX_TABLE,
8
+ type OutboxOperation,
9
+ } from './outbox';
3
10
  import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
4
11
  import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
5
12
  /**
@@ -186,6 +193,25 @@ export async function applyCommitFrame(
186
193
  `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
187
194
  [frame.commitSeq, change.table.name, rowId],
188
195
  );
196
+ // §7.1 chained base: this change names the version an acknowledged own
197
+ // commit wrote; pending upserts chained on it move to that version.
198
+ for (const { op } of db.query(
199
+ `SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`,
200
+ [change.table.name, rowId, frame.commitSeq],
201
+ )) {
202
+ const earlier: OutboxOperation = JSON.parse(op as string);
203
+ for (const commit of listOutbox(db, scope))
204
+ db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
205
+ JSON.stringify(
206
+ commit.operations.map((operation) =>
207
+ chainsOn(earlier, operation)
208
+ ? { ...operation, baseVersion: rowVersion }
209
+ : operation,
210
+ ),
211
+ ),
212
+ commit.seq,
213
+ ]);
214
+ }
189
215
  db.exec(
190
216
  `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
191
217
  [change.table.name, rowId, frame.commitSeq],
package/src/client.ts CHANGED
@@ -62,6 +62,7 @@ import {
62
62
  unitId,
63
63
  type UnitScopes,
64
64
  type WakeReason,
65
+ definedObject,
65
66
  } from '@syncular/core';
66
67
  import { EncryptError } from '@syncular/core';
67
68
  import { EncodeError } from '@syncular/core';
@@ -161,6 +162,7 @@ import {
161
162
  } from './local-rebootstrap-receipt';
162
163
  import {
163
164
  appendOutboxCommit,
165
+ chainsOn,
164
166
  deleteOutboxCommit,
165
167
  encodeOutboxCommit,
166
168
  listOutbox,
@@ -1852,12 +1854,8 @@ export class SyncClient {
1852
1854
  });
1853
1855
  };
1854
1856
  const deliveryOf = (id: string): CommitDelivery => {
1855
- const pending =
1856
- this.#db.query(
1857
- `SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`,
1858
- [id],
1859
- ).length > 0;
1860
- if (pending) return { status: 'pending', clientCommitId: id };
1857
+ if (this.#outboxCommitExists(id))
1858
+ return { status: 'pending', clientCommitId: id };
1861
1859
  const outcome = persistedCommitOutcome(this.#db, id);
1862
1860
  return outcome === undefined
1863
1861
  ? { status: 'unknown', clientCommitId: id }
@@ -3404,15 +3402,35 @@ export class SyncClient {
3404
3402
  /**
3405
3403
  * Record one atomic local commit (§7.1): appended to the outbox in
3406
3404
  * schema-agnostic form and applied optimistically to the local mirror.
3407
- * Returns the generated `clientCommitId`.
3405
+ * Returns the generated `clientCommitId`, or the caller's unused one
3406
+ * (`client.commit_id_reused` when this replica holds it).
3408
3407
  */
3409
- mutate(mutations: readonly MutationInput[]): string {
3410
- return this.#recordMutations(mutations);
3408
+ mutate(
3409
+ mutations: readonly MutationInput[],
3410
+ options?: { readonly clientCommitId?: string },
3411
+ ): string {
3412
+ return this.#recordMutations(mutations, options?.clientCommitId);
3411
3413
  }
3412
3414
 
3413
- #recordMutations(mutations: readonly MutationInput[]): string {
3415
+ #recordMutations(
3416
+ mutations: readonly MutationInput[],
3417
+ supplied?: string,
3418
+ ): string {
3414
3419
  this.#requireActive();
3415
- const clientCommitId = crypto.randomUUID();
3420
+ // §7.1: a supplied ID is non-empty (§6.1) and unknown to this replica.
3421
+ if (supplied === '') throw invalidRequest('clientCommitId is empty');
3422
+ if (
3423
+ supplied !== undefined &&
3424
+ (this.#outboxCommitExists(supplied) ||
3425
+ readCommitOutcome(this.#db, supplied))
3426
+ )
3427
+ throw new ClientSyncError(
3428
+ 'client.commit_id_reused',
3429
+ 'clientCommitId is held',
3430
+ false,
3431
+ { clientCommitId: supplied },
3432
+ );
3433
+ const clientCommitId = supplied ?? crypto.randomUUID();
3416
3434
  const operations: OutboxOperation[] = mutations.map((mutation) => {
3417
3435
  const table = this.#table(mutation.table);
3418
3436
  if (mutation.op === 'delete') {
@@ -3447,6 +3465,7 @@ export class SyncClient {
3447
3465
  );
3448
3466
  for (const column of table.columns) {
3449
3467
  if (!normalized.has(column.name)) continue;
3468
+ const at = { table: table.name, column: column.name };
3450
3469
  // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
3451
3470
  // server accepts a present scope column whose value equals the
3452
3471
  // stored row and applies it as a no-op, so a decoded envelope
@@ -3472,7 +3491,9 @@ export class SyncClient {
3472
3491
  )
3473
3492
  ) {
3474
3493
  throw invalidRequest(
3475
- `table ${table.name}: patch cannot write scope column ${JSON.stringify(column.name)} (§3.4)`,
3494
+ 'patch cannot write a scope column (§3.4)',
3495
+ false,
3496
+ at,
3476
3497
  );
3477
3498
  }
3478
3499
  continue;
@@ -3481,7 +3502,9 @@ export class SyncClient {
3481
3502
  if (value === undefined || value === null) {
3482
3503
  if (!column.nullable) {
3483
3504
  throw invalidRequest(
3484
- `table ${table.name}: column ${JSON.stringify(column.name)} is not nullable (§6.1)`,
3505
+ 'a non-nullable column is null (§6.1)',
3506
+ false,
3507
+ at,
3485
3508
  );
3486
3509
  }
3487
3510
  json[column.name] = null;
@@ -3586,9 +3609,12 @@ export class SyncClient {
3586
3609
  }
3587
3610
 
3588
3611
  /** Host-facing mutation result with explicit network work intent (§7.5). */
3589
- mutateCommand(mutations: readonly MutationInput[]): CommandResult<string> {
3612
+ mutateCommand(
3613
+ mutations: readonly MutationInput[],
3614
+ options?: { readonly clientCommitId?: string },
3615
+ ): CommandResult<string> {
3590
3616
  return {
3591
- value: this.mutate(mutations),
3617
+ value: this.mutate(mutations, options),
3592
3618
  effects: {
3593
3619
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
3594
3620
  },
@@ -3615,9 +3641,9 @@ export class SyncClient {
3615
3641
  const normalized = normalizeRecordKeys(compiled, partial);
3616
3642
  const pkOverride = normalized.get(pkColumn.name);
3617
3643
  if (pkOverride !== undefined && String(pkOverride) !== rowId) {
3618
- throw invalidRequest(
3619
- `table ${compiled.name}: patch cannot change the primary key`,
3620
- );
3644
+ throw invalidRequest('patch cannot change the primary key', false, {
3645
+ table,
3646
+ });
3621
3647
  }
3622
3648
  const pkType = localColumnType(pkColumn);
3623
3649
  const typedPk =
@@ -3996,7 +4022,16 @@ export class SyncClient {
3996
4022
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
3997
4023
  // commit that alone exceeds the operation cap is a typed capacity error
3998
4024
  // and stays queued; a later one defers with the complete suffix.
3999
- if (maxCommits !== undefined && pushFrames.length >= maxCommits) {
4025
+ // §7.1 chained base: a commit chained on an earlier commit of this
4026
+ // request waits for that commit's change, which supplies its version.
4027
+ if (
4028
+ (maxCommits !== undefined && pushFrames.length >= maxCommits) ||
4029
+ outbox.some((earlier) =>
4030
+ earlier.operations.some((prior) =>
4031
+ commit.operations.some((operation) => chainsOn(prior, operation)),
4032
+ ),
4033
+ )
4034
+ ) {
4000
4035
  deferred = pendingCount - processed;
4001
4036
  break;
4002
4037
  }
@@ -4026,12 +4061,10 @@ export class SyncClient {
4026
4061
  },
4027
4062
  );
4028
4063
  } catch (error) {
4029
- if (error instanceof OutboxEncodeError) {
4030
- this.#dropIncompatibleCommit(commit, error.message);
4031
- processed += 1;
4032
- continue;
4033
- }
4034
- if (error instanceof EncryptError) {
4064
+ if (
4065
+ error instanceof OutboxEncodeError ||
4066
+ error instanceof EncryptError
4067
+ ) {
4035
4068
  this.#dropIncompatibleCommit(commit, error.message, error.code);
4036
4069
  processed += 1;
4037
4070
  continue;
@@ -6880,21 +6913,6 @@ export class SyncClient {
6880
6913
  }
6881
6914
  }
6882
6915
 
6883
- type DefinedObject<T> = {
6884
- [K in keyof T as undefined extends T[K] ? never : K]: T[K];
6885
- } & {
6886
- [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<
6887
- T[K],
6888
- undefined
6889
- >;
6890
- };
6891
- function definedObject<const T extends object>(record: T): DefinedObject<T> {
6892
- for (const key of Object.keys(record) as (keyof T)[]) {
6893
- if (record[key] === undefined) delete record[key];
6894
- }
6895
- return record as DefinedObject<T>;
6896
- }
6897
-
6898
6916
  function requireRowId(value: unknown): string {
6899
6917
  if (typeof value === 'string' && value.length > 0) return value;
6900
6918
  if (typeof value === 'number' && Number.isSafeInteger(value)) {
package/src/errors.ts CHANGED
@@ -61,8 +61,14 @@ export class ClientSyncError extends Error {
61
61
  export function invalidRequest(
62
62
  message: string,
63
63
  retryable = false,
64
+ details?: Readonly<Record<string, unknown>>,
64
65
  ): ClientSyncError {
65
- return new ClientSyncError('sync.invalid_request', message, retryable);
66
+ return new ClientSyncError(
67
+ 'sync.invalid_request',
68
+ message,
69
+ retryable,
70
+ details,
71
+ );
66
72
  }
67
73
 
68
74
  /** Shared retryable `sync.transport_failed` construction for client transports. */
@@ -29,6 +29,8 @@ import type {
29
29
  import { deleteLocalRow, upsertLocalRow } from './apply';
30
30
 
31
31
  /** Protected failure state. The server base advances independently of intent. */
32
+ const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
33
+
32
34
  export function ensureFailedOverlaySchema(db: ClientDatabase): void {
33
35
  db.exec(
34
36
  `CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`,
@@ -81,22 +83,19 @@ export function retainedBaseWrite(
81
83
  })),
82
84
  );
83
85
  }
84
- db.exec(
85
- `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
86
- [
87
- conflicts.length
88
- ? JSON.stringify(
89
- conflicts.sort(
90
- (a, b) =>
91
- table.indexes.findIndex((index) => index.name === a.index) -
92
- table.indexes.findIndex((index) => index.name === b.index),
93
- ),
94
- )
95
- : null,
96
- retained.commit_id as string,
97
- Number(retained.idx),
98
- ],
99
- );
86
+ db.exec(SET_UNIQUE_CONFLICTS, [
87
+ conflicts.length
88
+ ? JSON.stringify(
89
+ conflicts.sort(
90
+ (a, b) =>
91
+ table.indexes.findIndex((index) => index.name === a.index) -
92
+ table.indexes.findIndex((index) => index.name === b.index),
93
+ ),
94
+ )
95
+ : null,
96
+ retained.commit_id as string,
97
+ Number(retained.idx),
98
+ ]);
100
99
  }
101
100
  }
102
101
 
@@ -272,19 +271,16 @@ export function failedOverlayCommits(
272
271
  ).length,
273
272
  );
274
273
  if (authorized.length)
275
- db.exec(
276
- `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`,
277
- [
278
- JSON.stringify(
279
- authorized.map((conflict) => ({
280
- ...conflict,
281
- serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
282
- })),
283
- ),
284
- row.commit_id as string,
285
- row.idx as number,
286
- ],
287
- );
274
+ db.exec(SET_UNIQUE_CONFLICTS, [
275
+ JSON.stringify(
276
+ authorized.map((conflict) => ({
277
+ ...conflict,
278
+ serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
279
+ })),
280
+ ),
281
+ row.commit_id as string,
282
+ row.idx as number,
283
+ ]);
288
284
  }
289
285
  }
290
286
  const prior = commits.get(id);
package/src/http.ts CHANGED
@@ -411,15 +411,8 @@ export function httpBlobTransport(
411
411
  } catch {
412
412
  // Not JSON: inline bytes.
413
413
  }
414
- if (typeof envelope?.url === 'string') {
415
- return {
416
- kind: 'url',
417
- url: envelope.url,
418
- ...(typeof envelope.urlExpiresAtMs === 'number'
419
- ? { urlExpiresAtMs: envelope.urlExpiresAtMs }
420
- : {}),
421
- };
422
- }
414
+ const grant = envelope && urlGrant(envelope);
415
+ if (grant) return grant;
423
416
  }
424
417
  return { kind: 'bytes', bytes };
425
418
  },
@@ -461,22 +454,11 @@ export function httpBlobTransport(
461
454
  'blob grant read failed',
462
455
  () => response.json(),
463
456
  response.status,
464
- )) as {
465
- url?: string;
466
- urlExpiresAtMs?: number;
467
- present?: boolean;
468
- };
469
- if (typeof body.url === 'string') {
470
- return {
471
- kind: 'url',
472
- url: body.url,
473
- ...(typeof body.urlExpiresAtMs === 'number'
474
- ? { urlExpiresAtMs: body.urlExpiresAtMs }
475
- : {}),
476
- };
477
- }
478
- if (body.present === true) return { kind: 'present' };
479
- return { kind: 'none' };
457
+ )) as { url?: unknown; urlExpiresAtMs?: unknown; present?: boolean };
458
+ return (
459
+ urlGrant(body) ??
460
+ (body.present === true ? { kind: 'present' } : { kind: 'none' })
461
+ );
480
462
  },
481
463
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
482
464
  uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
@@ -569,3 +551,16 @@ export function webSocketRealtimeConnector(
569
551
  };
570
552
  });
571
553
  }
554
+
555
+ /** §5.9.3, §5.9.5: a JSON body with a string `url` is a presigned grant. */
556
+ function urlGrant(body: { url?: unknown; urlExpiresAtMs?: unknown }) {
557
+ return typeof body.url === 'string'
558
+ ? {
559
+ kind: 'url' as const,
560
+ url: body.url,
561
+ ...(typeof body.urlExpiresAtMs === 'number'
562
+ ? { urlExpiresAtMs: body.urlExpiresAtMs }
563
+ : {}),
564
+ }
565
+ : undefined;
566
+ }
@@ -800,9 +800,15 @@ export abstract class NativeBridgeClient implements PromiseMethods<
800
800
  });
801
801
  }
802
802
 
803
- async mutate(mutations: readonly MutationInput[]): Promise<string> {
803
+ async mutate(
804
+ mutations: readonly MutationInput[],
805
+ options?: { readonly clientCommitId?: string },
806
+ ): Promise<string> {
804
807
  const result = (await this.command('mutate', {
805
808
  mutations: encodeValue(mutations),
809
+ ...(options?.clientCommitId === undefined
810
+ ? {}
811
+ : { clientCommitId: options.clientCommitId }),
806
812
  })) as { clientCommitId: string };
807
813
  return result.clientCommitId;
808
814
  }
package/src/outbox.ts CHANGED
@@ -10,6 +10,7 @@ import type { OverlayScope } from './failed-overlay';
10
10
  * upgrade to N+1 by re-encoding.
11
11
  */
12
12
  import {
13
+ definedObject,
13
14
  encodeSparseRow,
14
15
  type PushCommitFrame,
15
16
  type PushOperation,
@@ -52,6 +53,27 @@ export interface OutboxCommit {
52
53
  readonly operations: readonly OutboxOperation[];
53
54
  }
54
55
 
56
+ /**
57
+ * §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
58
+ * and presents only columns `earlier` presents.
59
+ */
60
+ export function chainsOn(
61
+ earlier: OutboxOperation,
62
+ later: OutboxOperation,
63
+ ): boolean {
64
+ // Only an upsert carries values, and it always carries its primary key.
65
+ return (
66
+ later.op === 'upsert' &&
67
+ earlier.rowId === later.rowId &&
68
+ earlier.table === later.table &&
69
+ later.baseVersion! > 0 &&
70
+ earlier.baseVersion === later.baseVersion &&
71
+ Object.keys(later.values ?? {}).every(
72
+ (column) => earlier.values?.[column] !== undefined,
73
+ )
74
+ );
75
+ }
76
+
55
77
  /** Protected local rollback image; never encoded or exposed in outcomes. */
56
78
  export interface OutboxBeforeImage {
57
79
  readonly opIndex: number;
@@ -209,8 +231,12 @@ export function replaceOutboxBeforeImages(
209
231
  * so the caller can drop the commit through the rejection channel.
210
232
  */
211
233
  export class OutboxEncodeError extends ClientSyncError {
212
- constructor(message: string) {
213
- super('sync.outbox_incompatible', message, false);
234
+ constructor() {
235
+ super(
236
+ 'sync.outbox_incompatible',
237
+ 'the persisted commit cannot encode under the current schema',
238
+ false,
239
+ );
214
240
  }
215
241
  }
216
242
 
@@ -223,9 +249,7 @@ function sparseValues(
223
249
  // bump removed (or renamed) it — the commit cannot be expressed now.
224
250
  for (const key of Object.keys(values)) {
225
251
  if (!table.columnIndex.has(key)) {
226
- throw new OutboxEncodeError(
227
- `outbox column ${JSON.stringify(key)} is absent from table ${JSON.stringify(table.name)} (§7.4.4)`,
228
- );
252
+ throw new OutboxEncodeError();
229
253
  }
230
254
  }
231
255
  return table.columns.map((column) => {
@@ -234,9 +258,7 @@ function sparseValues(
234
258
  if (!insert) return undefined;
235
259
  // §7.1: an insert-intent operation presents every current column.
236
260
  if (!column.nullable) {
237
- throw new OutboxEncodeError(
238
- 'an outbox insert lacks a non-nullable column (§7.4.4)',
239
- );
261
+ throw new OutboxEncodeError();
240
262
  }
241
263
  return null;
242
264
  });
@@ -262,27 +284,23 @@ export async function encodeOutboxCommit(
262
284
  const operations: PushOperation[] = [];
263
285
  for (const op of commit.operations) {
264
286
  if (op.op === 'delete') {
265
- operations.push({
266
- table: op.table,
267
- rowId: op.rowId,
268
- op: 'delete',
269
- ...(op.baseVersion !== undefined
270
- ? { baseVersion: op.baseVersion }
271
- : {}),
272
- });
287
+ operations.push(
288
+ definedObject({
289
+ table: op.table,
290
+ rowId: op.rowId,
291
+ op: 'delete',
292
+ baseVersion: op.baseVersion,
293
+ }),
294
+ );
273
295
  continue;
274
296
  }
275
297
  const table = schema.tables.get(op.table);
276
298
  if (table === undefined) {
277
299
  // §7.4.4: the bump removed this table — the commit cannot be encoded.
278
- throw new OutboxEncodeError(
279
- `outbox table ${JSON.stringify(op.table)} is absent from the current schema (§7.4.4)`,
280
- );
300
+ throw new OutboxEncodeError();
281
301
  }
282
302
  if (op.values === undefined) {
283
- throw invalidRequest(
284
- `outbox upsert on ${op.table}/${op.rowId} has no values`,
285
- );
303
+ throw invalidRequest('an outbox upsert has no values');
286
304
  }
287
305
  let values = sparseValues(table, op.values, op.insert === true);
288
306
  if (table.hasEncryptedColumns) {
@@ -296,13 +314,15 @@ export async function encodeOutboxCommit(
296
314
  storedKeyIdFor?.(table, op.rowId),
297
315
  );
298
316
  }
299
- operations.push({
300
- table: op.table,
301
- rowId: op.rowId,
302
- op: 'upsert',
303
- ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
304
- payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
305
- });
317
+ operations.push(
318
+ definedObject({
319
+ table: op.table,
320
+ rowId: op.rowId,
321
+ op: 'upsert',
322
+ baseVersion: op.baseVersion,
323
+ payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
324
+ }),
325
+ );
306
326
  }
307
327
  return {
308
328
  type: 'PUSH_COMMIT',
package/src/outcomes.ts CHANGED
@@ -365,13 +365,17 @@ export function recordCommitOutcome(
365
365
  return commitOutcome(db, outcome.clientCommitId) as CommitOutcome;
366
366
  }
367
367
 
368
+ function outcomeRow(db: ClientDatabase, clientCommitId: string) {
369
+ return db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
370
+ clientCommitId,
371
+ ])[0];
372
+ }
373
+
368
374
  export function commitOutcome(
369
375
  db: ClientDatabase,
370
376
  clientCommitId: string,
371
377
  ): CommitOutcome | undefined {
372
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
373
- clientCommitId,
374
- ])[0];
378
+ const row = outcomeRow(db, clientCommitId);
375
379
  return row === undefined ? undefined : parseOutcome(db, row);
376
380
  }
377
381
 
@@ -385,9 +389,7 @@ export function persistedCommitOutcome(
385
389
  db: ClientDatabase,
386
390
  clientCommitId: string,
387
391
  ): CommitOutcome | undefined {
388
- const row = db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
389
- clientCommitId,
390
- ])[0];
392
+ const row = outcomeRow(db, clientCommitId);
391
393
  if (row === undefined) return undefined;
392
394
  function corrupt(): never {
393
395
  throw new ClientSyncError(
@@ -578,8 +578,8 @@ export function startSyncWorkerCore(
578
578
  setWindow: async (base, units) => {
579
579
  await requireClient().setWindowCommand(base, units);
580
580
  },
581
- mutate: (mutations) => {
582
- return requireClient().mutateCommand(mutations).value;
581
+ mutate: (mutations, options) => {
582
+ return requireClient().mutateCommand(mutations, options).value;
583
583
  },
584
584
  patch: (table, rowId, partial, options) => {
585
585
  // Same §8.4 rule as `mutate`: a local write must push without the app
@@ -664,8 +664,11 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
664
664
  return this.#call('windowState', [base]);
665
665
  }
666
666
 
667
- mutate(mutations: readonly MutationInput[]): Promise<string> {
668
- return this.#call('mutate', [mutations]);
667
+ mutate(
668
+ mutations: readonly MutationInput[],
669
+ options?: { readonly clientCommitId?: string },
670
+ ): Promise<string> {
671
+ return this.#call('mutate', [mutations, options]);
669
672
  }
670
673
 
671
674
  /** Partial-update convenience: read-merge-write one full-row upsert. */
@@ -190,7 +190,10 @@ export interface WorkerApi extends Omit<
190
190
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
191
191
  /** §4.8 completeness oracle: the windowed-in values of a base. */
192
192
  windowState(base: WindowBase): WindowState;
193
- mutate(mutations: readonly MutationInput[]): string;
193
+ mutate(
194
+ mutations: readonly MutationInput[],
195
+ options?: { readonly clientCommitId?: string },
196
+ ): string;
194
197
  /** Partial-update convenience: read-merge-write one full-row upsert. */
195
198
  patch(
196
199
  table: string,