@syncular/client 0.91.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/dist/client.js CHANGED
@@ -160,6 +160,11 @@ function isFinalPushResult(frame) {
160
160
  result.code === 'sync.idempotency_cache_miss' &&
161
161
  result.retryable));
162
162
  }
163
+ function transportFlag(value) {
164
+ if (typeof value !== 'boolean')
165
+ throw invalidRequest('transportEnabled must be a boolean');
166
+ return value;
167
+ }
163
168
  /** The stable `code` a thrown value carries, when it has one. */
164
169
  function thrownCode(error) {
165
170
  const code = error?.code;
@@ -291,6 +296,9 @@ export class SyncClient {
291
296
  #queryFailures = new Map();
292
297
  /** The batch accumulator; non-undefined only inside `#applyBatch`. */
293
298
  #batch;
299
+ /** §1.4 rule 4: the change batches an open coalesced apply transaction
300
+ * publishes after its COMMIT, in revision order. */
301
+ #held;
294
302
  /**
295
303
  * Operation-serialization mutex (the core owns one loop). Every
296
304
  * transaction-entering ASYNC operation — `sync`, the delta-apply body, and
@@ -312,11 +320,9 @@ export class SyncClient {
312
320
  #protectedAsync = new Set();
313
321
  #preflightBarrier;
314
322
  constructor(config) {
315
- if (config.transportEnabled !== undefined &&
316
- typeof config.transportEnabled !== 'boolean') {
317
- throw invalidRequest('transportEnabled must be a boolean');
318
- }
319
- this.#transportEnabled = config.transportEnabled !== false;
323
+ this.#transportEnabled =
324
+ config.transportEnabled === undefined ||
325
+ transportFlag(config.transportEnabled);
320
326
  for (const name of [
321
327
  'maxPushCommitsPerRequest',
322
328
  'maxPushOperationsPerRequest',
@@ -547,12 +553,16 @@ export class SyncClient {
547
553
  // earlier WITHOUT a schema bump.
548
554
  this.#db.transaction(() => {
549
555
  ensureLocalSyncedSchema(this.#db, this.#schema);
550
- if (marker === undefined)
551
- setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
552
- setLocalSchemaDescriptor(this.#db, this.#schema);
553
- saveUnitScopeSchema(this.#db, this.#schema);
556
+ this.#stampSchema(marker === undefined);
554
557
  });
555
558
  }
559
+ /** Write the schema marker (when `version`), descriptor and unit scopes. */
560
+ #stampSchema(version) {
561
+ if (version)
562
+ setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
563
+ setLocalSchemaDescriptor(this.#db, this.#schema);
564
+ saveUnitScopeSchema(this.#db, this.#schema);
565
+ }
556
566
  /**
557
567
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
558
568
  * leaseState, and the tables and units a bump keeps (equal generations).
@@ -579,9 +589,7 @@ export class SyncClient {
579
589
  }
580
590
  changed = resetLocalReplica(this.#db, this.#schema, true);
581
591
  this.#replayOutbox();
582
- setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
583
- setLocalSchemaDescriptor(this.#db, this.#schema);
584
- saveUnitScopeSchema(this.#db, this.#schema);
592
+ this.#stampSchema(true);
585
593
  });
586
594
  // Every table the reset dropped changed (I1 eviction-shaped).
587
595
  for (const table of changed)
@@ -650,7 +658,7 @@ export class SyncClient {
650
658
  /** §2.1 reset after the server reports a different log continuity. */
651
659
  #runLogEpochReset(logEpoch) {
652
660
  if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
653
- this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
661
+ setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
654
662
  this.#emitSyncNeeded('startup');
655
663
  return [];
656
664
  }
@@ -762,9 +770,7 @@ export class SyncClient {
762
770
  /** Host-owned transport policy; the local replica remains available. */
763
771
  setTransportEnabled(enabled) {
764
772
  this.#requireStarted();
765
- if (typeof enabled !== 'boolean')
766
- throw invalidRequest('transportEnabled must be a boolean');
767
- if (this.#transportEnabled === enabled)
773
+ if (this.#transportEnabled === transportFlag(enabled))
768
774
  return;
769
775
  this.#transportEnabled = enabled;
770
776
  this.#transportEpoch += 1;
@@ -901,23 +907,16 @@ export class SyncClient {
901
907
  return this.#authorityReads.snapshot(this.#db, this.#schema);
902
908
  }
903
909
  querySnapshot(spec) {
904
- const read = this.#readSnapshot({
905
- statements: [
906
- {
907
- sql: spec.sql,
908
- ...(spec.params !== undefined ? { params: spec.params } : {}),
909
- },
910
- ],
911
- ...(spec.coverage !== undefined ? { coverage: spec.coverage } : {}),
912
- ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
913
- });
914
- const rows = read.queries[0];
915
- if (read.queries.length !== 1 || rows === undefined) {
916
- throw new ClientSyncError('client.failed', 'querySnapshot produced no statement result');
917
- }
910
+ // A statement reads only `sql` and `params`; one statement yields one
911
+ // result.
912
+ const read = this.#readSnapshot(definedObject({
913
+ statements: [spec],
914
+ coverage: spec.coverage,
915
+ owner: spec.owner,
916
+ }));
918
917
  return {
919
918
  revision: read.revision,
920
- rows,
919
+ rows: read.queries[0],
921
920
  coverage: read.coverage,
922
921
  };
923
922
  }
@@ -1130,18 +1129,10 @@ export class SyncClient {
1130
1129
  #readPreviousVersionRecord() {
1131
1130
  return withPreviousVersionContainer(this.#db, readPreviousVersionContainer);
1132
1131
  }
1133
- /** RFC 0005 A2: presence for `statusSnapshot()`, without creating the file. */
1134
- #previousVersionStatus() {
1135
- const record = this.#readPreviousVersionRecord();
1136
- if (record === undefined)
1137
- return { present: this.#previousVersionExists() };
1138
- return { present: true, createdAtMs: record.createdAtMs };
1139
- }
1140
1132
  #previousVersionLeaseInactive(nowMs) {
1141
1133
  const lease = this.#leaseState;
1142
- if (lease?.errorCode !== undefined)
1143
- return true;
1144
- return lease?.expiresAtMs !== undefined && lease.expiresAtMs <= nowMs;
1134
+ return (lease?.errorCode !== undefined ||
1135
+ (lease?.expiresAtMs ?? Infinity) <= nowMs);
1145
1136
  }
1146
1137
  /**
1147
1138
  * RFC 0005 D7: the §7.4.5 replacement-coverage predicate: no active unit
@@ -1282,12 +1273,13 @@ export class SyncClient {
1282
1273
  ? 'offline'
1283
1274
  : round?.status === 'succeeded'
1284
1275
  ? 'online'
1285
- : round?.status === 'failed' &&
1286
- (round.causeKind === 'network' || round.causeKind === 'connect')
1287
- ? 'offline'
1288
- : round?.status === 'failed' && round.httpStatus !== undefined
1289
- ? 'online'
1290
- : 'unknown';
1276
+ : round?.status !== 'failed'
1277
+ ? 'unknown'
1278
+ : round.causeKind === 'network' || round.causeKind === 'connect'
1279
+ ? 'offline'
1280
+ : round.httpStatus !== undefined
1281
+ ? 'online'
1282
+ : 'unknown';
1291
1283
  return definedObject({
1292
1284
  version: CLIENT_DIAGNOSTICS_VERSION,
1293
1285
  capturedAtMs,
@@ -1321,7 +1313,7 @@ export class SyncClient {
1321
1313
  : [this.#diagnosticCode(unit.reasonCode)])),
1322
1314
  ].sort(),
1323
1315
  },
1324
- activeUnits: registered.filter((unit) => unit.status === 'active').length,
1316
+ activeUnits: registered.length - units.revoked - units.failed,
1325
1317
  replicaCursor: replicaCursor(this.#db),
1326
1318
  lastRound: this.#lastRound,
1327
1319
  lastChange: this.#lastChange,
@@ -1347,8 +1339,8 @@ export class SyncClient {
1347
1339
  }
1348
1340
  #diagnosticStorage() {
1349
1341
  try {
1350
- const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
1351
- const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
1342
+ const pragma = (name) => Number(this.#db.query(`PRAGMA ${name}`)[0]?.[name] ?? 0);
1343
+ const databaseBytes = pragma('page_count') * pragma('page_size');
1352
1344
  // One statement for the outbox and outcome-journal sums keeps the
1353
1345
  // snapshot at its pre-version-4 statement count.
1354
1346
  const sums = this.#db.query(`SELECT (SELECT COALESCE(SUM(LENGTH(operations)),0) FROM ${OUTBOX_TABLE})AS outbox,COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM ${OUTCOMES_TABLE}`)[0];
@@ -1359,7 +1351,7 @@ export class SyncClient {
1359
1351
  const size = (value) => Math.max(0, Number(value ?? 0));
1360
1352
  return {
1361
1353
  status: pressure ? 'pressure' : 'healthy',
1362
- databaseBytesApprox: Math.max(0, pageCount * pageSize),
1354
+ databaseBytesApprox: Math.max(0, databaseBytes),
1363
1355
  pendingOutboxBytesApprox: size(sums?.outbox),
1364
1356
  retainedOutcomeBytesApprox: size(sums?.bytes),
1365
1357
  retainedOutcomeEntries: size(sums?.entries),
@@ -1403,6 +1395,8 @@ export class SyncClient {
1403
1395
  return this.#statusSnapshot();
1404
1396
  }
1405
1397
  #statusSnapshot(outboxCount) {
1398
+ // RFC 0005 A2: previous-version presence, without creating the file.
1399
+ const record = this.#readPreviousVersionRecord();
1406
1400
  return {
1407
1401
  currentSchemaVersion: this.#config.schema.version,
1408
1402
  outbox: outboxCount ?? countOutbox(this.#db),
@@ -1410,7 +1404,9 @@ export class SyncClient {
1410
1404
  leaseState: this.#leaseState,
1411
1405
  schemaFloor: this.#schemaFloor,
1412
1406
  syncNeeded: this.#needsPull,
1413
- previousVersionContext: this.#previousVersionStatus(),
1407
+ previousVersionContext: record === undefined
1408
+ ? { present: this.#previousVersionExists() }
1409
+ : { present: true, createdAtMs: record.createdAtMs },
1414
1410
  securityLifecycle: this.#securityLifecycle,
1415
1411
  };
1416
1412
  }
@@ -1453,7 +1449,7 @@ export class SyncClient {
1453
1449
  onRollback?.(error);
1454
1450
  throw error;
1455
1451
  }
1456
- if (revision !== undefined) {
1452
+ const publish = () => {
1457
1453
  const event = batch.finish(revision, status);
1458
1454
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
1459
1455
  const windows = [
@@ -1476,7 +1472,12 @@ export class SyncClient {
1476
1472
  if (legacy !== undefined)
1477
1473
  this.#invalidation.emit(legacy);
1478
1474
  this.#emitDiagnostics();
1479
- }
1475
+ };
1476
+ if (revision !== undefined)
1477
+ if (this.#held)
1478
+ this.#held.push(publish);
1479
+ else
1480
+ publish();
1480
1481
  return result;
1481
1482
  }
1482
1483
  /**
@@ -1516,24 +1517,23 @@ export class SyncClient {
1516
1517
  */
1517
1518
  uploadBlob(bytes, options) {
1518
1519
  const owned = bytes.slice();
1519
- return this.#runProtectedAsync(() => this.#uploadBlob(owned, options));
1520
- }
1521
- async #uploadBlob(bytes, options) {
1522
- if (this.#config.blobs === undefined) {
1523
- throw invalidRequest('uploadBlob requires a blob transport');
1524
- }
1525
- const blobId = await computeBlobId(bytes);
1526
- const nowMs = this.#now();
1527
- this.#db.transaction(() => {
1528
- putCachedBlob(this.#db, blobId, bytes, nowMs, options?.mediaType);
1529
- recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
1530
- });
1531
- this.#enforceBlobCacheCap();
1532
- return definedObject({
1533
- blobId,
1534
- byteLength: bytes.length,
1535
- mediaType: options?.mediaType,
1536
- name: options?.name,
1520
+ return this.#runProtectedAsync(async () => {
1521
+ if (this.#config.blobs === undefined) {
1522
+ throw invalidRequest('uploadBlob requires a blob transport');
1523
+ }
1524
+ const blobId = await computeBlobId(owned);
1525
+ const nowMs = this.#now();
1526
+ this.#db.transaction(() => {
1527
+ putCachedBlob(this.#db, blobId, owned, nowMs, options?.mediaType);
1528
+ recordPendingUpload(this.#db, blobId, nowMs, options?.mediaType);
1529
+ });
1530
+ this.#enforceBlobCacheCap();
1531
+ return definedObject({
1532
+ blobId,
1533
+ byteLength: owned.length,
1534
+ mediaType: options?.mediaType,
1535
+ name: options?.name,
1536
+ });
1537
1537
  });
