@syncular/client 0.90.0 → 0.92.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/src/client.ts CHANGED
@@ -68,6 +68,7 @@ import { EncryptError } from '@syncular/core';
68
68
  import { EncodeError } from '@syncular/core';
69
69
  import {
70
70
  applyCommitFrame,
71
+ type ApplyStep,
71
72
  applyRowsSegment,
72
73
  applySqliteSegment,
73
74
  deleteLocalRow,
@@ -106,7 +107,6 @@ import {
106
107
  type DiagnosticLastChange,
107
108
  type DiagnosticLastRound,
108
109
  type DiagnosticQueryFailure,
109
- type DiagnosticRoundCounters,
110
110
  MAX_DIAGNOSTIC_DOMAINS,
111
111
  MAX_DIAGNOSTIC_QUERY_FAILURES,
112
112
  type RealtimePolicy,
@@ -405,6 +405,13 @@ export interface SyncIdleOptions {
405
405
  * shipped host loops pass it; the native bridge ignores it.
406
406
  */
407
407
  readonly skipEmpty?: boolean;
408
+ /**
409
+ * §8.4 host policy: after a round that applied data and left nothing
410
+ * pending, the round that confirms idle starts this many milliseconds
411
+ * later, so claims and writes made in reaction to that data ride in it.
412
+ * Default 0. The native bridge ignores it.
413
+ */
414
+ readonly coalesceMs?: number;
408
415
  }
409
416
 
410
417
  export type CurrentBaseProof =
@@ -960,6 +967,12 @@ function isFinalPushResult(frame: PushResultFrame): boolean {
960
967
  );
961
968
  }
962
969
 
970
+ function transportFlag(value: unknown): boolean {
971
+ if (typeof value !== 'boolean')
972
+ throw invalidRequest('transportEnabled must be a boolean');
973
+ return value;
974
+ }
975
+
963
976
  /** The stable `code` a thrown value carries, when it has one. */
964
977
  function thrownCode(error: unknown): string | undefined {
965
978
  const code = (error as { code?: unknown } | undefined)?.code;
@@ -1131,6 +1144,9 @@ export class SyncClient {
1131
1144
  readonly #queryFailures = new Map<string, DiagnosticQueryFailure>();
1132
1145
  /** The batch accumulator; non-undefined only inside `#applyBatch`. */
1133
1146
  #batch: ChangeAccumulator | undefined;
1147
+ /** §1.4 rule 4: the change batches an open coalesced apply transaction
1148
+ * publishes after its COMMIT, in revision order. */
1149
+ #held: (() => void)[] | undefined;
1134
1150
  /**
1135
1151
  * Operation-serialization mutex (the core owns one loop). Every
1136
1152
  * transaction-entering ASYNC operation — `sync`, the delta-apply body, and
@@ -1153,13 +1169,9 @@ export class SyncClient {
1153
1169
  #preflightBarrier: Promise<void> | undefined;
1154
1170
 
1155
1171
  constructor(config: SyncClientConfig) {
1156
- if (
1157
- config.transportEnabled !== undefined &&
1158
- typeof config.transportEnabled !== 'boolean'
1159
- ) {
1160
- throw invalidRequest('transportEnabled must be a boolean');
1161
- }
1162
- this.#transportEnabled = config.transportEnabled !== false;
1172
+ this.#transportEnabled =
1173
+ config.transportEnabled === undefined ||
1174
+ transportFlag(config.transportEnabled);
1163
1175
  for (const name of [
1164
1176
  'maxPushCommitsPerRequest',
1165
1177
  'maxPushOperationsPerRequest',
@@ -1436,17 +1448,18 @@ export class SyncClient {
1436
1448
  // earlier WITHOUT a schema bump.
1437
1449
  this.#db.transaction(() => {
1438
1450
  ensureLocalSyncedSchema(this.#db, this.#schema);
1439
- if (marker === undefined)
1440
- setMeta(
1441
- this.#db,
1442
- LOCAL_SCHEMA_VERSION_KEY,
1443
- String(this.#schema.version),
1444
- );
1445
- setLocalSchemaDescriptor(this.#db, this.#schema);
1446
- saveUnitScopeSchema(this.#db, this.#schema);
1451
+ this.#stampSchema(marker === undefined);
1447
1452
  });
1448
1453
  }
1449
1454
 
1455
+ /** Write the schema marker (when `version`), descriptor and unit scopes. */
1456
+ #stampSchema(version: boolean): void {
1457
+ if (version)
1458
+ setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
1459
+ setLocalSchemaDescriptor(this.#db, this.#schema);
1460
+ saveUnitScopeSchema(this.#db, this.#schema);
1461
+ }
1462
+
1450
1463
  /**
1451
1464
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
1452
1465
  * leaseState, and the tables and units a bump keeps (equal generations).
@@ -1484,13 +1497,7 @@ export class SyncClient {
1484
1497
  }
1485
1498
  changed = resetLocalReplica(this.#db, this.#schema, true);
1486
1499
  this.#replayOutbox();
1487
- setMeta(
1488
- this.#db,
1489
- LOCAL_SCHEMA_VERSION_KEY,
1490
- String(this.#schema.version),
1491
- );
1492
- setLocalSchemaDescriptor(this.#db, this.#schema);
1493
- saveUnitScopeSchema(this.#db, this.#schema);
1500
+ this.#stampSchema(true);
1494
1501
  });
1495
1502
  // Every table the reset dropped changed (I1 eviction-shaped).
1496
1503
  for (const table of changed) batch.table(table);
@@ -1574,7 +1581,7 @@ export class SyncClient {
1574
1581
  /** §2.1 reset after the server reports a different log continuity. */
1575
1582
  #runLogEpochReset(logEpoch: string): string[] {
1576
1583
  if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
1577
- this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
1584
+ setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
1578
1585
  this.#emitSyncNeeded('startup');
1579
1586
  return [];
1580
1587
  }
@@ -1688,9 +1695,7 @@ export class SyncClient {
1688
1695
  /** Host-owned transport policy; the local replica remains available. */
1689
1696
  setTransportEnabled(enabled: boolean): void {
1690
1697
  this.#requireStarted();
1691
- if (typeof enabled !== 'boolean')
1692
- throw invalidRequest('transportEnabled must be a boolean');
1693
- if (this.#transportEnabled === enabled) return;
1698
+ if (this.#transportEnabled === transportFlag(enabled)) return;
1694
1699
  this.#transportEnabled = enabled;
1695
1700
  this.#transportEpoch += 1;
1696
1701
  this.#disarm();
@@ -1853,26 +1858,18 @@ export class SyncClient {
1853
1858
  */
1854
1859
  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
1855
1860
  querySnapshot(spec: QueryReadSpec): QuerySnapshot {
1856
- const read = this.#readSnapshot({
1857
- statements: [
1858
- {
1859
- sql: spec.sql,
1860
- ...(spec.params !== undefined ? { params: spec.params } : {}),
1861
- },
1862
- ],
1863
- ...(spec.coverage !== undefined ? { coverage: spec.coverage } : {}),
1864
- ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
1865
- });
1866
- const rows = read.queries[0];
1867
- if (read.queries.length !== 1 || rows === undefined) {
1868
- throw new ClientSyncError(
1869
- 'client.failed',
1870
- 'querySnapshot produced no statement result',
1871
- );
1872
- }
1861
+ // A statement reads only `sql` and `params`; one statement yields one
1862
+ // result.
1863
+ const read = this.#readSnapshot(
1864
+ definedObject({
1865
+ statements: [spec],
1866
+ coverage: spec.coverage,
1867
+ owner: spec.owner,
1868
+ }),
1869
+ );
1873
1870
  return {
1874
1871
  revision: read.revision,
1875
- rows,
1872
+ rows: read.queries[0]!,
1876
1873
  coverage: read.coverage,
1877
1874
  };
1878
1875
  }
@@ -2130,17 +2127,12 @@ export class SyncClient {
2130
2127
  return withPreviousVersionContainer(this.#db, readPreviousVersionContainer);
2131
2128
  }
2132
2129
 
2133
- /** RFC 0005 A2: presence for `statusSnapshot()`, without creating the file. */
2134
- #previousVersionStatus(): { present: boolean; createdAtMs?: number } {
2135
- const record = this.#readPreviousVersionRecord();
2136
- if (record === undefined) return { present: this.#previousVersionExists() };
2137
- return { present: true, createdAtMs: record.createdAtMs };
2138
- }
2139
-
2140
2130
  #previousVersionLeaseInactive(nowMs: number): boolean {
2141
2131
  const lease = this.#leaseState;
2142
- if (lease?.errorCode !== undefined) return true;
2143
- return lease?.expiresAtMs !== undefined && lease.expiresAtMs <= nowMs;
2132
+ return (
2133
+ lease?.errorCode !== undefined ||
2134
+ (lease?.expiresAtMs ?? Infinity) <= nowMs
2135
+ );
2144
2136
  }
2145
2137
 
2146
2138
  /**
@@ -2309,12 +2301,13 @@ export class SyncClient {
2309
2301
  ? 'offline'
2310
2302
  : round?.status === 'succeeded'
2311
2303
  ? 'online'
2312
- : round?.status === 'failed' &&
2313
- (round.causeKind === 'network' || round.causeKind === 'connect')
2314
- ? 'offline'
2315
- : round?.status === 'failed' && round.httpStatus !== undefined
2316
- ? 'online'
2317
- : 'unknown';
2304
+ : round?.status !== 'failed'
2305
+ ? 'unknown'
2306
+ : round.causeKind === 'network' || round.causeKind === 'connect'
2307
+ ? 'offline'
2308
+ : round.httpStatus !== undefined
2309
+ ? 'online'
2310
+ : 'unknown';
2318
2311
  return definedObject({
2319
2312
  version: CLIENT_DIAGNOSTICS_VERSION,
2320
2313
  capturedAtMs,
@@ -2352,7 +2345,7 @@ export class SyncClient {
2352
2345
  ),
2353
2346
  ].sort(),
2354
2347
  },
2355
- activeUnits: registered.filter((unit) => unit.status === 'active').length,
2348
+ activeUnits: registered.length - units.revoked - units.failed,
2356
2349
  replicaCursor: replicaCursor(this.#db),
2357
2350
  lastRound: this.#lastRound,
2358
2351
  lastChange: this.#lastChange,
@@ -2379,12 +2372,9 @@ export class SyncClient {
2379
2372
 
2380
2373
  #diagnosticStorage(): ClientDiagnosticsStorage {
2381
2374
  try {
2382
- const pageCount = Number(
2383
- this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0,
2384
- );
2385
- const pageSize = Number(
2386
- this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0,
2387
- );
2375
+ const pragma = (name: string) =>
2376
+ Number(this.#db.query(`PRAGMA ${name}`)[0]?.[name] ?? 0);
2377
+ const databaseBytes = pragma('page_count') * pragma('page_size');
2388
2378
  // One statement for the outbox and outcome-journal sums keeps the
2389
2379
  // snapshot at its pre-version-4 statement count.
2390
2380
  const sums = this.#db.query(
@@ -2402,7 +2392,7 @@ export class SyncClient {
2402
2392
  const size = (value: unknown) => Math.max(0, Number(value ?? 0));
2403
2393
  return {
2404
2394
  status: pressure ? 'pressure' : 'healthy',
2405
- databaseBytesApprox: Math.max(0, pageCount * pageSize),
2395
+ databaseBytesApprox: Math.max(0, databaseBytes),
2406
2396
  pendingOutboxBytesApprox: size(sums?.outbox),
2407
2397
  retainedOutcomeBytesApprox: size(sums?.bytes),
2408
2398
  retainedOutcomeEntries: size(sums?.entries),
@@ -2451,6 +2441,8 @@ export class SyncClient {
2451
2441
  }
2452
2442
 
2453
2443
  #statusSnapshot(outboxCount?: number): SyncStatusSnapshot {
2444
+ // RFC 0005 A2: previous-version presence, without creating the file.
2445
+ const record = this.#readPreviousVersionRecord();
2454
2446
  return {
2455
2447
  currentSchemaVersion: this.#config.schema.version,
2456
2448
  outbox: outboxCount ?? countOutbox(this.#db),
@@ -2458,7 +2450,10 @@ export class SyncClient {
2458
2450
  leaseState: this.#leaseState,
2459
2451
  schemaFloor: this.#schemaFloor,
2460
2452
  syncNeeded: this.#needsPull,
2461
- previousVersionContext: this.#previousVersionStatus(),
2453
+ previousVersionContext:
2454
+ record === undefined
2455
+ ? { present: this.#previousVersionExists() }
2456
+ : { present: true, createdAtMs: record.createdAtMs },
2462
2457
  securityLifecycle: this.#securityLifecycle,
2463
2458
  };
2464
2459
  }
@@ -2507,14 +2502,14 @@ export class SyncClient {
2507
2502
  onRollback?.(error);
2508
2503
  throw error;
2509
2504
  }
2510
- if (revision !== undefined) {
2511
- const event = batch.finish(revision, status);
2505
+ const publish = () => {
2506
+ const event = batch.finish(revision!, status);
2512
2507
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
2513
2508
  const windows = [
2514
2509
  ...new Set(event.windows.map((entry) => entry.baseKey.split('\0')[0]!)),
2515
2510
  ];
2516
2511
  this.#lastChange = {
2517
- revision: revision.toString(),
2512
+ revision: revision!.toString(),
2518
2513
  recordedAtMs: this.#now(),
2519
2514
  tables: tables.slice(0, MAX_DIAGNOSTIC_DOMAINS),
2520
2515
  windows: windows.slice(0, MAX_DIAGNOSTIC_DOMAINS),
@@ -2530,7 +2525,10 @@ export class SyncClient {
2530
2525
  const legacy = invalidationFromChange(event);
2531
2526
  if (legacy !== undefined) this.#invalidation.emit(legacy);
2532
2527
  this.#emitDiagnostics();
2533
- }
2528
+ };
2529
+ if (revision !== undefined)
2530
+ if (this.#held) this.#held.push(publish);
2531
+ else publish();
2534
2532
  return result;
2535
2533
  }
2536
2534
 
@@ -2580,28 +2578,23 @@ export class SyncClient {
2580
2578
  options?: { readonly mediaType?: string; readonly name?: string },
2581
2579
  ): Promise<BlobRef> {
2582
2580
  const owned = bytes.slice();
2583
- return this.#runProtectedAsync(() => this.#uploadBlob(owned, options));
2584
- }
2585
-
2586
- async #uploadBlob(
2587
- bytes: Uint8Array,
2588
- options?: { readonly mediaType?: string; readonly name?: string },
2589
- ): Promise<BlobRef> {
2590
- if (this.#config.blobs === undefined) {
2591
- throw invalidRequest('uploadBlob requires a blob transport');
2592
- }
2593
- const blobId = await computeBlobId(bytes);
2594
- const nowMs = this.#now();
2595
- this.#db.transaction(() => {
2596
- putCachedBlob(this.#db, blobId, bytes, nowMs, options?.mediaType);
2597
- recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
2598
- });
2599
- this.#enforceBlobCacheCap();
2600
- return definedObject({
2601
- blobId,
2602
- byteLength: bytes.length,
2603
- mediaType: options?.mediaType,
2604
- name: options?.name,
2581
+ return this.#runProtectedAsync(async () => {
2582
+ if (this.#config.blobs === undefined) {
2583
+ throw invalidRequest('uploadBlob requires a blob transport');
2584
+ }
2585
+ const blobId = await computeBlobId(owned);
2586
+ const nowMs = this.#now();
2587
+ this.#db.transaction(() => {
2588
+ putCachedBlob(this.#db, blobId, owned, nowMs, options?.mediaType);
2589
+ recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
2590
+ });
2591
+ this.#enforceBlobCacheCap();
2592
+ return definedObject({
2593
+ blobId,
2594
+ byteLength: owned.length,
2595
+ mediaType: options?.mediaType,
2596
+ name: options?.name,
2597
+ });
2605
2598
  });
2606
2599
  }
2607
2600
 
@@ -2617,65 +2610,63 @@ export class SyncClient {
2617
2610
  * Accepts a raw `blob_ref` column string or a bare `blobId`.
2618
2611
  */
2619
2612
  fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
2620
- return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
2621
- }
2622
-
2623
- async #fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
2624
- // A BlobRef declares the size that caps the download (§5.9.5); a bare
2625
- // blobId declares none.
2626
- const ref = blobIdOrRef.startsWith('sha256:')
2627
- ? undefined
2628
- : parseBlobRef(blobIdOrRef);
2629
- const blobId = ref?.blobId ?? blobIdOrRef;
2630
- const cached = getCachedBlob(this.#db, blobId);
2631
- if (cached !== undefined) return cached;
2632
- const transport = this.#config.blobs;
2633
- if (transport === undefined) {
2634
- throw invalidRequest('fetchBlob requires a blob transport');
2635
- }
2636
- // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
2637
- // presign configured) a signed url the client fetches directly. On a url
2638
- // arm the client MUST NOT attach host auth and MUST NOT fall through:
2639
- // failure => re-request, the caller's next fetchBlob mints a fresh url.
2640
- this.#requireTransport();
2641
- const response = await transport.download(blobId, ref?.byteLength);
2642
- let bytes: Uint8Array;
2643
- if (response.kind === 'url') {
2644
- if (transport.fetchUrl === undefined) {
2645
- throw invalidRequest('blob transport cannot fetch urls');
2613
+ return this.#runProtectedAsync(async () => {
2614
+ // A BlobRef declares the size that caps the download (§5.9.5); a bare
2615
+ // blobId declares none.
2616
+ const ref = blobIdOrRef.startsWith('sha256:')
2617
+ ? undefined
2618
+ : parseBlobRef(blobIdOrRef);
2619
+ const blobId = ref?.blobId ?? blobIdOrRef;
2620
+ const cached = getCachedBlob(this.#db, blobId);
2621
+ if (cached !== undefined) return cached;
2622
+ const transport = this.#config.blobs;
2623
+ if (transport === undefined) {
2624
+ throw invalidRequest('fetchBlob requires a blob transport');
2646
2625
  }
2647
- if (
2648
- response.urlExpiresAtMs !== undefined &&
2649
- response.urlExpiresAtMs <= this.#now()
2650
- ) {
2651
- // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
2652
- throw new ClientSyncError(
2653
- 'sync.segment_expired',
2654
- 'blob url expired before fetch',
2655
- true,
2656
- );
2626
+ // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
2627
+ // presign configured) a signed url the client fetches directly. On a url
2628
+ // arm the client MUST NOT attach host auth and MUST NOT fall through:
2629
+ // failure => re-request, the caller's next fetchBlob mints a fresh url.
2630
+ this.#requireTransport();
2631
+ const response = await transport.download(blobId, ref?.byteLength);
2632
+ let bytes: Uint8Array;
2633
+ if (response.kind === 'url') {
2634
+ if (transport.fetchUrl === undefined) {
2635
+ throw invalidRequest('blob transport cannot fetch urls');
2636
+ }
2637
+ if (
2638
+ response.urlExpiresAtMs !== undefined &&
2639
+ response.urlExpiresAtMs <= this.#now()
2640
+ ) {
2641
+ // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
2642
+ throw new ClientSyncError(
2643
+ 'sync.segment_expired',
2644
+ 'blob url expired before fetch',
2645
+ true,
2646
+ );
2647
+ }
2648
+ bytes = await transport.fetchUrl(response.url, ref?.byteLength);
2649
+ } else {
2650
+ bytes = response.bytes;
2657
2651
  }
2658
- bytes = await transport.fetchUrl(response.url, ref?.byteLength);
2659
- } else {
2660
- bytes = response.bytes;
2661
- }
2662
- // §5.9.5 inherits §5.1: the declared size caps the body and the content
2663
- // address must match. On the url path either failure invalidates the
2664
- // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
2665
- if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
2666
- throw invalidRequest('blob exceeds its byteLength');
2667
- }
2668
- if ((await computeBlobId(bytes)) !== blobId) {
2669
- throw invalidRequest('blob content address mismatch');
2670
- }
2671
- putCachedBlob(this.#db, blobId, bytes, this.#now());
2672
- this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
2673
- this.#enforceBlobCacheCap();
2674
- const stored = getCachedBlob(this.#db, blobId);
2675
- if (stored === undefined) {
2676
- throw invalidRequest('blob cache write failed');
2677
- }
2678
- return stored;
2652
+ // §5.9.5 inherits §5.1: the declared size caps the body and the content
2653
+ // address must match. On the url path either failure invalidates the
2654
+ // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
2655
+ if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
2656
+ throw invalidRequest('blob exceeds its byteLength');
2657
+ }
2658
+ if ((await computeBlobId(bytes)) !== blobId) {
2659
+ throw invalidRequest('blob content address mismatch');
2660
+ }
2661
+ putCachedBlob(this.#db, blobId, bytes, this.#now());
2662
+ this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
2663
+ this.#enforceBlobCacheCap();
2664
+ const stored = getCachedBlob(this.#db, blobId);
2665
+ if (stored === undefined) {
2666
+ throw invalidRequest('blob cache write failed');
2667
+ }
2668
+ return stored;
2669
+ });
2679
2670
  }
2680
2671
 
2681
2672
  /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
@@ -3186,12 +3177,10 @@ export class SyncClient {
3186
3177
  if (resolved === undefined) {
3187
3178
  throw outcomeNotFound();
3188
3179
  }
3189
- this.#conflicts = this.#conflicts.filter(
3190
- (record) => record.clientCommitId !== input.clientCommitId,
3191
- );
3192
- this.#rejections = this.#rejections.filter(
3193
- (record) => record.clientCommitId !== input.clientCommitId,
3194
- );
3180
+ const kept = (record: { readonly clientCommitId: string }) =>
3181
+ record.clientCommitId !== input.clientCommitId;
3182
+ this.#conflicts = this.#conflicts.filter(kept);
3183
+ this.#rejections = this.#rejections.filter(kept);
3195
3184
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
3196
3185
  this.#replayOutbox(scope, false);
3197
3186
  for (const operation of current.operations ?? [])
@@ -3427,21 +3416,25 @@ export class SyncClient {
3427
3416
  const baseKey = windowBaseKey(base);
3428
3417
  const wanted = new Set(units);
3429
3418
  const live = loadWindowUnits(this.#db, baseKey);
3430
- // §7.8: a widen registers like `subscribe` and never waits for a
3431
- // running round.
3432
- for (const value of wanted) {
3433
- if (live.some((entry) => entry.value === value)) continue;
3419
+ // §7.8: a widen registers its values like `subscribeMany`, in one
3420
+ // transaction, and never waits for a running round.
3421
+ const added = [...wanted].filter(
3422
+ (value) => !live.some((entry) => entry.value === value),
3423
+ );
3424
+ if (added.length > 0) {
3434
3425
  this.#applyBatch((batch) => {
3435
- const { id, changed: registered } = this.#holdUnit(
3436
- windowUnitScopes(base, value),
3437
- false,
3438
- );
3439
- this.#db.exec(
3440
- `INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`,
3441
- [baseKey, value, id],
3442
- );
3443
- this.#needsPull ||= registered;
3444
- batch.window(baseKey, value);
3426
+ for (const value of added) {
3427
+ const { id, changed: registered } = this.#holdUnit(
3428
+ windowUnitScopes(base, value),
3429
+ false,
3430
+ );
3431
+ this.#db.exec(
3432
+ `INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`,
3433
+ [baseKey, value, id],
3434
+ );
3435
+ this.#needsPull ||= registered;
3436
+ batch.window(baseKey, value);
3437
+ }
3445
3438
  batch.status();
3446
3439
  });
3447
3440
  changed = true;
@@ -3811,9 +3804,7 @@ export class SyncClient {
3811
3804
  );
3812
3805
  for (const operation of operations) {
3813
3806
  if (operation.op !== 'upsert') continue;
3814
- const table = this.#schema.tables.get(operation.table);
3815
- if (table === undefined) continue;
3816
- for (const column of table.columns) {
3807
+ for (const column of this.#table(operation.table).columns) {
3817
3808
  if (column.type !== 'blob_ref') continue;
3818
3809
  const raw = operation.values?.[column.name];
3819
3810
  if (typeof raw !== 'string') continue;
@@ -4220,13 +4211,6 @@ export class SyncClient {
4220
4211
  if (next.errorCode !== undefined) this.#discardPreviousVersion();
4221
4212
  }
4222
4213
 
4223
- /** The request-level lease error codes (§7.3.4): stop-and-surface. */
4224
- #isLeaseErrorCode(code: string): boolean {
4225
- return (
4226
- code === 'sync.auth_lease_required' || code === 'sync.auth_lease_revoked'
4227
- );
4228
- }
4229
-
4230
4214
  /**
4231
4215
  * §7.4.4: encode every pending outbox commit with the current codec. A
4232
4216
  * commit that cannot re-encode under the new schema (an
@@ -4400,7 +4384,7 @@ export class SyncClient {
4400
4384
  kind,
4401
4385
  limit,
4402
4386
  size,
4403
- ...(clientCommitId !== undefined ? { clientCommitId } : {}),
4387
+ clientCommitId,
4404
4388
  }),
4405
4389
  );
4406
4390
  }
@@ -4584,7 +4568,20 @@ export class SyncClient {
4584
4568
  this.#lastRound = {
4585
4569
  status: 'succeeded',
4586
4570
  ...round(),
4587
- counters: this.#diagnosticRoundCounters(summary),
4571
+ counters: {
4572
+ pushed: summary.pushed,
4573
+ applied: summary.applied.length,
4574
+ rejected: summary.rejected.length,
4575
+ retryable: summary.retryable.length,
4576
+ conflicts: summary.conflicts.length,
4577
+ commitsApplied: summary.commitsApplied,
4578
+ segmentRowsApplied: summary.segmentRowsApplied,
4579
+ bootstrapping: summary.bootstrapping.length,
4580
+ resets: summary.resets.length,
4581
+ revoked: summary.revoked.length,
4582
+ failed: summary.failed.length,
4583
+ deferredCommits: summary.deferredCommits ?? 0,
4584
+ },
4588
4585
  };
4589
4586
  this.#emitDiagnostics();
4590
4587
  return summary;
@@ -4654,23 +4651,6 @@ export class SyncClient {
4654
4651
  });
4655
4652
  }
4656
4653
 
4657
- #diagnosticRoundCounters(summary: SyncSummary): DiagnosticRoundCounters {
4658
- return {
4659
- pushed: summary.pushed,
4660
- applied: summary.applied.length,
4661
- rejected: summary.rejected.length,
4662
- retryable: summary.retryable.length,
4663
- conflicts: summary.conflicts.length,
4664
- commitsApplied: summary.commitsApplied,
4665
- segmentRowsApplied: summary.segmentRowsApplied,
4666
- bootstrapping: summary.bootstrapping.length,
4667
- resets: summary.resets.length,
4668
- revoked: summary.revoked.length,
4669
- failed: summary.failed.length,
4670
- deferredCommits: summary.deferredCommits ?? 0,
4671
- };
4672
- }
4673
-
4674
4654
  #diagnosticCode(code: string): string {
4675
4655
  return isStableCode(code) ? code : 'client.unknown_failure';
4676
4656
  }
@@ -4731,7 +4711,13 @@ export class SyncClient {
4731
4711
  frameBytes,
4732
4712
  deferred: encodedDeferred,
4733
4713
  } = logEpoch === undefined
4734
- ? { pushFrames: [], outbox: [], frameBytes: [], deferred: 0 }
4714
+ ? {
4715
+ pushFrames: [],
4716
+ outbox: [],
4717
+ frameBytes: [],
4718
+ // §2.1: the outbox waits for the next, epoch-bound request.
4719
+ deferred: countOutbox(this.#db),
4720
+ }
4735
4721
  : await this.#encodeOutboxForPush(header, pull, byteCap);
4736
4722
  // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
4737
4723
  // them, so the server-side existence check (§6.6) passes.
@@ -4774,6 +4760,8 @@ export class SyncClient {
4774
4760
  ...(report !== undefined
4775
4761
  ? [{ type: 'ROUND_FAILURE' as const, code: report }]
4776
4762
  : []),
4763
+ // §2.1: a replica without an epoch holds nothing bound to one.
4764
+ ...(logEpoch === undefined ? [{ type: 'ADOPT_EPOCH' as const }] : []),
4777
4765
  pull,
4778
4766
  ...(travels
4779
4767
  ? registered.map(
@@ -4867,8 +4855,20 @@ export class SyncClient {
4867
4855
  } catch (caught) {
4868
4856
  // §1.5: a round that ended without a complete, decodable response is a
4869
4857
  // failure the server could not see — keep its code for the next request.
4870
- const unseen = this.#unseenRoundFailureCode(caught);
4871
- if (unseen !== undefined) this.#roundFailureCode = unseen;
4858
+ // An undecodable/truncated body, a rejected fetch, a failed body read,
4859
+ // or a socket round lost mid-flight; an HTTP-status rejection and an
4860
+ // in-band `ERROR` frame were recorded by the server and stay
4861
+ // unreported. The frame carries only codes matching its grammar; a
4862
+ // code that does not match would turn the whole request into a decode
4863
+ // error.
4864
+ if (
4865
+ (caught instanceof DecodeError ||
4866
+ (caught instanceof ClientSyncError &&
4867
+ caught.code === 'sync.transport_failed' &&
4868
+ caught.details?.['causeKind'] !== 'status')) &&
4869
+ isRoundFailureCode(caught.code)
4870
+ )
4871
+ this.#roundFailureCode = caught.code;
4872
4872
  // §7.8: a round the drive deadline aborted ends with the deadline's
4873
4873
  // error, whichever transport call observed the abort.
4874
4874
  const error: unknown = signal?.aborted ? signal.reason : caught;
@@ -4877,8 +4877,12 @@ export class SyncClient {
4877
4877
  // silent retry: the app drives recovery to a live resolver. The
4878
4878
  // error may arrive as a ClientSyncError or as a transport error
4879
4879
  // carrying the server's `.code` (HTTP-JSON / loopback surface, §1.1).
4880
+ // The request-level lease error codes (§7.3.4).
4880
4881
  const code = (error as { code?: unknown }).code;
4881
- if (typeof code === 'string' && this.#isLeaseErrorCode(code)) {
4882
+ if (
4883
+ code === 'sync.auth_lease_required' ||
4884
+ code === 'sync.auth_lease_revoked'
4885
+ ) {
4882
4886
  this.#setLeaseState({
4883
4887
  ...(this.#leaseState ?? {}),
4884
4888
  errorCode: code,
@@ -4956,17 +4960,26 @@ export class SyncClient {
4956
4960
  )
4957
4961
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
4958
4962
  const skipEmpty = typeof options === 'object' && options.skipEmpty === true;
4959
- const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}`;
4963
+ const coalesceMs = (typeof options === 'object' && options.coalesceMs) || 0;
4964
+ // NaN and Infinity fail too.
4965
+ if (!(coalesceMs >= 0 && coalesceMs < Number.POSITIVE_INFINITY))
4966
+ throw invalidRequest('coalesceMs must be a non-negative finite number');
4967
+ const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}:${coalesceMs}`;
4960
4968
  const pending = this.#syncIdlePending.get(key);
4961
4969
  if (pending !== undefined) return pending;
4962
4970
  const previous = this.#syncIdleTail;
4963
4971
  let drive: Promise<SyncIdleResult>;
4964
4972
  if (previous === undefined) {
4965
- drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4973
+ drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty, coalesceMs);
4966
4974
  } else {
4967
4975
  drive = previous.then(() => {
4968
4976
  this.#syncIdlePending.delete(key);
4969
- return this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4977
+ return this.#syncIdleRounds(
4978
+ maxRounds,
4979
+ timeoutMs,
4980
+ skipEmpty,
4981
+ coalesceMs,
4982
+ );
4970
4983
  });
4971
4984
  this.#syncIdlePending.set(key, drive);
4972
4985
  }
@@ -4986,6 +4999,7 @@ export class SyncClient {
4986
4999
  maxRounds: number | undefined,
4987
5000
  timeoutMs: number,
4988
5001
  skipEmpty: boolean,
5002
+ coalesceMs: number,
4989
5003
  ): Promise<SyncIdleResult> {
4990
5004
  const budget = maxRounds ?? 20;
4991
5005
  const aggregate = {
@@ -4999,7 +5013,7 @@ export class SyncClient {
4999
5013
  return {
5000
5014
  ...summary,
5001
5015
  ...(deferredCommits > 0 ? { deferredCommits } : {}),
5002
- ...(schemaFloor !== undefined ? { schemaFloor } : {}),
5016
+ ...definedObject({ schemaFloor }),
5003
5017
  budgetExhausted,
5004
5018
  };
5005
5019
  };
@@ -5117,6 +5131,18 @@ export class SyncClient {
5117
5131
  continue;
5118
5132
  return result(false);
5119
5133
  }
5134
+ // §8.4: the next round only confirms idle; claims and writes made in
5135
+ // reaction to the data this round applied join it.
5136
+ if (
5137
+ coalesceMs > 0 &&
5138
+ round + 1 < budget &&
5139
+ last.bootstrapping.length === 0 &&
5140
+ !aggregate.deferredCommits &&
5141
+ !this.#needsPull
5142
+ )
5143
+ await new Promise<void>((resolve) => {
5144
+ this.#schedule(resolve, coalesceMs);
5145
+ });
5120
5146
  }
5121
5147
  return result(true);
5122
5148
  }
@@ -5164,7 +5190,12 @@ export class SyncClient {
5164
5190
  if (this.#realtimePolicy === 'required') {
5165
5191
  // §8.8: the designated realtime path is down. Refuse the round; the
5166
5192
  // HTTP binding is not an alternative for a `required` client.
5167
- throw this.#realtimeUnavailableError();
5193
+ this.#realtimeRetryDelayMs = this.#retryDelayMs;
5194
+ throw new RealtimeUnavailableError(
5195
+ this.#realtimeState,
5196
+ this.#realtimeReasonCode,
5197
+ this.#retryDelayMs,
5198
+ );
5168
5199
  }
5169
5200
  return Promise.resolve()
5170
5201
  .then(() => this.#config.transport(request, signal))
@@ -5181,27 +5212,6 @@ export class SyncClient {
5181
5212
  });
5182
5213
  }
5183
5214
 
5184
- /**
5185
- * §1.5: the code to report for a round that ended without a complete,
5186
- * decodable response — an undecodable/truncated body, a rejected fetch, a
5187
- * failed body read, or a socket round lost mid-flight. An HTTP-status
5188
- * rejection and an in-band `ERROR` frame were recorded by the server and
5189
- * stay unreported.
5190
- */
5191
- #unseenRoundFailureCode(error: unknown): string | undefined {
5192
- const code =
5193
- error instanceof DecodeError
5194
- ? error.code
5195
- : error instanceof ClientSyncError &&
5196
- error.code === 'sync.transport_failed' &&
5197
- error.details?.['causeKind'] !== 'status'
5198
- ? error.code
5199
- : undefined;
5200
- // §1.5: the frame carries only codes matching its grammar; a code that
5201
- // does not match would turn the whole request into a decode error.
5202
- return code !== undefined && isRoundFailureCode(code) ? code : undefined;
5203
- }
5204
-
5205
5215
  /** Abort the in-flight socket round (socket closed or disconnected). */
5206
5216
  #abortPendingRound(reason: string | ClientSyncError): void {
5207
5217
  const round = this.#pendingRound;
@@ -5231,15 +5241,6 @@ export class SyncClient {
5231
5241
  this.#emitDiagnostics();
5232
5242
  }
5233
5243
 
5234
- #realtimeUnavailableError(): RealtimeUnavailableError {
5235
- this.#realtimeRetryDelayMs = this.#retryDelayMs;
5236
- return new RealtimeUnavailableError(
5237
- this.#realtimeState,
5238
- this.#realtimeReasonCode,
5239
- this.#retryDelayMs,
5240
- );
5241
- }
5242
-
5243
5244
  connectRealtime(): Promise<void> {
5244
5245
  this.#requireActive();
5245
5246
  this.#requireTransport();
@@ -5527,12 +5528,6 @@ export class SyncClient {
5527
5528
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
5528
5529
  }
5529
5530
 
5530
- /** §8.2: after a pull round, ack the replica cursor while it is `>= 0`. */
5531
- #ackAfterPull(): void {
5532
- const cursor = replicaCursor(this.#db);
5533
- if (this.#socket !== undefined && cursor >= 0) this.#sendAck(cursor);
5534
- }
5535
-
5536
5531
  // -- response processing ------------------------------------------------------
5537
5532
 
5538
5533
  /**
@@ -5599,7 +5594,7 @@ export class SyncClient {
5599
5594
  if (header.resetRequired) {
5600
5595
  if (mode !== 'pull' || message.frames.length !== 1) {
5601
5596
  throw invalidHostResponse(
5602
- 'a log-epoch reset response must contain only RESP_HEADER',
5597
+ 'a log-epoch reset response carries frames after RESP_HEADER',
5603
5598
  );
5604
5599
  }
5605
5600
  return {
@@ -5608,7 +5603,10 @@ export class SyncClient {
5608
5603
  bootstrapping: [],
5609
5604
  };
5610
5605
  }
5611
- if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
5606
+ // §2.1 adoption: the epoch is stored before any section applies.
5607
+ if (currentLogEpoch === undefined) {
5608
+ setMeta(this.#db, LOG_EPOCH_META_KEY, header.logEpoch);
5609
+ } else if (currentLogEpoch !== header.logEpoch) {
5612
5610
  throw invalidHostResponse(
5613
5611
  'the server changed logEpoch without requiring a reset',
5614
5612
  );
@@ -5686,13 +5684,19 @@ export class SyncClient {
5686
5684
  prefetch();
5687
5685
  }
5688
5686
 
5689
- // Each durable observer transaction emits its own revisioned batch.
5690
- // Async decrypt/download work happens outside SQLite transactions.
5691
- this.#beginDiagnosticsDeferral();
5692
- try {
5687
+ // §1.4 rule 4: the frames of unit sections run in coalesced apply
5688
+ // transactions of at most 1,024 rows, each frame or block in its own
5689
+ // savepoint with its own revision, published after the COMMIT; the host
5690
+ // yields to local reads after each COMMIT. Every other frame runs outside
5691
+ // one, and downloads, decryption, images and COMMIT frames are awaited
5692
+ // outside any transaction.
5693
+ const steps = function* (
5694
+ this: SyncClient,
5695
+ ): Generator<ApplyStep, void, unknown> {
5693
5696
  for (let index = 1; index < message.frames.length; index += 1) {
5694
5697
  const frame = message.frames[index];
5695
5698
  if (frame === undefined) break;
5699
+ if (!/^(SUB|SEGMENT|UNIT)_/.test(frame.type)) yield -1;
5696
5700
  switch (frame.type) {
5697
5701
  case 'RESP_HEADER':
5698
5702
  break;
@@ -5842,14 +5846,16 @@ export class SyncClient {
5842
5846
  const pending = prefetched.get(frame);
5843
5847
  prefetched.delete(frame);
5844
5848
  if (pending !== undefined) reporting = frame;
5849
+ const { scopes } = section.unit;
5845
5850
  try {
5846
- bytes = await (pending ??
5851
+ bytes = (yield () =>
5852
+ pending ??
5847
5853
  this.#downloadSegment(
5848
5854
  frame,
5849
- section.unit.scopes,
5855
+ scopes,
5850
5856
  (bytesReceived) => this.#progress.update({ bytesReceived }),
5851
5857
  signal,
5852
- ));
5858
+ )) as Uint8Array;
5853
5859
  } catch (error) {
5854
5860
  // §5.5: access changed since the response. The unit stays
5855
5861
  // catching up with its cursor unpersisted, and the next
@@ -5878,7 +5884,7 @@ export class SyncClient {
5878
5884
  0,
5879
5885
  ),
5880
5886
  });
5881
- await this.#applySegmentOrFail(
5887
+ yield* this.#applySegmentOrFail(
5882
5888
  section,
5883
5889
  summary,
5884
5890
  image?.table ?? segment!.table,
@@ -5892,27 +5898,27 @@ export class SyncClient {
5892
5898
  ? image.rowCount > 0
5893
5899
  : segment!.blocks.some((block) => block.length > 0),
5894
5900
  resetEpoch,
5895
- image !== undefined,
5896
5901
  );
5897
5902
  return image !== undefined
5898
- ? applySqliteSegment(
5899
- this.#db,
5900
- this.#schema,
5901
- table,
5902
- bytes,
5903
- image,
5904
- {
5905
- ...options,
5906
- appliedRows,
5907
- onChunk: (rows) =>
5908
- recordAppliedRows(
5909
- this.#db,
5910
- unitId,
5911
- image.segmentId,
5912
- rows,
5913
- ),
5914
- },
5915
- )
5903
+ ? () =>
5904
+ applySqliteSegment(
5905
+ this.#db,
5906
+ this.#schema,
5907
+ table,
5908
+ bytes,
5909
+ image,
5910
+ {
5911
+ ...options,
5912
+ appliedRows,
5913
+ onChunk: (rows) =>
5914
+ recordAppliedRows(
5915
+ this.#db,
5916
+ unitId,
5917
+ image.segmentId,
5918
+ rows,
5919
+ ),
5920
+ },
5921
+ )
5916
5922
  : applyRowsSegment(
5917
5923
  this.#db,
5918
5924
  this.#schema,
@@ -6004,7 +6010,8 @@ export class SyncClient {
6004
6010
  );
6005
6011
  });
6006
6012
  if (changes.length > 0)
6007
- await this.#applyCommit({ ...frame, changes }, summary, mode);
6013
+ yield () =>
6014
+ this.#applyCommit({ ...frame, changes }, summary, mode);
6008
6015
  break;
6009
6016
  }
6010
6017
  case 'LIVE_END': {
@@ -6096,6 +6103,52 @@ export class SyncClient {
6096
6103
  }
6097
6104
  if (errorFrame !== undefined) break;
6098
6105
  }
6106
+ }.call(this);
6107
+ this.#beginDiagnosticsDeferral();
6108
+ try {
6109
+ for (let step = steps.next(); !step.done;) {
6110
+ const work = step.value;
6111
+ if (typeof work === 'function') {
6112
+ try {
6113
+ step = steps.next(await work());
6114
+ } catch (error) {
6115
+ step = steps.throw(error);
6116
+ }
6117
+ } else if (work < 0) step = steps.next();
6118
+ else {
6119
+ const held: (() => void)[] = (this.#held = []);
6120
+ const rejections = this.#rejections.length;
6121
+ let failure: { error: unknown } | undefined;
6122
+ try {
6123
+ failure = this.#db.transaction(() => {
6124
+ try {
6125
+ for (let rows = work; ;) {
6126
+ step = steps.next();
6127
+ const next = step.value;
6128
+ if (
6129
+ typeof next !== 'number' ||
6130
+ next < 0 ||
6131
+ (rows > 0 && rows + next > 1024)
6132
+ )
6133
+ return undefined;
6134
+ rows += next;
6135
+ }
6136
+ } catch (error) {
6137
+ // §1.4 rule 5: the frames before the failing one commit.
6138
+ return { error };
6139
+ }
6140
+ });
6141
+ } catch (error) {
6142
+ this.#rejections.length = rejections;
6143
+ throw error;
6144
+ } finally {
6145
+ this.#held = undefined;
6146
+ }
6147
+ for (const publish of held) publish();
6148
+ if (failure) throw failure.error;
6149
+ await yieldToHost();
6150
+ }
6151
+ }
6099
6152
  } finally {
6100
6153
  this.#endDiagnosticsDeferral();
6101
6154
  }
@@ -6109,7 +6162,9 @@ export class SyncClient {
6109
6162
  this.#emitSyncNeeded('catchup-required');
6110
6163
  }
6111
6164
  } else {
6112
- this.#ackAfterPull();
6165
+ // §8.2: after a pull round, ack the replica cursor while it is `>= 0`.
6166
+ const cursor = replicaCursor(this.#db);
6167
+ if (this.#socket !== undefined && cursor >= 0) this.#sendAck(cursor);
6113
6168
  }
6114
6169
 
6115
6170
  const catchingUp = loadUnits(this.#db)
@@ -6314,7 +6369,23 @@ export class SyncClient {
6314
6369
  this.#encryption,
6315
6370
  (fn) =>
6316
6371
  this.#applyBatch((batch) => {
6317
- this.#recordCommitChanges(batch, frame);
6372
+ // Record before + after scope keys while the transaction is open.
6373
+ for (const change of frame.changes) {
6374
+ const tableName = frame.tables[change.tableIndex];
6375
+ if (tableName === undefined) continue;
6376
+ const table = this.#schema.tables.get(tableName);
6377
+ if (table === undefined) continue;
6378
+ let precise = this.#recordStoredRowScopes(
6379
+ batch,
6380
+ table,
6381
+ change.rowId,
6382
+ );
6383
+ for (const variable of Object.keys(change.scopes)) {
6384
+ if (table.scopePrefixByVariable.has(variable)) precise = true;
6385
+ }
6386
+ batch.changeScopes(table, change.scopes);
6387
+ if (!precise) batch.table(tableName);
6388
+ }
6318
6389
  const result = fn();
6319
6390
  this.#replayOutbox(result, false);
6320
6391
  for (const table of new Set(
@@ -6333,22 +6404,6 @@ export class SyncClient {
6333
6404
  summary.commitsApplied += 1;
6334
6405
  }
6335
6406
 
6336
- /** Record before + after scope keys while the commit transaction is open. */
6337
- #recordCommitChanges(batch: ChangeAccumulator, frame: CommitFrame): void {
6338
- for (const change of frame.changes) {
6339
- const tableName = frame.tables[change.tableIndex];
6340
- if (tableName === undefined) continue;
6341
- const table = this.#schema.tables.get(tableName);
6342
- if (table === undefined) continue;
6343
- let precise = this.#recordStoredRowScopes(batch, table, change.rowId);
6344
- for (const variable of Object.keys(change.scopes)) {
6345
- if (table.scopePrefixByVariable.has(variable)) precise = true;
6346
- }
6347
- batch.changeScopes(table, change.scopes);
6348
- if (!precise) batch.table(tableName);
6349
- }
6350
- }
6351
-
6352
6407
  /** Add the currently materialized row's scope keys; returns whether known. */
6353
6408
  #recordStoredRowScopes(
6354
6409
  batch: ChangeAccumulator,
@@ -6401,7 +6456,6 @@ export class SyncClient {
6401
6456
  owners: () => readonly ScopeMap[],
6402
6457
  hasRows: boolean,
6403
6458
  resetEpoch: number,
6404
- image: boolean,
6405
6459
  ): Parameters<typeof applySqliteSegment>[5] {
6406
6460
  let writeMs = 0;
6407
6461
  let commitMs = 0;
@@ -6429,14 +6483,13 @@ export class SyncClient {
6429
6483
  written = performance.now();
6430
6484
  return result;
6431
6485
  });
6432
- // §7.7: image payloads report their import cost.
6486
+ // §7.7: a payload reports its import cost.
6433
6487
  writeMs += written - started;
6434
6488
  commitMs += performance.now() - written;
6435
- if (image)
6436
- this.#progress.update({
6437
- importWriteMs: Math.round(writeMs),
6438
- importCommitMs: Math.round(commitMs),
6439
- });
6489
+ this.#progress.update({
6490
+ importWriteMs: Math.round(writeMs),
6491
+ importCommitMs: Math.round(commitMs),
6492
+ });
6440
6493
  return result;
6441
6494
  },