1538
1538
  }
1539
1539
  /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
@@ -1547,60 +1547,59 @@ export class SyncClient {
1547
1547
  * Accepts a raw `blob_ref` column string or a bare `blobId`.
1548
1548
  */
1549
1549
  fetchBlob(blobIdOrRef) {
1550
- return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
1551
- }
1552
- async #fetchBlob(blobIdOrRef) {
1553
- // A BlobRef declares the size that caps the download (§5.9.5); a bare
1554
- // blobId declares none.
1555
- const ref = blobIdOrRef.startsWith('sha256:')
1556
- ? undefined
1557
- : parseBlobRef(blobIdOrRef);
1558
- const blobId = ref?.blobId ?? blobIdOrRef;
1559
- const cached = getCachedBlob(this.#db, blobId);
1560
- if (cached !== undefined)
1561
- return cached;
1562
- const transport = this.#config.blobs;
1563
- if (transport === undefined) {
1564
- throw invalidRequest('fetchBlob requires a blob transport');
1565
- }
1566
- // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
1567
- // presign configured) a signed url the client fetches directly. On a url
1568
- // arm the client MUST NOT attach host auth and MUST NOT fall through:
1569
- // failure => re-request, the caller's next fetchBlob mints a fresh url.
1570
- this.#requireTransport();
1571
- const response = await transport.download(blobId, ref?.byteLength);
1572
- let bytes;
1573
- if (response.kind === 'url') {
1574
- if (transport.fetchUrl === undefined) {
1575
- throw invalidRequest('blob transport cannot fetch urls');
1550
+ return this.#runProtectedAsync(async () => {
1551
+ // A BlobRef declares the size that caps the download (§5.9.5); a bare
1552
+ // blobId declares none.
1553
+ const ref = blobIdOrRef.startsWith('sha256:')
1554
+ ? undefined
1555
+ : parseBlobRef(blobIdOrRef);
1556
+ const blobId = ref?.blobId ?? blobIdOrRef;
1557
+ const cached = getCachedBlob(this.#db, blobId);
1558
+ if (cached !== undefined)
1559
+ return cached;
1560
+ const transport = this.#config.blobs;
1561
+ if (transport === undefined) {
1562
+ throw invalidRequest('fetchBlob requires a blob transport');
1576
1563
  }
1577
- if (response.urlExpiresAtMs !== undefined &&
1578
- response.urlExpiresAtMs <= this.#now()) {
1579
- // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
1580
- throw new ClientSyncError('sync.segment_expired', 'blob url expired before fetch', true);
1564
+ // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
1565
+ // presign configured) a signed url the client fetches directly. On a url
1566
+ // arm the client MUST NOT attach host auth and MUST NOT fall through:
1567
+ // failure => re-request, the caller's next fetchBlob mints a fresh url.
1568
+ this.#requireTransport();
1569
+ const response = await transport.download(blobId, ref?.byteLength);
1570
+ let bytes;
1571
+ if (response.kind === 'url') {
1572
+ if (transport.fetchUrl === undefined) {
1573
+ throw invalidRequest('blob transport cannot fetch urls');
1574
+ }
1575
+ if (response.urlExpiresAtMs !== undefined &&
1576
+ response.urlExpiresAtMs <= this.#now()) {
1577
+ // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
1578
+ throw new ClientSyncError('sync.segment_expired', 'blob url expired before fetch', true);
1579
+ }
1580
+ bytes = await transport.fetchUrl(response.url, ref?.byteLength);
1581
1581
  }
1582
- bytes = await transport.fetchUrl(response.url, ref?.byteLength);
1583
- }
1584
- else {
1585
- bytes = response.bytes;
1586
- }
1587
- // §5.9.5 inherits §5.1: the declared size caps the body and the content
1588
- // address must match. On the url path either failure invalidates the
1589
- // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
1590
- if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
1591
- throw invalidRequest('blob exceeds its byteLength');
1592
- }
1593
- if ((await computeBlobId(bytes)) !== blobId) {
1594
- throw invalidRequest('blob content address mismatch');
1595
- }
1596
- putCachedBlob(this.#db, blobId, bytes, this.#now());
1597
- this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
1598
- this.#enforceBlobCacheCap();
1599
- const stored = getCachedBlob(this.#db, blobId);
1600
- if (stored === undefined) {
1601
- throw invalidRequest('blob cache write failed');
1602
- }
1603
- return stored;
1582
+ else {
1583
+ bytes = response.bytes;
1584
+ }
1585
+ // §5.9.5 inherits §5.1: the declared size caps the body and the content
1586
+ // address must match. On the url path either failure invalidates the
1587
+ // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
1588
+ if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
1589
+ throw invalidRequest('blob exceeds its byteLength');
1590
+ }
1591
+ if ((await computeBlobId(bytes)) !== blobId) {
1592
+ throw invalidRequest('blob content address mismatch');
1593
+ }
1594
+ putCachedBlob(this.#db, blobId, bytes, this.#now());
1595
+ this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
1596
+ this.#enforceBlobCacheCap();
1597
+ const stored = getCachedBlob(this.#db, blobId);
1598
+ if (stored === undefined) {
1599
+ throw invalidRequest('blob cache write failed');
1600
+ }
1601
+ return stored;
1602
+ });
1604
1603
  }
1605
1604
  /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
1606
1605
  #enforceBlobCacheCap() {
@@ -1977,8 +1976,9 @@ export class SyncClient {
1977
1976
  if (resolved === undefined) {
1978
1977
  throw outcomeNotFound();
1979
1978
  }
1980
- this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== input.clientCommitId);
1981
- this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== input.clientCommitId);
1979
+ const kept = (record) => record.clientCommitId !== input.clientCommitId;
1980
+ this.#conflicts = this.#conflicts.filter(kept);
1981
+ this.#rejections = this.#rejections.filter(kept);
1982
1982
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
1983
1983
  this.#replayOutbox(scope, false);
1984
1984
  for (const operation of current.operations ?? [])
@@ -2178,16 +2178,17 @@ export class SyncClient {
2178
2178
  const baseKey = windowBaseKey(base);
2179
2179
  const wanted = new Set(units);
2180
2180
  const live = loadWindowUnits(this.#db, baseKey);
2181
- // §7.8: a widen registers like `subscribe` and never waits for a
2182
- // running round.
2183
- for (const value of wanted) {
2184
- if (live.some((entry) => entry.value === value))
2185
- continue;
2181
+ // §7.8: a widen registers its values like `subscribeMany`, in one
2182
+ // transaction, and never waits for a running round.
2183
+ const added = [...wanted].filter((value) => !live.some((entry) => entry.value === value));
2184
+ if (added.length > 0) {
2186
2185
  this.#applyBatch((batch) => {
2187
- const { id, changed: registered } = this.#holdUnit(windowUnitScopes(base, value), false);
2188
- this.#db.exec(`INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`, [baseKey, value, id]);
2189
- this.#needsPull ||= registered;
2190
- batch.window(baseKey, value);
2186
+ for (const value of added) {
2187
+ const { id, changed: registered } = this.#holdUnit(windowUnitScopes(base, value), false);
2188
+ this.#db.exec(`INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`, [baseKey, value, id]);
2189
+ this.#needsPull ||= registered;
2190
+ batch.window(baseKey, value);
2191
+ }
2191
2192
  batch.status();
2192
2193
  });
2193
2194
  changed = true;
@@ -2478,10 +2479,7 @@ export class SyncClient {
2478
2479
  for (const operation of operations) {
2479
2480
  if (operation.op !== 'upsert')
2480
2481
  continue;
2481
- const table = this.#schema.tables.get(operation.table);
2482
- if (table === undefined)
2483
- continue;
2484
- for (const column of table.columns) {
2482
+ for (const column of this.#table(operation.table).columns) {
2485
2483
  if (column.type !== 'blob_ref')
2486
2484
  continue;
2487
2485
  const raw = operation.values?.[column.name];
@@ -2812,10 +2810,6 @@ export class SyncClient {
2812
2810
  if (next.errorCode !== undefined)
2813
2811
  this.#discardPreviousVersion();
2814
2812
  }
2815
- /** The request-level lease error codes (§7.3.4): stop-and-surface. */
2816
- #isLeaseErrorCode(code) {
2817
- return (code === 'sync.auth_lease_required' || code === 'sync.auth_lease_revoked');
2818
- }
2819
2813
  /**
2820
2814
  * §7.4.4: encode every pending outbox commit with the current codec. A
2821
2815
  * commit that cannot re-encode under the new schema (an
@@ -2932,7 +2926,7 @@ export class SyncClient {
2932
2926
  kind,
2933
2927
  limit,
2934
2928
  size,
2935
- ...(clientCommitId !== undefined ? { clientCommitId } : {}),
2929
+ clientCommitId,
2936
2930
  }));
2937
2931
  }
2938
2932
  /**
@@ -3067,7 +3061,20 @@ export class SyncClient {
3067
3061
  this.#lastRound = {
3068
3062
  status: 'succeeded',
3069
3063
  ...round(),
3070
- counters: this.#diagnosticRoundCounters(summary),
3064
+ counters: {
3065
+ pushed: summary.pushed,
3066
+ applied: summary.applied.length,
3067
+ rejected: summary.rejected.length,
3068
+ retryable: summary.retryable.length,
3069
+ conflicts: summary.conflicts.length,
3070
+ commitsApplied: summary.commitsApplied,
3071
+ segmentRowsApplied: summary.segmentRowsApplied,
3072
+ bootstrapping: summary.bootstrapping.length,
3073
+ resets: summary.resets.length,
3074
+ revoked: summary.revoked.length,
3075
+ failed: summary.failed.length,
3076
+ deferredCommits: summary.deferredCommits ?? 0,
3077
+ },
3071
3078
  };
3072
3079
  this.#emitDiagnostics();
3073
3080
  return summary;
@@ -3130,22 +3137,6 @@ export class SyncClient {
3130
3137
  this.#endDiagnosticsDeferral();
3131
3138
  });
3132
3139
  }
3133
- #diagnosticRoundCounters(summary) {
3134
- return {
3135
- pushed: summary.pushed,
3136
- applied: summary.applied.length,
3137
- rejected: summary.rejected.length,
3138
- retryable: summary.retryable.length,
3139
- conflicts: summary.conflicts.length,
3140
- commitsApplied: summary.commitsApplied,
3141
- segmentRowsApplied: summary.segmentRowsApplied,
3142
- bootstrapping: summary.bootstrapping.length,
3143
- resets: summary.resets.length,
3144
- revoked: summary.revoked.length,
3145
- failed: summary.failed.length,
3146
- deferredCommits: summary.deferredCommits ?? 0,
3147
- };
3148
- }
3149
3140
  #diagnosticCode(code) {
3150
3141
  return isStableCode(code) ? code : 'client.unknown_failure';
3151
3142
  }
@@ -3200,7 +3191,13 @@ export class SyncClient {
3200
3191
  echoDigest: new Uint8Array(),
3201
3192
  };
3202
3193
  const { pushFrames, outbox, frameBytes, deferred: encodedDeferred, } = logEpoch === undefined
3203
- ? { pushFrames: [], outbox: [], frameBytes: [], deferred: 0 }
3194
+ ? {
3195
+ pushFrames: [],
3196
+ outbox: [],
3197
+ frameBytes: [],
3198
+ // §2.1: the outbox waits for the next, epoch-bound request.
3199
+ deferred: countOutbox(this.#db),
3200
+ }
3204
3201
  : await this.#encodeOutboxForPush(header, pull, byteCap);
3205
3202
  // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
3206
3203
  // them, so the server-side existence check (§6.6) passes.
@@ -3237,6 +3234,8 @@ export class SyncClient {
3237
3234
  ...(report !== undefined
3238
3235
  ? [{ type: 'ROUND_FAILURE', code: report }]
3239
3236
  : []),
3237
+ // §2.1: a replica without an epoch holds nothing bound to one.
3238
+ ...(logEpoch === undefined ? [{ type: 'ADOPT_EPOCH' }] : []),
3240
3239
  pull,
3241
3240
  ...(travels
3242
3241
  ? registered.map((unit) => ({ type: 'UNIT', scopes: unit.scopes }))
@@ -3315,9 +3314,18 @@ export class SyncClient {
3315
3314
  catch (caught) {
3316
3315
  // §1.5: a round that ended without a complete, decodable response is a
3317
3316
  // failure the server could not see — keep its code for the next request.
3318
- const unseen = this.#unseenRoundFailureCode(caught);
3319
- if (unseen !== undefined)
3320
- this.#roundFailureCode = unseen;
3317
+ // An undecodable/truncated body, a rejected fetch, a failed body read,
3318
+ // or a socket round lost mid-flight; an HTTP-status rejection and an
3319
+ // in-band `ERROR` frame were recorded by the server and stay
3320
+ // unreported. The frame carries only codes matching its grammar; a
3321
+ // code that does not match would turn the whole request into a decode
3322
+ // error.
3323
+ if ((caught instanceof DecodeError ||
3324
+ (caught instanceof ClientSyncError &&
3325
+ caught.code === 'sync.transport_failed' &&
3326
+ caught.details?.['causeKind'] !== 'status')) &&
3327
+ isRoundFailureCode(caught.code))
3328
+ this.#roundFailureCode = caught.code;
3321
3329
  // §7.8: a round the drive deadline aborted ends with the deadline's
3322
3330
  // error, whichever transport call observed the abort.
3323
3331
  const error = signal?.aborted ? signal.reason : caught;
@@ -3326,8 +3334,10 @@ export class SyncClient {
3326
3334
  // silent retry: the app drives recovery to a live resolver. The
3327
3335
  // error may arrive as a ClientSyncError or as a transport error
3328
3336
  // carrying the server's `.code` (HTTP-JSON / loopback surface, §1.1).
3337
+ // The request-level lease error codes (§7.3.4).
3329
3338
  const code = error.code;
3330
- if (typeof code === 'string' && this.#isLeaseErrorCode(code)) {
3339
+ if (code === 'sync.auth_lease_required' ||
3340
+ code === 'sync.auth_lease_revoked') {
3331
3341
  this.#setLeaseState({
3332
3342
  ...(this.#leaseState ?? {}),
3333
3343
  errorCode: code,
@@ -3438,7 +3448,7 @@ export class SyncClient {
3438
3448
  return {
3439
3449
  ...summary,
3440
3450
  ...(deferredCommits > 0 ? { deferredCommits } : {}),
3441
- ...(schemaFloor !== undefined ? { schemaFloor } : {}),
3451
+ ...definedObject({ schemaFloor }),
3442
3452
  budgetExhausted,
3443
3453
  };
3444
3454
  };
@@ -3590,7 +3600,8 @@ export class SyncClient {
3590
3600
  if (this.#realtimePolicy === 'required') {
3591
3601
  // §8.8: the designated realtime path is down. Refuse the round; the
3592
3602
  // HTTP binding is not an alternative for a `required` client.
3593
- throw this.#realtimeUnavailableError();
3603
+ this.#realtimeRetryDelayMs = this.#retryDelayMs;
3604
+ throw new RealtimeUnavailableError(this.#realtimeState, this.#realtimeReasonCode, this.#retryDelayMs);
3594
3605
  }
3595
3606
  return Promise.resolve()
3596
3607
  .then(() => this.#config.transport(request, signal))
@@ -3604,25 +3615,6 @@ export class SyncClient {
3604
3615
  });
3605
3616
  });
3606
3617
  }
3607
- /**
3608
- * §1.5: the code to report for a round that ended without a complete,
3609
- * decodable response — an undecodable/truncated body, a rejected fetch, a
3610
- * failed body read, or a socket round lost mid-flight. An HTTP-status
3611
- * rejection and an in-band `ERROR` frame were recorded by the server and
3612
- * stay unreported.
3613
- */
3614
- #unseenRoundFailureCode(error) {
3615
- const code = error instanceof DecodeError
3616
- ? error.code
3617
- : error instanceof ClientSyncError &&
3618
- error.code === 'sync.transport_failed' &&
3619
- error.details?.['causeKind'] !== 'status'
3620
- ? error.code
3621
- : undefined;
3622
- // §1.5: the frame carries only codes matching its grammar; a code that
3623
- // does not match would turn the whole request into a decode error.
3624
- return code !== undefined && isRoundFailureCode(code) ? code : undefined;
3625
- }
3626
3618
  /** Abort the in-flight socket round (socket closed or disconnected). */
3627
3619
  #abortPendingRound(reason) {
3628
3620
  const round = this.#pendingRound;
@@ -3648,10 +3640,6 @@ export class SyncClient {
3648
3640
  }
3649
3641
  this.#emitDiagnostics();
3650
3642
  }
3651
- #realtimeUnavailableError() {
3652
- this.#realtimeRetryDelayMs = this.#retryDelayMs;
3653
- return new RealtimeUnavailableError(this.#realtimeState, this.#realtimeReasonCode, this.#retryDelayMs);
3654
- }
3655
3643
  connectRealtime() {
3656
3644
  this.#requireActive();
3657
3645
  this.#requireTransport();
@@ -3918,12 +3906,6 @@ export class SyncClient {
3918
3906
  if (this.#transportEnabled)
3919
3907
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
3920
3908
  }
3921
- /** §8.2: after a pull round, ack the replica cursor while it is `>= 0`. */
3922
- #ackAfterPull() {
3923
- const cursor = replicaCursor(this.#db);
3924
- if (this.#socket !== undefined && cursor >= 0)
3925
- this.#sendAck(cursor);
3926
- }
3927
3909
  // -- response processing ------------------------------------------------------
3928
3910
  /**
3929
3911
  * Apply one response (§1.6) or realtime delta (§8.2). `sentDigest` is the
@@ -3971,7 +3953,7 @@ export class SyncClient {
3971
3953
  const currentLogEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
3972
3954
  if (header.resetRequired) {
3973
3955
  if (mode !== 'pull' || message.frames.length !== 1) {
3974
- throw invalidHostResponse('a log-epoch reset response must contain only RESP_HEADER');
3956
+ throw invalidHostResponse('a log-epoch reset response carries frames after RESP_HEADER');
3975
3957
  }
3976
3958
  return {
3977
3959
  ...summary,
@@ -3979,7 +3961,11 @@ export class SyncClient {
3979
3961
  bootstrapping: [],
3980
3962
  };
3981
3963
  }
3982
- if (currentLogEpoch === undefined || currentLogEpoch !== header.logEpoch) {
3964
+ // §2.1 adoption: the epoch is stored before any section applies.
3965
+ if (currentLogEpoch === undefined) {
3966
+ setMeta(this.#db, LOG_EPOCH_META_KEY, header.logEpoch);
3967
+ }
3968
+ else if (currentLogEpoch !== header.logEpoch) {
3983
3969
  throw invalidHostResponse('the server changed logEpoch without requiring a reset');
3984
3970
  }
3985
3971
  let section;
@@ -4045,14 +4031,19 @@ export class SyncClient {
4045
4031
  }
4046
4032
  prefetch();
4047
4033
  }
4048
- // Each durable observer transaction emits its own revisioned batch.
4049
- // Async decrypt/download work happens outside SQLite transactions.
4050
- this.#beginDiagnosticsDeferral();
4051
- try {
4034
+ // §1.4 rule 4: the frames of unit sections run in coalesced apply
4035
+ // transactions of at most 1,024 rows, each frame or block in its own
4036
+ // savepoint with its own revision, published after the COMMIT; the host
4037
+ // yields to local reads after each COMMIT. Every other frame runs outside
4038
+ // one, and downloads, decryption, images and COMMIT frames are awaited
4039
+ // outside any transaction.
4040
+ const steps = function* () {
4052
4041
  for (let index = 1; index < message.frames.length; index += 1) {
4053
4042
  const frame = message.frames[index];
4054
4043
  if (frame === undefined)
4055
4044
  break;
4045
+ if (!/^(SUB|SEGMENT|UNIT)_/.test(frame.type))
4046
+ yield -1;
4056
4047
  switch (frame.type) {
4057
4048
  case 'RESP_HEADER':
4058
4049
  break;
@@ -4176,9 +4167,10 @@ export class SyncClient {
4176
4167
  prefetched.delete(frame);
4177
4168
  if (pending !== undefined)
4178
4169
  reporting = frame;
4170
+ const { scopes } = section.unit;
4179
4171
  try {
4180
- bytes = await (pending ??
4181
- this.#downloadSegment(frame, section.unit.scopes, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
4172
+ bytes = (yield () => pending ??
4173
+ this.#downloadSegment(frame, scopes, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
4182
4174
  }
4183
4175
  catch (error) {
4184
4176
  // §5.5: access changed since the response. The unit stays
@@ -4206,12 +4198,12 @@ export class SyncClient {
4206
4198
  bytesTotal: bytes.byteLength,
4207
4199
  rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
4208
4200
  });
4209
- await this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
4201
+ yield* this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
4210
4202
  const options = this.#segmentApplyOptions(table, clearFirst, effective, owners, image !== undefined
4211
4203
  ? image.rowCount > 0
4212
- : segment.blocks.some((block) => block.length > 0), resetEpoch, image !== undefined);
4204
+ : segment.blocks.some((block) => block.length > 0), resetEpoch);
4213
4205
  return image !== undefined
4214
- ? applySqliteSegment(this.#db, this.#schema, table, bytes, image, {
4206
+ ? () => applySqliteSegment(this.#db, this.#schema, table, bytes, image, {
4215
4207
  ...options,
4216
4208
  appliedRows,
4217
4209
  onChunk: (rows) => recordAppliedRows(this.#db, unitId, image.segmentId, rows),
@@ -4281,7 +4273,7 @@ export class SyncClient {
4281
4273
  }));
4282
4274
  });
4283
4275
  if (changes.length > 0)
4284
- await this.#applyCommit({ ...frame, changes }, summary, mode);
4276
+ yield () => this.#applyCommit({ ...frame, changes }, summary, mode);
4285
4277
  break;
4286
4278
  }
4287
4279
  case 'LIVE_END': {
@@ -4369,6 +4361,58 @@ export class SyncClient {
4369
4361
  if (errorFrame !== undefined)
4370
4362
  break;
4371
4363
  }
4364
+ }.call(this);
4365
+ this.#beginDiagnosticsDeferral();
4366
+ try {
4367
+ for (let step = steps.next(); !step.done;) {
4368
+ const work = step.value;
4369
+ if (typeof work === 'function') {
4370
+ try {
4371
+ step = steps.next(await work());
4372
+ }
4373
+ catch (error) {
4374
+ step = steps.throw(error);
4375
+ }
4376
+ }
4377
+ else if (work < 0)
4378
+ step = steps.next();
4379
+ else {
4380
+ const held = (this.#held = []);
4381
+ const rejections = this.#rejections.length;
4382
+ let failure;
4383
+ try {
4384
+ failure = this.#db.transaction(() => {
4385
+ try {
4386
+ for (let rows = work;;) {
4387
+ step = steps.next();
4388
+ const next = step.value;
4389
+ if (typeof next !== 'number' ||
4390
+ next < 0 ||
4391
+ (rows > 0 && rows + next > 1024))
4392
+ return undefined;
4393
+ rows += next;
4394
+ }
4395
+ }
4396
+ catch (error) {
4397
+ // §1.4 rule 5: the frames before the failing one commit.
4398
+ return { error };
4399
+ }
4400
+ });
4401
+ }
4402
+ catch (error) {
4403
+ this.#rejections.length = rejections;
4404
+ throw error;
4405
+ }
4406
+ finally {
4407
+ this.#held = undefined;
4408
+ }
4409
+ for (const publish of held)
4410
+ publish();
4411
+ if (failure)
4412
+ throw failure.error;
4413
+ await yieldToHost();
4414
+ }
4415
+ }
4372
4416
  }
4373
4417
  finally {
4374
4418
  this.#endDiagnosticsDeferral();
@@ -4384,7 +4428,10 @@ export class SyncClient {
4384
4428
  }
4385
4429
  }
4386
4430
  else {
4387
- this.#ackAfterPull();
4431
+ // §8.2: after a pull round, ack the replica cursor while it is `>= 0`.
4432
+ const cursor = replicaCursor(this.#db);
4433
+ if (this.#socket !== undefined && cursor >= 0)
4434
+ this.#sendAck(cursor);
4388
4435
  }
4389
4436
  const catchingUp = loadUnits(this.#db)
4390
4437
  .filter((unit) => unit.status === 'active' && unit.cursor !== undefined)
@@ -4544,7 +4591,23 @@ export class SyncClient {
4544
4591
  }
4545
4592
  async #applyCommit(frame, summary, source) {
4546
4593
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4547
- this.#recordCommitChanges(batch, frame);
4594
+ // Record before + after scope keys while the transaction is open.
4595
+ for (const change of frame.changes) {
4596
+ const tableName = frame.tables[change.tableIndex];
4597
+ if (tableName === undefined)
4598
+ continue;
4599
+ const table = this.#schema.tables.get(tableName);
4600
+ if (table === undefined)
4601
+ continue;
4602
+ let precise = this.#recordStoredRowScopes(batch, table, change.rowId);
4603
+ for (const variable of Object.keys(change.scopes)) {
4604
+ if (table.scopePrefixByVariable.has(variable))
4605
+ precise = true;
4606
+ }
4607
+ batch.changeScopes(table, change.scopes);
4608
+ if (!precise)
4609
+ batch.table(tableName);
4610
+ }
4548
4611
  const result = fn();
4549
4612
  this.#replayOutbox(result, false);
4550
4613
  for (const table of new Set(frame.changes.map((change) => frame.tables[change.tableIndex]))) {
@@ -4559,25 +4622,6 @@ export class SyncClient {
4559
4622
  }));
4560
4623
  summary.commitsApplied += 1;
4561
4624
  }
4562
- /** Record before + after scope keys while the commit transaction is open. */
4563
- #recordCommitChanges(batch, frame) {
4564
- for (const change of frame.changes) {
4565
- const tableName = frame.tables[change.tableIndex];
4566
- if (tableName === undefined)
4567
- continue;
4568
- const table = this.#schema.tables.get(tableName);
4569
- if (table === undefined)
4570
- continue;
4571
- let precise = this.#recordStoredRowScopes(batch, table, change.rowId);
4572
- for (const variable of Object.keys(change.scopes)) {
4573
- if (table.scopePrefixByVariable.has(variable))
4574
- precise = true;
4575
- }
4576
- batch.changeScopes(table, change.scopes);
4577
- if (!precise)
4578
- batch.table(tableName);
4579
- }
4580
- }
4581
4625
  /** Add the currently materialized row's scope keys; returns whether known. */
4582
4626
  #recordStoredRowScopes(batch, table, rowId) {
4583
4627
  const mappings = [...table.scopeColumnByVariable].filter(([variable]) => table.scopePrefixByVariable.has(variable));
@@ -4604,7 +4648,7 @@ export class SyncClient {
4604
4648
  this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
4605
4649
  }
4606
4650
  /** Shared transaction, reset fence and progress for both segment formats. */
4607
- #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch, image) {
4651
+ #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch) {
4608
4652
  let writeMs = 0;
4609
4653
  let commitMs = 0;
4610
4654
  return {
@@ -4629,14 +4673,13 @@ export class SyncClient {
4629
4673
  written = performance.now();
4630
4674
  return result;
4631
4675
  });
4632
- // §7.7: image payloads report their import cost.
4676
+ // §7.7: a payload reports its import cost.
4633
4677
  writeMs += written - started;
4634
4678
  commitMs += performance.now() - written;
4635
- if (image)
4636
- this.#progress.update({
4637
- importWriteMs: Math.round(writeMs),
4638
- importCommitMs: Math.round(commitMs),
4639
- });
4679
+ this.#progress.update({
4680
+ importWriteMs: Math.round(writeMs),
4681
+ importCommitMs: Math.round(commitMs),
4682
+ });
4640
4683
  return result;
4641
4684
  },
4642
4685
  };
@@ -4647,7 +4690,7 @@ export class SyncClient {
4647
4690
  * pair's scope first (§5.6). A fail-closed error (no local scope-column
4648
4691
  * mapping) marks the unit `failed` without failing the whole response.
4649
4692
  */
4650
- async #applySegmentOrFail(section, summary, tableName, apply) {
4693
+ *#applySegmentOrFail(section, summary, tableName, apply) {
4651
4694
  const { unit } = section;
4652
4695
  const table = this.#table(tableName);
4653
4696
  const effective = covers(table, unit.scopes)
@@ -4666,10 +4709,12 @@ export class SyncClient {
4666
4709
  unit.id,
4667
4710
  ]);
4668
4711
  try {
4669
- summary.segmentRowsApplied += await apply(table, clearFirst, effective, () => (owners ??=
4712
+ const work = apply(table, clearFirst, effective, () => (owners ??=
4670
4713
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [table.name]).length > 0 || this.#scopedRowsExist(table, effective, [])
4671
4714
  ? unitOwners(loadUnits(this.#db), table, unit.id)
4672
4715
  : []));
4716
+ summary.segmentRowsApplied +=
4717
+ typeof work === 'function' ? (yield work) : yield* work;
4673
4718
  section.seeded.add(tableName);
4674
4719
  }
4675
4720
  catch (error) {
@@ -4727,7 +4772,7 @@ export class SyncClient {
4727
4772
  ]))),
4728
4773
  byteLength: frame.byteLength,
4729
4774
  onProgress,
4730
- ...(signal !== undefined ? { signal } : {}),
4775
+ ...definedObject({ signal }),
4731
4776
  });