6442
6495
  };
@@ -6448,7 +6501,7 @@ export class SyncClient {
6448
6501
  * pair's scope first (§5.6). A fail-closed error (no local scope-column
6449
6502
  * mapping) marks the unit `failed` without failing the whole response.
6450
6503
  */
6451
- async #applySegmentOrFail(
6504
+ *#applySegmentOrFail(
6452
6505
  section: OpenSection,
6453
6506
  summary: MutableSummary,
6454
6507
  tableName: string,
@@ -6457,8 +6510,8 @@ export class SyncClient {
6457
6510
  clearFirst: boolean,
6458
6511
  effective: ScopeMap,
6459
6512
  owners: () => readonly ScopeMap[],
6460
- ) => number | Promise<number>,
6461
- ): Promise<void> {
6513
+ ) => Generator<ApplyStep, number, unknown> | (() => Promise<number>),
6514
+ ): Generator<ApplyStep, void, unknown> {
6462
6515
  const { unit } = section;
6463
6516
  const table = this.#table(tableName);
6464
6517
  const effective = covers(table, unit.scopes)
@@ -6477,7 +6530,7 @@ export class SyncClient {
6477
6530
  unit.id,
6478
6531
  ]);
6479
6532
  try {
6480
- summary.segmentRowsApplied += await apply(
6533
+ const work = apply(
6481
6534
  table,
6482
6535
  clearFirst,
6483
6536
  effective,
@@ -6490,6 +6543,8 @@ export class SyncClient {
6490
6543
  ? unitOwners(loadUnits(this.#db), table, unit.id)
6491
6544
  : []),
6492
6545
  );
6546
+ summary.segmentRowsApplied +=
6547
+ typeof work === 'function' ? ((yield work) as number) : yield* work;
6493
6548
  section.seeded.add(tableName);
6494
6549
  } catch (error) {
6495
6550
  if (
@@ -6568,7 +6623,7 @@ export class SyncClient {
6568
6623
  ),
6569
6624
  byteLength: frame.byteLength,
6570
6625
  onProgress,
6571
- ...(signal !== undefined ? { signal } : {}),
6626
+ ...definedObject({ signal }),
6572
6627
  });
6573
6628
  }
6574
6629
  // §5.4: the descriptor's byteLength caps the body; §5.1: verify the
@@ -6841,26 +6896,6 @@ export class SyncClient {
6841
6896
  upsertLocalRow(this.#db, table, values, image.syncVersion);
6842
6897
  }
6843
6898
 
6844
- #legacyUndoOptimisticRows(
6845
- commit: OutboxCommit,
6846
- batch: ChangeAccumulator,
6847
- ): void {
6848
- for (const operation of commit.operations) {
6849
- if (operation.op !== 'upsert') continue;
6850
- const table = this.#schema.tables.get(operation.table);
6851
- if (table === undefined) continue;
6852
- const row = this.#rowById(
6853
- table,
6854
- operation.rowId,
6855
- `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`,
6856
- );
6857
- if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
6858
- batch.table(table.name);
6859
- deleteLocalRow(this.#db, table, operation.rowId);
6860
- }
6861
- }
6862
- }
6863
-
6864
6899
  #rollbackFailedCommit(
6865
6900
  commit: OutboxCommit,
6866
6901
  batch: ChangeAccumulator,
@@ -6883,7 +6918,21 @@ export class SyncClient {
6883
6918
  } else {
6884
6919
  // Pending commits written by older clients have no before-images.
6885
6920
  // Preserve the old fail-closed behavior rather than guessing a base.
6886
- this.#legacyUndoOptimisticRows(commit, batch);
6921
+ for (const operation of commit.operations) {
6922
+ if (operation.op !== 'upsert') continue;
6923
+ const table = this.#schema.tables.get(operation.table);
6924
+ if (
6925
+ table !== undefined &&
6926
+ this.#rowById(
6927
+ table,
6928
+ operation.rowId,
6929
+ `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`,
6930
+ )?.v === OPTIMISTIC_VERSION
6931
+ ) {
6932
+ batch.table(table.name);
6933
+ deleteLocalRow(this.#db, table, operation.rowId);
6934
+ }
6935
+ }
6887
6936
  }
6888
6937
  deleteOutboxCommit(this.#db, commit.clientCommitId);
6889
6938
 
@@ -7239,9 +7288,7 @@ export class SyncClient {
7239
7288
 
7240
7289
  function requireRowId(value: unknown): string {
7241
7290
  if (typeof value === 'string' && value.length > 0) return value;
7242
- if (typeof value === 'number' && Number.isSafeInteger(value)) {
7291
+ if (Number.isSafeInteger(value) || typeof value === 'boolean')
7243
7292
  return String(value);
7244
- }
7245
- if (typeof value === 'boolean') return String(value);
7246
7293
  throw invalidRequest('a mutation requires a non-empty primary key');
7247
7294
  }