4732
4777
  }
4733
4778
  // §5.4: the descriptor's byteLength caps the body; §5.1: verify the
@@ -4936,20 +4981,6 @@ export class SyncClient {
4936
4981
  const values = table.columns.map((column) => jsonToRowValue(image.values?.[column.name] ?? null));
4937
4982
  upsertLocalRow(this.#db, table, values, image.syncVersion);
4938
4983
  }
4939
- #legacyUndoOptimisticRows(commit, batch) {
4940
- for (const operation of commit.operations) {
4941
- if (operation.op !== 'upsert')
4942
- continue;
4943
- const table = this.#schema.tables.get(operation.table);
4944
- if (table === undefined)
4945
- continue;
4946
- const row = this.#rowById(table, operation.rowId, `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`);
4947
- if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
4948
- batch.table(table.name);
4949
- deleteLocalRow(this.#db, table, operation.rowId);
4950
- }
4951
- }
4952
- }
4953
4984
  #rollbackFailedCommit(commit, batch, classifiedFailures) {
4954
4985
  const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
4955
4986
  const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
@@ -4967,7 +4998,16 @@ export class SyncClient {
4967
4998
  else {
4968
4999
  // Pending commits written by older clients have no before-images.
4969
5000
  // Preserve the old fail-closed behavior rather than guessing a base.
4970
- this.#legacyUndoOptimisticRows(commit, batch);
5001
+ for (const operation of commit.operations) {
5002
+ if (operation.op !== 'upsert')
5003
+ continue;
5004
+ const table = this.#schema.tables.get(operation.table);
5005
+ if (table !== undefined &&
5006
+ this.#rowById(table, operation.rowId, `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`)?.v === OPTIMISTIC_VERSION) {
5007
+ batch.table(table.name);
5008
+ deleteLocalRow(this.#db, table, operation.rowId);
5009
+ }
5010
+ }
4971
5011
  }
4972
5012
  deleteOutboxCommit(this.#db, commit.clientCommitId);
4973
5013
  if (!complete)
@@ -5245,10 +5285,7 @@ export class SyncClient {
5245
5285
  function requireRowId(value) {
5246
5286
  if (typeof value === 'string' && value.length > 0)
5247
5287
  return value;
5248
- if (typeof value === 'number' && Number.isSafeInteger(value)) {
5249
- return String(value);
5250
- }
5251
- if (typeof value === 'boolean')
5288
+ if (Number.isSafeInteger(value) || typeof value === 'boolean')
5252
5289
  return String(value);
5253
5290
  throw invalidRequest('a mutation requires a non-empty primary key');
5254
5291
  }