@syncular/client 0.58.0 → 0.59.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.
Files changed (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
package/dist/client.js CHANGED
@@ -14,21 +14,20 @@ 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, decodeMessage, DecodeError, decodeRow, decodeRowsSegment, encodeMessage, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
17
+ import { canonicalScopeJson, decodeMessage, DecodeError, decodeRow, decodeRowsSegment, encodeMessage, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
18
18
  import { EncryptError } from '@syncular/core';
19
19
  import { EncodeError } from '@syncular/core';
20
- import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
20
+ import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
21
21
  import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
22
22
  import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
23
- import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
23
+ import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, transportFailed, } from './errors.js';
24
24
  import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
25
25
  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, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
29
+ import { appendOutboxCommit, 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
- import { assertReadOnlyQuery } from './query-guard.js';
32
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';
33
32
  import { compileClientSchema, 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';
34
33
  import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, saveSubscriptionScopeSchema, resetSubscriptionsForBump, saveSubscription, setMeta, SUBSCRIPTIONS_TABLE, } from './state.js';
@@ -93,6 +92,12 @@ const PREVIOUS_VERSION_DEFAULT_MAX_ROWS = 20_000;
93
92
  const PREVIOUS_VERSION_DEFAULT_MAX_TABLES = 32;
94
93
  const PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES = 1024 * 1024;
95
94
  const PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
95
+ /** §7.7: an explicit round budget is a strict positive u32 count. */
96
+ function requireRoundBudget(maxRounds) {
97
+ if (maxRounds !== undefined &&
98
+ (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
99
+ throw invalidRequest('maxRounds must be a positive integer');
100
+ }
96
101
  function boundedBudget(value, fallback, name) {
97
102
  if (value === undefined)
98
103
  return fallback;
@@ -169,6 +174,10 @@ export class SyncClient {
169
174
  #realtimeRetryDelayMs;
170
175
  #realtimeConnectPromise;
171
176
  #realtimeGeneration = 0;
177
+ #heartbeatMs;
178
+ #schedule;
179
+ /** SPEC §8.5: cancels the armed heartbeat watchdog; unset while unarmed. */
180
+ #watchdog;
172
181
  #pendingRound;
173
182
  #needsPull = false;
174
183
  #progress = new ProgressEmitter();
@@ -283,6 +292,19 @@ export class SyncClient {
283
292
  if (realtimePolicy === 'required' && config.realtime === undefined) {
284
293
  throw invalidRequest("realtimePolicy 'required' needs a realtime connector");
285
294
  }
295
+ // Twice the interval must stay within the 2^31 - 1 ms timer range.
296
+ const heartbeatMs = config.realtimeHeartbeatMs ?? 30_000;
297
+ if (!Number.isInteger(heartbeatMs) ||
298
+ heartbeatMs < 1 ||
299
+ heartbeatMs > 2 ** 30)
300
+ throw invalidRequest('realtimeHeartbeatMs must be an integer in 1..=2^30');
301
+ this.#heartbeatMs = heartbeatMs;
302
+ this.#schedule =
303
+ config.schedule ??
304
+ ((callback, delayMs) => {
305
+ const timer = setTimeout(callback, delayMs);
306
+ return () => clearTimeout(timer);
307
+ });
286
308
  this.#config = config;
287
309
  this.#realtimePolicy = realtimePolicy;
288
310
  this.#realtimeState =
@@ -716,6 +738,7 @@ export class SyncClient {
716
738
  return;
717
739
  this.#transportEnabled = enabled;
718
740
  this.#transportEpoch += 1;
741
+ this.#disarm();
719
742
  if (!enabled && !this.#syncOutstanding)
720
743
  this.disconnectRealtime();
721
744
  this.#emitSyncIntent(enabled && this.#securityLifecycle === 'active'
@@ -809,8 +832,8 @@ export class SyncClient {
809
832
  return this.#db;
810
833
  }
811
834
  /**
812
- * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only
813
- * statement only — writes must go through `mutate()` so they hit the
835
+ * The raw-SQL read tier. Guarded (query-guard.ts): a single statement
836
+ * SQLite reports read-only — writes must go through `mutate()` so they hit the
814
837
  * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
815
838
  * result, so a `SELECT *` row is safe to feed back into `mutate()`
816
839
  * values; alias explicitly (`_sync_version AS v`) to read one. Engine
@@ -818,11 +841,10 @@ export class SyncClient {
818
841
  */
819
842
  query(sql, params) {
820
843
  this.#requireActive();
821
- assertReadOnlyQuery(sql);
822
844
  // RFC 0005's container lives in a separate database file, so this
823
845
  // connection cannot see it and there is no table-access guard to run.
824
846
  try {
825
- return stripSyncColumns(this.#db.query(sql, params));
847
+ return stripSyncColumns(this.#db.queryReadOnly(sql, params));
826
848
  }
827
849
  catch (error) {
828
850
  throw classifySqliteFailure(error).error;
@@ -951,12 +973,9 @@ export class SyncClient {
951
973
  };
952
974
  let read;
953
975
  try {
954
- for (const statement of request.statements) {
955
- assertReadOnlyQuery(statement.sql);
956
- }
957
976
  read = this.#db.transaction(() => {
958
977
  const revision = getLocalRevision(this.#db);
959
- const queries = request.statements.map((statement) => stripSyncColumns(this.#db.query(statement.sql, statement.params)));
978
+ const queries = request.statements.map((statement) => stripSyncColumns(this.#db.queryReadOnly(statement.sql, statement.params)));
960
979
  const pending = [];
961
980
  const missing = [];
962
981
  for (const requested of request.coverage ?? []) {
@@ -1556,7 +1575,7 @@ export class SyncClient {
1556
1575
  }
1557
1576
  async #uploadBlob(bytes, options) {
1558
1577
  if (this.#config.blobs === undefined) {
1559
- throw invalidRequest('uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
1578
+ throw invalidRequest('uploadBlob requires a blob transport');
1560
1579
  }
1561
1580
  const blobId = await computeBlobId(bytes);
1562
1581
  const nowMs = this.#now();
@@ -1586,43 +1605,48 @@ export class SyncClient {
1586
1605
  return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
1587
1606
  }
1588
1607
  async #fetchBlob(blobIdOrRef) {
1589
- const blobId = blobIdOrRef.startsWith('sha256:')
1590
- ? blobIdOrRef
1591
- : parseBlobRef(blobIdOrRef).blobId;
1608
+ // A BlobRef declares the size that caps the download (§5.9.5); a bare
1609
+ // blobId declares none.
1610
+ const ref = blobIdOrRef.startsWith('sha256:')
1611
+ ? undefined
1612
+ : parseBlobRef(blobIdOrRef);
1613
+ const blobId = ref?.blobId ?? blobIdOrRef;
1592
1614
  const cached = getCachedBlob(this.#db, blobId);
1593
1615
  if (cached !== undefined)
1594
1616
  return cached;
1595
1617
  const transport = this.#config.blobs;
1596
1618
  if (transport === undefined) {
1597
- throw invalidRequest('fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
1619
+ throw invalidRequest('fetchBlob requires a blob transport');
1598
1620
  }
1599
1621
  // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
1600
1622
  // presign configured) a signed url the client fetches directly. On a url
1601
1623
  // arm the client MUST NOT attach host auth and MUST NOT fall through:
1602
1624
  // failure => re-request, the caller's next fetchBlob mints a fresh url.
1603
1625
  this.#requireTransport();
1604
- const response = await transport.download(blobId);
1626
+ const response = await transport.download(blobId, ref?.byteLength);
1605
1627
  let bytes;
1606
1628
  if (response.kind === 'url') {
1607
1629
  if (transport.fetchUrl === undefined) {
1608
- throw invalidRequest('blob download returned a url but the transport cannot fetch urls (§5.9.5)');
1630
+ throw invalidRequest('blob transport cannot fetch urls');
1609
1631
  }
1610
1632
  if (response.urlExpiresAtMs !== undefined &&
1611
1633
  response.urlExpiresAtMs <= this.#now()) {
1612
1634
  // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
1613
- throw new ClientSyncError('sync.segment_expired', `blob url for ${blobId} expired before fetch — re-request mints a fresh url (§5.9.5)`, true);
1635
+ throw new ClientSyncError('sync.segment_expired', 'blob url expired before fetch', true);
1614
1636
  }
1615
- bytes = await transport.fetchUrl(response.url);
1637
+ bytes = await transport.fetchUrl(response.url, ref?.byteLength);
1616
1638
  }
1617
1639
  else {
1618
1640
  bytes = response.bytes;
1619
1641
  }
1620
- const computed = await computeBlobId(bytes);
1621
- if (computed !== blobId) {
1622
- // §5.9.5 inherits §5.1: verify the content address, reject on mismatch.
1623
- // On the url path this invalidates the fetch (no fall-through) — the
1624
- // next fetchBlob re-requests the authorized endpoint (§5.9.5 recovery).
1625
- throw invalidRequest(`blob content address mismatch for ${blobId} (§5.9.5)`);
1642
+ // §5.9.5 inherits §5.1: the declared size caps the body and the content
1643
+ // address must match. On the url path either failure invalidates the
1644
+ // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
1645
+ if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
1646
+ throw invalidRequest('blob exceeds its byteLength');
1647
+ }
1648
+ if ((await computeBlobId(bytes)) !== blobId) {
1649
+ throw invalidRequest('blob content address mismatch');
1626
1650
  }
1627
1651
  putCachedBlob(this.#db, blobId, bytes, this.#now());
1628
1652
  this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
@@ -1640,15 +1664,23 @@ export class SyncClient {
1640
1664
  return;
1641
1665
  enforceBlobCacheCap(this.#db, this.#schema, cap);
1642
1666
  }
1643
- /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
1667
+ /**
1668
+ * Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. It
1669
+ * runs on the round's operation chain because a refused upload drops
1670
+ * outbox commits a round may have captured.
1671
+ */
1644
1672
  flushBlobUploads() {
1645
1673
  this.#requireTransport();
1646
- return this.#runProtectedAsync(() => this.#flushBlobUploads());
1674
+ return this.#runProtectedAsync(async () => {
1675
+ await this.#serialize(() => this.#flushBlobUploads(undefined));
1676
+ });
1647
1677
  }
1648
- async #flushBlobUploads() {
1678
+ /** Returns the ids of the commits a refused upload dropped (§5.9.7). */
1679
+ async #flushBlobUploads(signal) {
1680
+ const refused = new Set();
1649
1681
  const transport = this.#config.blobs;
1650
1682
  if (transport === undefined || !this.#hasBlobs)
1651
- return;
1683
+ return refused;
1652
1684
  for (const pending of listPendingUploads(this.#db)) {
1653
1685
  const cached = getCachedBlob(this.#db, pending.blobId);
1654
1686
  if (cached === undefined ||
@@ -1658,9 +1690,36 @@ export class SyncClient {
1658
1690
  (await computeBlobId(cached.bytes)) !== pending.blobId) {
1659
1691
  throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload body is missing or corrupt');
1660
1692
  }
1661
- await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType);
1693
+ try {
1694
+ await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType, signal);
1695
+ }
1696
+ catch (error) {
1697
+ // §5.9.7: a non-retryable server refusal is this body's final
1698
+ // outcome. Retryable refusals and transport failures fail the round.
1699
+ // A failure without a server code (`sync.transport_failed`: no
1700
+ // response, or a response without a JSON error body) is not one.
1701
+ if (!(error instanceof Error) ||
1702
+ !('code' in error) ||
1703
+ typeof error.code !== 'string' ||
1704
+ error.code === 'sync.transport_failed' ||
1705
+ !('retryable' in error) ||
1706
+ error.retryable !== false)
1707
+ throw error;
1708
+ clearPendingUpload(this.#db, pending.blobId);
1709
+ const referencing = new Set(this.#db
1710
+ .query(`SELECT commit_id FROM ${BLOB_COMMIT_REFS} WHERE blob_id=?`, [pending.blobId])
1711
+ .map((row) => row.commit_id));
1712
+ for (const commit of listOutbox(this.#db)) {
1713
+ if (!referencing.has(commit.clientCommitId))
1714
+ continue;
1715
+ this.#dropIncompatibleCommit(commit, error.message, error.code);
1716
+ refused.add(commit.clientCommitId);
1717
+ }
1718
+ continue;
1719
+ }
1662
1720
  clearPendingUpload(this.#db, pending.blobId);
1663
1721
  }
1722
+ return refused;
1664
1723
  }
1665
1724
  /**
1666
1725
  * §5.9.3: upload one blob, preferring the presigned direct-to-storage grant
@@ -1670,17 +1729,17 @@ export class SyncClient {
1670
1729
  * *different, host-authenticated capability*, not a fall-through of the
1671
1730
  * grant's authority (the direct endpoint was always the other path, B4).
1672
1731
  */
1673
- async #uploadOne(transport, blobId, bytes, mediaType) {
1732
+ async #uploadOne(transport, blobId, bytes, mediaType, signal) {
1674
1733
  if (transport.uploadGrant !== undefined &&
1675
1734
  transport.uploadToUrl !== undefined) {
1676
- const grant = await transport.uploadGrant(blobId, bytes.length, mediaType);
1735
+ const grant = await transport.uploadGrant(blobId, bytes.length, mediaType, signal);
1677
1736
  if (grant.kind === 'present')
1678
1737
  return; // idempotent §5.9.3 — no PUT needed
1679
1738
  if (grant.kind === 'url') {
1680
1739
  if (grant.urlExpiresAtMs === undefined ||
1681
1740
  grant.urlExpiresAtMs > this.#now()) {
1682
1741
  try {
1683
- await transport.uploadToUrl(grant.url, bytes, mediaType);
1742
+ await transport.uploadToUrl(grant.url, bytes, mediaType, signal);
1684
1743
  return;
1685
1744
  }
1686
1745
  catch {
@@ -1691,7 +1750,7 @@ export class SyncClient {
1691
1750
  // grant.kind === 'none' (no presign store) or a failed/expired grant:
1692
1751
  // stream through the direct host-authenticated endpoint.
1693
1752
  }
1694
- await transport.upload(blobId, bytes, mediaType);
1753
+ await transport.upload(blobId, bytes, mediaType, signal);
1695
1754
  }
1696
1755
  conflicts() {
1697
1756
  this.#requireActive();
@@ -1709,9 +1768,7 @@ export class SyncClient {
1709
1768
  /** Prove all retained bases against a completed post-rejection pull (§7.2.1). */
1710
1769
  async proveCurrentBase(outcome, maxRounds) {
1711
1770
  this.#requireActive();
1712
- if (maxRounds !== undefined &&
1713
- (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
1714
- throw invalidRequest('maxRounds must be a positive integer');
1771
+ requireRoundBudget(maxRounds);
1715
1772
  const { clientCommitId, sequence } = outcome;
1716
1773
  const provable = (candidate) => candidate !== undefined &&
1717
1774
  candidate.sequence === sequence &&
@@ -1929,9 +1986,11 @@ export class SyncClient {
1929
1986
  return [...this.#presence.keys()];
1930
1987
  }
1931
1988
  /**
1932
- * §8.6: subscribe to presence changes (join/update/leave on any held key).
1933
- * The subscribable twin of the `onPresence` config callback — React's
1934
- * `usePresence` targets this so many components can watch one client.
1989
+ * §8.6: subscribe to presence changes (join/update/leave on any held key)
1990
+ * and to the server's refusal of this client's own publish (`error`,
1991
+ * §8.6.2). The subscribable twin of the `onPresence` config callback —
1992
+ * React's `usePresence` targets this so many components can watch one
1993
+ * client.
1935
1994
  * Returns an unsubscribe function.
1936
1995
  */
1937
1996
  onPresence(listener) {
@@ -2170,7 +2229,7 @@ export class SyncClient {
2170
2229
  let remaining = false;
2171
2230
  this.#applyBatch((batch) => {
2172
2231
  this.#db.transaction(() => {
2173
- const result = evictScopedRows(this.#db, table, effective, pinned);
2232
+ const result = evictScopedRows(this.#db, table, effective, this.#scopeOwners(base.table, subId), pinned);
2174
2233
  remaining = result.remaining;
2175
2234
  deleteWindowUnit(this.#db, baseKey, unit);
2176
2235
  deleteSubscription(this.#db, subId);
@@ -2214,7 +2273,7 @@ export class SyncClient {
2214
2273
  const pinned = this.#pinnedRowIds(entry.table);
2215
2274
  remaining = false;
2216
2275
  this.#applyBatch((batch) => {
2217
- const result = evictScopedRows(this.#db, table, entry.effective, pinned);
2276
+ const result = evictScopedRows(this.#db, table, entry.effective, this.#scopeOwners(entry.table, entry.subId), pinned);
2218
2277
  remaining = result.remaining;
2219
2278
  if (!result.deferred)
2220
2279
  deletePendingEviction(this.#db, entry.subId);
@@ -2225,6 +2284,20 @@ export class SyncClient {
2225
2284
  } while (remaining);
2226
2285
  }
2227
2286
  }
2287
+ /**
2288
+ * §3.3/§4.8/§5.6 row ownership: the effective scopes of every other
2289
+ * active subscription on `table` that holds rows (`cursor >= 0`). A
2290
+ * scoped delete keeps every row one of them still covers.
2291
+ */
2292
+ #scopeOwners(table, exceptId) {
2293
+ return loadSubscriptions(this.#db).flatMap((sub) => sub.id !== exceptId &&
2294
+ sub.table === table &&
2295
+ sub.status === 'active' &&
2296
+ sub.cursor >= 0 &&
2297
+ sub.effectiveScopes !== undefined
2298
+ ? [sub.effectiveScopes]
2299
+ : []);
2300
+ }
2228
2301
  /**
2229
2302
  * §4.8 E1: primary keys of `table` referenced by any still-pending outbox
2230
2303
  * commit — rows that MUST NOT be evicted until the commit drains.
@@ -2257,6 +2330,9 @@ export class SyncClient {
2257
2330
  const operations = mutations.map((mutation) => {
2258
2331
  const table = this.#table(mutation.table);
2259
2332
  if (mutation.op === 'delete') {
2333
+ // §2.4: the server rejects a rowId holding U+0000.
2334
+ if (mutation.rowId.includes('\u0000'))
2335
+ throw invalidRequest('rowId holds U+0000');
2260
2336
  return definedObject({
2261
2337
  table: mutation.table,
2262
2338
  rowId: mutation.rowId,
@@ -2865,6 +2941,10 @@ export class SyncClient {
2865
2941
  * `setWindow` at an await point.
2866
2942
  */
2867
2943
  sync() {
2944
+ return this.#sync();
2945
+ }
2946
+ /** `signal` is the `syncUntilIdle` deadline (§7.7); `sync()` has none. */
2947
+ #sync(signal) {
2868
2948
  this.#requireActive();
2869
2949
  if (this.#syncOutstanding) {
2870
2950
  return Promise.reject(invalidRequest('sync() is already running; coalesce wake-ups'));
@@ -2872,7 +2952,7 @@ export class SyncClient {
2872
2952
  this.#syncOutstanding = true;
2873
2953
  this.#beginDiagnosticsDeferral();
2874
2954
  const startedAtMs = this.#now();
2875
- return this.#serialize(() => this.#runSync())
2955
+ return this.#serialize(() => this.#runSync(signal))
2876
2956
  .then((summary) => {
2877
2957
  const completedAtMs = this.#now();
2878
2958
  this.#lastRound = {
@@ -2978,7 +3058,7 @@ export class SyncClient {
2978
3058
  ? code
2979
3059
  : 'client.unknown_failure';
2980
3060
  }
2981
- async #runSync() {
3061
+ async #runSync(signal) {
2982
3062
  this.#requireTransport();
2983
3063
  this.#roundRetryDelayMs = undefined;
2984
3064
  this.#progress.emit({
@@ -3029,7 +3109,15 @@ export class SyncClient {
3029
3109
  if (logEpoch !== undefined &&
3030
3110
  this.#hasBlobs &&
3031
3111
  this.#config.blobs !== undefined) {
3032
- await this.#flushBlobUploads();
3112
+ const refused = await this.#flushBlobUploads(signal);
3113
+ // §5.9.7: a commit whose blob the server refused left the outbox.
3114
+ for (let index = outbox.length - 1; index >= 0; index--) {
3115
+ if (!refused.has(outbox[index].clientCommitId))
3116
+ continue;
3117
+ outbox.splice(index, 1);
3118
+ pushFrames.splice(index, 1);
3119
+ frameBytes.splice(index, 1);
3120
+ }
3033
3121
  }
3034
3122
  // Captured after encoding: a subscribe/unsubscribe during the
3035
3123
  // encryption await must not make the final request exceed the byte
@@ -3095,14 +3183,14 @@ export class SyncClient {
3095
3183
  msgKind: 'request',
3096
3184
  frames,
3097
3185
  });
3098
- const responseBytes = await this.#roundTrip(requestBytes);
3186
+ const responseBytes = await this.#roundTrip(requestBytes, signal);
3099
3187
  const message = decodeMessage(responseBytes);
3100
3188
  if (message.msgKind !== 'response') {
3101
3189
  throw invalidRequest('transport returned a non-response message');
3102
3190
  }
3103
3191
  // §1.5: a complete, decodable response ends the report obligation.
3104
3192
  this.#roundFailureCode = undefined;
3105
- const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
3193
+ const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch, signal);
3106
3194
  // §4.8 E1: the push half may have drained commits that pinned rows of
3107
3195
  // a shrunk window unit — retry any deferred evictions now.
3108
3196
  await this.#drainPendingEvictions();
@@ -3110,6 +3198,10 @@ export class SyncClient {
3110
3198
  ? { state: 'failed', errorCode: 'sync.scope_revoked' }
3111
3199
  : { state: 'complete' });
3112
3200
  this.#retryDelayMs = 250;
3201
+ // §4.7: a subscription that still holds a resume token needs another
3202
+ // round, also when the drive that started its bootstrap ends early.
3203
+ if (summary.bootstrapping.length > 0)
3204
+ this.#setSyncNeeded(true);
3113
3205
  if (deferred > 0) {
3114
3206
  // §6.1 splitBatch remainder: more queued commits than this request
3115
3207
  // could carry — keep the sync-needed signal raised for the host.
@@ -3118,12 +3210,15 @@ export class SyncClient {
3118
3210
  }
3119
3211
  return summary;
3120
3212
  }
3121
- catch (error) {
3213
+ catch (caught) {
3122
3214
  // §1.5: a round that ended without a complete, decodable response is a
3123
3215
  // failure the server could not see — keep its code for the next request.
3124
- const unseen = this.#unseenRoundFailureCode(error);
3216
+ const unseen = this.#unseenRoundFailureCode(caught);
3125
3217
  if (unseen !== undefined)
3126
3218
  this.#roundFailureCode = unseen;
3219
+ // §7.7: a round the drive deadline aborted ends with the deadline's
3220
+ // error, whichever transport call observed the abort.
3221
+ const error = signal?.aborted === true ? signal.reason : caught;
3127
3222
  // §7.3.5: a request-level lease code stops-and-surfaces — record it
3128
3223
  // in leaseState (no local-data purge, §7.3.4) and re-throw. Not a
3129
3224
  // silent retry: the app drives recovery to a live resolver. The
@@ -3154,6 +3249,9 @@ export class SyncClient {
3154
3249
  ? details.causeKind
3155
3250
  : undefined;
3156
3251
  const unreachable = causeKind === 'connect' || causeKind === 'network';
3252
+ // The round's work is still owed; the host's connectivity resume runs it.
3253
+ if (unreachable)
3254
+ this.#setSyncNeeded(true);
3157
3255
  if (retryable && !unreachable) {
3158
3256
  const realtimeUnavailable = error instanceof RealtimeUnavailableError;
3159
3257
  const delay = realtimeUnavailable
@@ -3199,9 +3297,7 @@ export class SyncClient {
3199
3297
  : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
3200
3298
  // §7.7: an explicit budget is a strict positive round count. Zero,
3201
3299
  // fractional, and out-of-range values are caller errors.
3202
- if (maxRounds !== undefined &&
3203
- (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
3204
- throw invalidRequest('maxRounds must be a positive integer');
3300
+ requireRoundBudget(maxRounds);
3205
3301
  if (timeoutMs !== Number.POSITIVE_INFINITY &&
3206
3302
  !(Number.isFinite(timeoutMs) && timeoutMs > 0))
3207
3303
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
@@ -3233,17 +3329,8 @@ export class SyncClient {
3233
3329
  async #syncIdleRounds(maxRounds, timeoutMs) {
3234
3330
  const budget = maxRounds ?? 20;
3235
3331
  const aggregate = {
3236
- pushed: 0,
3237
- applied: [],
3238
- rejected: [],
3239
- retryable: [],
3240
- conflicts: [],
3241
- commitsApplied: 0,
3242
- segmentRowsApplied: 0,
3332
+ ...emptySummary(0),
3243
3333
  bootstrapping: [],
3244
- resets: [],
3245
- revoked: [],
3246
- failed: [],
3247
3334
  deferredCommits: 0,
3248
3335
  schemaFloor: undefined,
3249
3336
  };
@@ -3270,27 +3357,32 @@ export class SyncClient {
3270
3357
  let round = 0;
3271
3358
  let expired = false;
3272
3359
  let timer;
3360
+ // One signal reaches every transport call of the drive's rounds.
3361
+ const controller = new AbortController();
3362
+ const expiredError = () => new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3273
3363
  const deadline = timeoutMs === Number.POSITIVE_INFINITY
3274
3364
  ? undefined
3275
3365
  : new Promise((_, reject) => {
3276
3366
  timer = setTimeout(() => {
3277
3367
  expired = true;
3368
+ const error = expiredError();
3278
3369
  // The transport may never answer; release the round so the
3279
3370
  // client can run another one after the caller sees the error.
3371
+ controller.abort(error);
3280
3372
  this.#abortPendingRound('syncUntilIdle deadline exceeded');
3281
- reject(new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round }));
3373
+ reject(error);
3282
3374
  }, timeoutMs);
3283
3375
  });
3284
3376
  const drive = (async () => {
3285
3377
  for (; round < budget; round++) {
3286
3378
  // The race already rejected; stop spending rounds on a dead drive.
3287
3379
  if (expired)
3288
- throw new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3380
+ throw expiredError();
3289
3381
  const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
3290
3382
  sub.id,
3291
3383
  sub.bootstrapState,
3292
3384
  ]));
3293
- const last = await this.sync();
3385
+ const last = await this.#sync(controller.signal);
3294
3386
  // Historical counters accumulate; current readiness (`bootstrapping`,
3295
3387
  // `deferredCommits`, `schemaFloor`) describes the latest round.
3296
3388
  aggregate.pushed += last.pushed;
@@ -3347,7 +3439,7 @@ export class SyncClient {
3347
3439
  * refuses the round with `RealtimeUnavailableError` instead of using the
3348
3440
  * seam (SPEC §8.8).
3349
3441
  */
3350
- #roundTrip(request) {
3442
+ #roundTrip(request, signal) {
3351
3443
  const socket = this.#socket;
3352
3444
  if (socket !== undefined && this.#realtimePolicy !== 'off') {
3353
3445
  return new Promise((resolve, reject) => {
@@ -3368,7 +3460,9 @@ export class SyncClient {
3368
3460
  // The socket could not carry the round: record the same loss the
3369
3461
  // Rust core records when its realtime round call fails (§8.8).
3370
3462
  this.#setRealtimeState('lost', 'sync.transport_failed');
3371
- reject(new ClientSyncError('sync.transport_failed', 'socket round send failed', true, { causeKind: 'unknown' }));
3463
+ reject(transportFailed('socket round send failed', {
3464
+ causeKind: 'unknown',
3465
+ }));
3372
3466
  }
3373
3467
  });
3374
3468
  }
@@ -3378,13 +3472,15 @@ export class SyncClient {
3378
3472
  throw this.#realtimeUnavailableError();
3379
3473
  }
3380
3474
  return Promise.resolve()
3381
- .then(() => this.#config.transport(request))
3475
+ .then(() => this.#config.transport(request, signal))
3382
3476
  .catch((error) => {
3383
3477
  if (error instanceof ClientSyncError ||
3384
3478
  typeof error?.code === 'string') {
3385
3479
  throw error;
3386
3480
  }
3387
- throw new ClientSyncError('sync.transport_failed', 'transport round failed', true, { causeKind: 'unknown' });
3481
+ throw transportFailed('transport round failed', {
3482
+ causeKind: 'unknown',
3483
+ });
3388
3484
  });
3389
3485
  }
3390
3486
  /**
@@ -3412,7 +3508,7 @@ export class SyncClient {
3412
3508
  if (round === undefined)
3413
3509
  return;
3414
3510
  this.#pendingRound = undefined;
3415
- round.reject(new ClientSyncError('sync.transport_failed', reason, true));
3511
+ round.reject(typeof reason === 'string' ? transportFailed(reason) : reason);
3416
3512
  }
3417
3513
  // -- realtime (§8 client side) ----------------------------------------------
3418
3514
  /**
@@ -3464,17 +3560,19 @@ export class SyncClient {
3464
3560
  onText: (text) => {
3465
3561
  if (generation !== this.#realtimeGeneration || !this.#started)
3466
3562
  return;
3467
- this.#handleRealtimeText(text);
3563
+ this.#heard(this.#handleRealtimeText(text));
3468
3564
  },
3469
3565
  onBinary: (bytes) => {
3470
3566
  if (generation !== this.#realtimeGeneration || !this.#started)
3471
3567
  return;
3568
+ this.#heard();
3472
3569
  this.#routeRealtimeBinary(bytes);
3473
3570
  },
3474
3571
  onClose: () => {
3475
3572
  if (openedSocket === undefined || this.#socket !== openedSocket)
3476
3573
  return;
3477
3574
  this.#socket = undefined;
3575
+ this.#disarm();
3478
3576
  this.#presence.clear(); // §8.6.1: presence is per-connection
3479
3577
  // §8.8: an undesired close is a visible lost state, not a silent
3480
3578
  // downgrade to HTTP rounds.
@@ -3482,7 +3580,7 @@ export class SyncClient {
3482
3580
  this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
3483
3581
  this.#emitDiagnostics();
3484
3582
  },
3485
- });
3583
+ }, this.#clientId);
3486
3584
  openedSocket = socket;
3487
3585
  if (!this.#transportEnabled) {
3488
3586
  socket.close();
@@ -3513,6 +3611,7 @@ export class SyncClient {
3513
3611
  this.#realtimeConnectPromise = undefined;
3514
3612
  this.#socket?.close();
3515
3613
  this.#socket = undefined;
3614
+ this.#disarm();
3516
3615
  this.#presence.clear(); // §8.6.1: presence is per-connection
3517
3616
  this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
3518
3617
  this.#setRealtimeState(this.#realtimePolicy === 'off'
@@ -3527,14 +3626,37 @@ export class SyncClient {
3527
3626
  * Close the socket and record the loss; later rounds use the configured
3528
3627
  * transport until the supervisor reconnects.
3529
3628
  */
3530
- #loseSocket() {
3629
+ #loseSocket(code = REALTIME_LOST_CODE) {
3531
3630
  const socket = this.#socket;
3532
3631
  this.#socket = undefined;
3632
+ this.#disarm();
3533
3633
  this.#presence.clear(); // §8.6.1: presence is per-connection
3534
- this.#setRealtimeState('lost', REALTIME_LOST_CODE);
3634
+ this.#setRealtimeState('lost', code);
3535
3635
  socket?.close();
3536
3636
  this.#emitDiagnostics();
3537
3637
  }
3638
+ /**
3639
+ * SPEC §8.5 watchdog: the connection's first `heartbeat` arms it; once
3640
+ * armed, every inbound frame restarts it, and twice the interval of
3641
+ * silence loses the socket. A server that sends no heartbeats never arms it.
3642
+ */
3643
+ #heard(heartbeat) {
3644
+ if (this.#socket === undefined ||
3645
+ !this.#transportEnabled ||
3646
+ (this.#watchdog === undefined && heartbeat !== true))
3647
+ return;
3648
+ this.#watchdog?.();
3649
+ this.#watchdog = this.#schedule(() => {
3650
+ this.#loseSocket('transport.timeout');
3651
+ this.#abortPendingRound(new ClientSyncError('transport.timeout', 'realtime heartbeat missed', true, {
3652
+ causeKind: 'heartbeat',
3653
+ }));
3654
+ }, 2 * this.#heartbeatMs);
3655
+ }
3656
+ #disarm() {
3657
+ this.#watchdog?.();
3658
+ this.#watchdog = undefined;
3659
+ }
3538
3660
  /**
3539
3661
  * §8.7 channel-tag routing (synchronous, so chunk order is preserved):
3540
3662
  * `0x01` chunks feed the in-flight round's assembler; `0x00` messages
@@ -3575,6 +3697,7 @@ export class SyncClient {
3575
3697
  }
3576
3698
  // Unknown tag: tolerated and ignored (§8.7 closed registry).
3577
3699
  }
3700
+ /** Returns whether the text was a §8.5 `heartbeat`. */
3578
3701
  #handleRealtimeText(text) {
3579
3702
  let parsed;
3580
3703
  try {
@@ -3599,43 +3722,40 @@ export class SyncClient {
3599
3722
  this.#emitSyncNeeded(event.data.reason);
3600
3723
  return;
3601
3724
  }
3602
- if (event.event === 'presence') {
3725
+ if (event.event === 'presence')
3603
3726
  this.#applyPresence(event.data);
3604
- }
3727
+ return event.event === 'heartbeat';
3605
3728
  }
3606
- /** §8.6 apply an inbound presence fanout to the local map. */
3729
+ /**
3730
+ * §8.6 apply an inbound presence fanout to the local map, or hand a
3731
+ * publisher-directed rejection (§8.6.2) to the listeners unchanged.
3732
+ */
3607
3733
  #applyPresence(data) {
3608
- // The publisher-directed error variant (§8.6.2) surfaces via the
3609
- // sync-needed reason channel is inappropriate; it is an out-of-band
3610
- // presence rejection — record nothing to the peer map, just ignore
3611
- // here (setPresence callers observe it through the callback if wired).
3612
- if (data.error !== undefined || data.kind === undefined)
3613
- return;
3614
- const { scopeKey, kind, actorId, clientId } = data;
3615
- if (actorId === undefined || clientId === undefined)
3616
- return;
3617
- const peerKey = `${actorId} ${clientId}`;
3618
- let peers = this.#presence.get(scopeKey);
3619
- if (kind === 'leave') {
3620
- peers?.delete(peerKey);
3621
- if (peers !== undefined && peers.size === 0) {
3622
- this.#presence.delete(scopeKey);
3623
- }
3624
- }
3625
- else {
3626
- const doc = data.doc;
3627
- if (doc === null || doc === undefined)
3734
+ const { scopeKey, kind, actorId, clientId, doc, error } = data;
3735
+ if (error === undefined) {
3736
+ // No `kind` is the client→server shape. The parser pins both ids and a
3737
+ // join/update doc on a fanout (§8.6.2); these checks narrow types.
3738
+ if (kind === undefined || actorId === undefined || clientId === undefined)
3628
3739
  return;
3629
- if (peers === undefined) {
3630
- peers = new Map();
3631
- this.#presence.set(scopeKey, peers);
3740
+ const peerKey = `${actorId} ${clientId}`;
3741
+ let peers = this.#presence.get(scopeKey);
3742
+ if (kind === 'leave') {
3743
+ peers?.delete(peerKey);
3744
+ if (peers?.size === 0)
3745
+ this.#presence.delete(scopeKey);
3746
+ }
3747
+ else if (doc) {
3748
+ if (peers === undefined) {
3749
+ peers = new Map();
3750
+ this.#presence.set(scopeKey, peers);
3751
+ }
3752
+ peers.set(peerKey, { actorId, clientId, doc });
3632
3753
  }
3633
- peers.set(peerKey, { actorId, clientId, doc });
3634
3754
  }
3635
- this.#config.onPresence?.(scopeKey);
3755
+ this.#config.onPresence?.(scopeKey, error);
3636
3756
  for (const listener of this.#presenceListeners) {
3637
3757
  try {
3638
- listener(scopeKey);
3758
+ listener(scopeKey, error);
3639
3759
  }
3640
3760
  catch {
3641
3761
  // A UI listener must never break presence application.
@@ -3694,7 +3814,7 @@ export class SyncClient {
3694
3814
  this.#sendAck(Math.min(...cursors));
3695
3815
  }
3696
3816
  // -- response processing ------------------------------------------------------
3697
- async #processResponse(message, sentCommits, sentSubs, mode, resetEpoch = this.#localResetEpoch) {
3817
+ async #processResponse(message, sentCommits, sentSubs, mode, resetEpoch = this.#localResetEpoch, signal) {
3698
3818
  const summary = emptySummary(sentCommits.length);
3699
3819
  const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
3700
3820
  const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
@@ -3714,9 +3834,7 @@ export class SyncClient {
3714
3834
  if (header?.type !== 'RESP_HEADER') {
3715
3835
  throw invalidRequest('missing RESP_HEADER');
3716
3836
  }
3717
- if (message.wireVersion < 2 ||
3718
- header.logEpoch === undefined ||
3719
- header.resetRequired === undefined) {
3837
+ if (message.wireVersion < 2) {
3720
3838
  throw new ClientSyncError('client.invalid_host_response', 'the server response does not carry wire version 2 log-epoch state');
3721
3839
  }
3722
3840
  if (header.requiredSchemaVersion !== undefined) {
@@ -3755,16 +3873,42 @@ export class SyncClient {
3755
3873
  let section;
3756
3874
  let errorFrame;
3757
3875
  let deltaCursor = -1;
3876
+ let deltaDropped = false;
3877
+ // §8.2: a delta section applies only to a locally active subscription
3878
+ // that holds a cursor and no resume token. A subscription at cursor -1
3879
+ // (never synced, reset, or rebootstrapped) bootstraps on its own pull.
3880
+ const skipsSection = (sub) => sub === undefined ||
3881
+ (mode === 'delta' &&
3882
+ (sub.status !== 'active' ||
3883
+ sub.cursor < 0 ||
3884
+ sub.bootstrapState !== undefined));
3758
3885
  const incompleteSubscriptions = new Set(mode === 'pull' ? subsById.keys() : []);
3759
- // §5.4/§5.5: issue every segment download of this response before the
3760
- // apply loop reaches the first one, so a paged bootstrap overlaps its page
3761
- // fetches instead of paying one blocking round trip per page. Eligibility
3762
- // mirrors the loop: a descriptor outside an applied section, inside a
3763
- // skipped delta section, or from an unconfigured downloader is never
3764
- // fetched, and a prefetched failure is only observed where the loop awaits
3765
- // it. A promise left over because an earlier frame ended apply is handled
3766
- // at creation, never unhandled.
3886
+ // §5.4/§5.5: queue every segment download of this response, so a paged
3887
+ // bootstrap overlaps its page fetches instead of paying one blocking round
3888
+ // trip per page. At most four downloads run at once, the Rust native
3889
+ // transport's pool size: enough to overlap round trips, while the client
3890
+ // holds at most four bodies, the one being applied and three ahead. The
3891
+ // loop takes each body out of the map before applying it and tops the
3892
+ // window up at the next descriptor. Eligibility mirrors the loop: a
3893
+ // descriptor outside an applied section, inside a skipped delta section,
3894
+ // or from an unconfigured downloader is never queued, and a failure is
3895
+ // only observed where the loop awaits it. A promise left over because an
3896
+ // earlier frame ended apply is handled at creation, never unhandled.
3897
+ const queued = [];
3767
3898
  const prefetched = new Map();
3899
+ const prefetch = () => {
3900
+ for (let next; prefetched.size < 4 && (next = queued.shift());) {
3901
+ const [frame, sub] = next;
3902
+ const pending = this.#downloadSegment(frame, sub, (bytes) => {
3903
+ // Only the descriptor the loop is applying reports bytes; a
3904
+ // sibling still in flight would overwrite its progress.
3905
+ if (reporting === frame)
3906
+ this.#progress.update({ bytesReceived: bytes });
3907
+ }, signal);
3908
+ pending.catch(() => { });
3909
+ prefetched.set(frame, pending);
3910
+ }
3911
+ };
3768
3912
  let reporting;
3769
3913
  const deleteKey = (commitSeq, table, rowId) => `${commitSeq}\u0000${table}\u0000${rowId}`;
3770
3914
  {
@@ -3772,12 +3916,7 @@ export class SyncClient {
3772
3916
  for (const frame of message.frames) {
3773
3917
  if (frame.type === 'SUB_START') {
3774
3918
  const sub = subsById.get(frame.id);
3775
- openSub =
3776
- sub === undefined ||
3777
- (mode === 'delta' &&
3778
- (sub.status !== 'active' || sub.bootstrapState !== undefined))
3779
- ? undefined
3780
- : sub;
3919
+ openSub = skipsSection(sub) ? undefined : sub;
3781
3920
  }
3782
3921
  else if (frame.type === 'SUB_END') {
3783
3922
  openSub = undefined;
@@ -3790,16 +3929,10 @@ export class SyncClient {
3790
3929
  this.#config.segments !== undefined &&
3791
3930
  !(frame.mediaType === 'sqlite' &&
3792
3931
  (this.#acceptMask() & ACCEPT_SQLITE) === 0)) {
3793
- const pending = this.#downloadSegment(frame, openSub, (bytes) => {
3794
- // Only the descriptor the loop is applying reports bytes; a
3795
- // sibling still in flight would overwrite its progress.
3796
- if (reporting === frame)
3797
- this.#progress.update({ bytesReceived: bytes });
3798
- });
3799
- pending.catch(() => { });
3800
- prefetched.set(frame, pending);
3932
+ queued.push([frame, openSub]);
3801
3933
  }
3802
3934
  }
3935
+ prefetch();
3803
3936
  }
3804
3937
  // §2.2 scope migration: the server emits the delete tagged with the old
3805
3938
  // scope and the upsert tagged with the new one in one commit. A reader
@@ -3817,12 +3950,7 @@ export class SyncClient {
3817
3950
  for (const frame of message.frames) {
3818
3951
  if (frame.type === 'SUB_START') {
3819
3952
  const sub = subsById.get(frame.id);
3820
- openSub =
3821
- sub === undefined ||
3822
- (mode === 'delta' &&
3823
- (sub.status !== 'active' || sub.bootstrapState !== undefined))
3824
- ? undefined
3825
- : sub;
3953
+ openSub = skipsSection(sub) ? undefined : sub;
3826
3954
  }
3827
3955
  else if (frame.type === 'SUB_END') {
3828
3956
  openSub = undefined;
@@ -3931,9 +4059,12 @@ export class SyncClient {
3931
4059
  sub.cursor < 0 &&
3932
4060
  sub.bootstrapState === undefined &&
3933
4061
  frame.bootstrap;
3934
- const skip = sub === undefined ||
3935
- (mode === 'delta' &&
3936
- (sub.status !== 'active' || sub.bootstrapState !== undefined));
4062
+ // §4.4: a section whose registration was removed mid-round
4063
+ // (unsubscribe, eviction) is skipped; it never re-creates it.
4064
+ const skip = skipsSection(sub) ||
4065
+ getSubscription(this.#db, frame.id) === undefined;
4066
+ if (skip && mode === 'delta')
4067
+ deltaDropped = true;
3937
4068
  section = { start: frame, sub, fresh, skip, cleared: false };
3938
4069
  break;
3939
4070
  }
@@ -3976,11 +4107,13 @@ export class SyncClient {
3976
4107
  rowsProcessed: 0,
3977
4108
  rowsTotal: frame.rowCount,
3978
4109
  });
3979
- const prefetch = prefetched.get(frame);
3980
- if (prefetch !== undefined)
4110
+ prefetch();
4111
+ const pending = prefetched.get(frame);
4112
+ prefetched.delete(frame);
4113
+ if (pending !== undefined)
3981
4114
  reporting = frame;
3982
- bytes = await (prefetch ??
3983
- this.#downloadSegment(frame, section.sub, (bytesReceived) => this.#progress.update({ bytesReceived })));
4115
+ bytes = await (pending ??
4116
+ this.#downloadSegment(frame, section.sub, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
3984
4117
  }
3985
4118
  else {
3986
4119
  bytes = frame.payload;
@@ -3993,12 +4126,12 @@ export class SyncClient {
3993
4126
  frame.nextRowCursor !== undefined) {
3994
4127
  throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
3995
4128
  }
3996
- await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
4129
+ await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective, owners) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
3997
4130
  table: frame.table,
3998
4131
  rowCount: frame.rowCount,
3999
4132
  asOfCommitSeq: frame.asOfCommitSeq,
4000
4133
  scopeDigest: frame.scopeDigest,
4001
- }, this.#segmentApplyOptions(table, clearFirst, effective, frame.rowCount > 0, resetEpoch)), section.fresh && !section.cleared);
4134
+ }, this.#segmentApplyOptions(table, clearFirst, effective, owners, frame.rowCount > 0, resetEpoch)), section.fresh && !section.cleared);
4002
4135
  }
4003
4136
  else {
4004
4137
  const segment = decodeRowsSegment(bytes);
@@ -4014,7 +4147,7 @@ export class SyncClient {
4014
4147
  rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
4015
4148
  });
4016
4149
  }
4017
- await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, this.#segmentApplyOptions(table, clearFirst, effective, segment.blocks.some((block) => block.length > 0), resetEpoch), this.#encryption), section.fresh &&
4150
+ await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective, owners) => applyRowsSegment(this.#db, this.#schema, table, segment, this.#segmentApplyOptions(table, clearFirst, effective, owners, segment.blocks.some((block) => block.length > 0), resetEpoch), this.#encryption), section.fresh &&
4018
4151
  !section.cleared &&
4019
4152
  (frame.type === 'SEGMENT_INLINE' ||
4020
4153
  frame.rowCursor === undefined));
@@ -4083,6 +4216,11 @@ export class SyncClient {
4083
4216
  if (mode === 'delta') {
4084
4217
  if (deltaCursor >= 0)
4085
4218
  this.#sendAck(deltaCursor);
4219
+ // §8.2: a skipped delta section is a drop; a pull repairs it.
4220
+ if (deltaDropped) {
4221
+ this.#setSyncNeeded(true);
4222
+ this.#emitSyncNeeded('catchup-required');
4223
+ }
4086
4224
  }
4087
4225
  else {
4088
4226
  this.#ackAfterPull();
@@ -4316,21 +4454,22 @@ export class SyncClient {
4316
4454
  return recorded;
4317
4455
  }
4318
4456
  /** Whether a fresh-bootstrap clear would remove at least one local row. */
4319
- #scopedRowsExist(table, effective) {
4320
- const scope = localScopePredicate(table, effective);
4457
+ #scopedRowsExist(table, effective, owners) {
4458
+ const scope = localScopePredicate(table, effective, owners);
4321
4459
  return (scope !== undefined &&
4322
4460
  this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
4323
4461
  }
4324
4462
  /** Shared transaction, reset fence and progress for both segment formats. */
4325
- #segmentApplyOptions(table, clearFirst, effective, hasRows, resetEpoch) {
4463
+ #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch) {
4326
4464
  return {
4327
4465
  clearFirst,
4328
4466
  effective,
4467
+ owners,
4329
4468
  isCurrent: () => this.#localResetEpoch === resetEpoch,
4330
4469
  onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
4331
4470
  transaction: (fn) => this.#applyBatch((batch) => {
4332
4471
  if (hasRows ||
4333
- (clearFirst && this.#scopedRowsExist(table, effective)))
4472
+ (clearFirst && this.#scopedRowsExist(table, effective, owners)))
4334
4473
  batch.table(table.name);
4335
4474
  const result = fn();
4336
4475
  this.#replayOutbox(result, false);
@@ -4349,12 +4488,15 @@ export class SyncClient {
4349
4488
  return;
4350
4489
  const table = this.#table(sub.table);
4351
4490
  try {
4352
- summary.segmentRowsApplied += await apply(table, clearFirst, section.start.effectiveScopes);
4491
+ summary.segmentRowsApplied += await apply(table, clearFirst, section.start.effectiveScopes, this.#scopeOwners(sub.table, sub.id));
4353
4492
  section.cleared = true;
4354
4493
  }
4355
4494
  catch (error) {
4356
4495
  if (error instanceof ClientSyncError &&
4357
4496
  error.code === 'sync.scope_revoked') {
4497
+ section.skip = true;
4498
+ if (getSubscription(this.#db, sub.id) === undefined)
4499
+ return;
4358
4500
  const registered = getWindowUnitBySubId(this.#db, sub.id);
4359
4501
  this.#applyBatch((batch) => {
4360
4502
  saveSubscription(this.#db, definedObject({
@@ -4372,13 +4514,12 @@ export class SyncClient {
4372
4514
  }
4373
4515
  });
4374
4516
  summary.failed.push(sub.id);
4375
- section.skip = true;
4376
4517
  return;
4377
4518
  }
4378
4519
  throw error;
4379
4520
  }
4380
4521
  }
4381
- async #downloadSegment(frame, sub, onProgress) {
4522
+ async #downloadSegment(frame, sub, onProgress, signal) {
4382
4523
  const downloader = this.#config.segments;
4383
4524
  if (downloader === undefined) {
4384
4525
  throw invalidRequest('received SEGMENT_REF but no segment downloader is configured');
@@ -4399,19 +4540,25 @@ export class SyncClient {
4399
4540
  // §5.4: MUST NOT start a fetch at/past expiry.
4400
4541
  throw new ClientSyncError('sync.segment_expired', `segment download grant expired; pull again (§5.4)`, true);
4401
4542
  }
4402
- bytes = await fetchUrl(frame.url, onProgress);
4543
+ bytes = await fetchUrl(frame.url, onProgress, signal, frame.byteLength);
4403
4544
  }
4404
4545
  else {
4405
4546
  bytes = await downloader({
4406
4547
  segmentId: frame.segmentId,
4407
4548
  table: frame.table,
4408
4549
  requestedScopesJson: canonicalScopeJson(sub.scopes),
4550
+ byteLength: frame.byteLength,
4409
4551
  onProgress,
4552
+ ...(signal !== undefined ? { signal } : {}),
4410
4553
  });
4411
4554
  }
4412
- // §5.1: verify the content address before applying; on mismatch the
4413
- // segment is discarded and the cursor/resume token stay unpersisted,
4414
- // so the next pull re-delivers.
4555
+ // §5.4: the descriptor's byteLength caps the body; §5.1: verify the
4556
+ // content address before applying. On either failure the segment is
4557
+ // discarded and the cursor/resume token stay unpersisted, so the next
4558
+ // pull re-delivers.
4559
+ if (bytes.byteLength > frame.byteLength) {
4560
+ throw invalidRequest('segment exceeds its byteLength', true);
4561
+ }
4415
4562
  onProgress(bytes.byteLength);
4416
4563
  const hash = await sha256Hex(bytes);
4417
4564
  if (`sha256:${hash}` !== frame.segmentId) {
@@ -4421,6 +4568,11 @@ export class SyncClient {
4421
4568
  }
4422
4569
  /** Returns whether SUB_END state was persisted (section applied). */
4423
4570
  #finishSection(sub, start, nextCursor, bootstrapState, summary) {
4571
+ // §4.4: SUB_END rewrites a live registration only. An unsubscribe or
4572
+ // eviction during this round's awaits removed it; persisting now would
4573
+ // re-create it. Everything below is synchronous with this check.
4574
+ if (getSubscription(this.#db, sub.id) === undefined)
4575
+ return false;
4424
4576
  if (start.status === 'active') {
4425
4577
  // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
4426
4578
  // §3.3: the effective-scope echo is persisted for the purge contract.
@@ -4494,6 +4646,7 @@ export class SyncClient {
4494
4646
  // (never the requested map), drop doomed outbox commits, stop pulling.
4495
4647
  const table = this.#table(sub.table);
4496
4648
  const lastEffective = sub.effectiveScopes;
4649
+ const owners = this.#scopeOwners(sub.table, sub.id);
4497
4650
  const registered = getWindowUnitBySubId(this.#db, sub.id);
4498
4651
  let failed = false;
4499
4652
  this.#applyBatch((batch) => {
@@ -4503,20 +4656,19 @@ export class SyncClient {
4503
4656
  const scope = [
4504
4657
  JSON.stringify([table.name]),
4505
4658
  ...this.#dropRetainedRows(batch, (name, values) => name === table.name &&
4506
- matchesLocalScopes(table, lastEffective, values)),
4659
+ ownsLocalRow(table, lastEffective, owners, values)),
4507
4660
  ];
4508
- deleteScopedRows(this.#db, table, lastEffective);
4661
+ deleteScopedRows(this.#db, table, lastEffective, owners);
4509
4662
  batch.scopeMap(table, lastEffective);
4510
- const pendingById = new Map(listOutbox(this.#db).map((commit) => [
4511
- commit.clientCommitId,
4512
- commit,
4513
- ]));
4514
- const droppedIds = dropOutboxCommitsInScope(this.#db, table, lastEffective);
4515
- if (droppedIds.length > 0) {
4516
- for (const clientCommitId of droppedIds) {
4517
- const commit = pendingById.get(clientCommitId);
4518
- if (commit === undefined)
4519
- continue;
4663
+ // §3.3: a whole pending commit leaves when one of its upserts
4664
+ // provably lands in the revoked scopes and no other owner covers it.
4665
+ const doomed = listOutbox(this.#db).filter((commit) => commit.operations.some((op) => op.table === table.name &&
4666
+ op.values !== undefined &&
4667
+ ownsLocalRow(table, lastEffective, owners, op.values)));
4668
+ if (doomed.length > 0) {
4669
+ for (const commit of doomed) {
4670
+ const { clientCommitId } = commit;
4671
+ deleteOutboxCommit(this.#db, clientCommitId);
4520
4672
  const results = commit.operations.map((operation, opIndex) => {
4521
4673
  const rejection = {
4522
4674
  clientCommitId,
@@ -4596,8 +4748,10 @@ export class SyncClient {
4596
4748
  }
4597
4749
  return { opIndex, existed: true, syncVersion, values };
4598
4750
  }
4751
+ /** `onlyKeys` holds overlay row keys (`JSON [table,rowId]`). */
4599
4752
  #captureBeforeImages(operations, onlyKeys) {
4600
- return operations.flatMap((operation, opIndex) => onlyKeys && !onlyKeys.has(`${operation.table}\u0000${operation.rowId}`)
4753
+ return operations.flatMap((operation, opIndex) => onlyKeys &&
4754
+ !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
4601
4755
  ? []
4602
4756
  : [this.#captureBeforeImage(operation, opIndex)]);
4603
4757
  }
@@ -4634,11 +4788,11 @@ export class SyncClient {
4634
4788
  const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
4635
4789
  const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
4636
4790
  const complete = commit.operations.every((_, index) => imageByIndex.has(index));
4637
- const affectedKeys = new Set(commit.operations.map((operation) => `${operation.table}\u0000${operation.rowId}`));
4791
+ const affectedKeys = new Set(commit.operations.map((operation) => JSON.stringify([operation.table, operation.rowId])));
4638
4792
  if (complete) {
4639
4793
  const restored = new Set();
4640
4794
  commit.operations.forEach((operation, index) => {
4641
- const key = `${operation.table}\u0000${operation.rowId}`;
4795
+ const key = JSON.stringify([operation.table, operation.rowId]);
4642
4796
  if (restored.has(key))
4643
4797
  return;
4644
4798
  const image = imageByIndex.get(index);
@@ -4655,13 +4809,13 @@ export class SyncClient {
4655
4809
  deleteOutboxCommit(this.#db, commit.clientCommitId);
4656
4810
  if (!complete)
4657
4811
  return;
4658
- for (const later of listOutbox(this.#db)) {
4812
+ for (const later of listOutbox(this.#db, [...affectedKeys])) {
4659
4813
  if (later.seq <= commit.seq)
4660
4814
  continue;
4661
- const affectedOperations = later.operations.filter((operation) => affectedKeys.has(`${operation.table}\u0000${operation.rowId}`));
4815
+ const affectedOperations = later.operations.filter((operation) => affectedKeys.has(JSON.stringify([operation.table, operation.rowId])));
4662
4816
  if (affectedOperations.length === 0)
4663
4817
  continue;
4664
- replaceOutboxBeforeImages(this.#db, later.clientCommitId, this.#captureBeforeImages(later.operations, affectedKeys));
4818
+ replaceOutboxBeforeImages(this.#db, later, this.#captureBeforeImages(later.operations, affectedKeys));
4665
4819
  // §7.4.4: a later commit the recovery already classified refused never
4666
4820
  // replays. Its before-image is still rebased above, so dropping it later
4667
4821
  // restores the same base this rollback just restored.
@@ -4795,26 +4949,30 @@ export class SyncClient {
4795
4949
  type: localColumnType(column),
4796
4950
  }));
4797
4951
  const sparse = [];
4798
- for (const column of table.columns) {
4799
- const raw = values[column.name];
4952
+ for (const { name, type } of declared) {
4953
+ const raw = values[name];
4800
4954
  if (raw === undefined) {
4801
4955
  sparse.push(undefined);
4802
4956
  continue;
4803
4957
  }
4804
- // §7.1: the schema-agnostic outbox form serializes through JSON, which
4805
- // turns NaN and ±Infinity into null. The authoring boundary refuses them
4806
- // instead of recording a different value; the wire `f64` encoding itself
4807
- // stays IEEE-754 binary64 (§2.4).
4808
- if (localColumnType(column) === 'float' &&
4958
+ // §2.4/§7.1: authoring refuses the push admission values the server
4959
+ // rejects. JSON would also turn NaN and ±Infinity into null, so the
4960
+ // outbox never records a different value.
4961
+ if ((type === 'float' &&
4809
4962
  typeof raw === 'number' &&
4810
- !Number.isFinite(raw))
4811
- return `column ${column.name} (float) requires a finite number value`;
4963
+ !Number.isFinite(raw)) ||
4964
+ (type === 'string' && typeof raw === 'string' && raw.includes('\0')))
4965
+ return `column ${name} holds a value push admission rejects`;
4812
4966
  try {
4967
+ if (typeof raw === 'string' && type === 'json')
4968
+ parseJsonDocument(raw, 'json value');
4969
+ if (typeof raw === 'string' && type === 'blob_ref')
4970
+ parseBlobRef(raw);
4813
4971
  sparse.push(jsonToRowValue(raw));
4814
4972
  }
4815
4973
  catch (error) {
4816
- if (error instanceof ClientSyncError)
4817
- return `column ${column.name}: ${error.message}`;
4974
+ if (error instanceof ClientSyncError || error instanceof DecodeError)
4975
+ return `column ${name}: ${error.message}`;
4818
4976
  throw error;
4819
4977
  }
4820
4978
  }
@@ -4870,14 +5028,23 @@ export class SyncClient {
4870
5028
  if (restoreBases)
4871
5029
  restoreFailedBases(this.#db, this.#schema, scope);
4872
5030
  const acknowledged = failedOverlayCommits(this.#db, true, scope, this.#schema);
5031
+ const outbox = new Set(listOutbox(this.#db, scope));
4873
5032
  const pending = [
4874
5033
  ...failedOverlayCommits(this.#db, false, scope, this.#schema),
4875
- ...listOutbox(this.#db, scope),
5034
+ ...outbox,
4876
5035
  ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
4877
- for (const commit of [...acknowledged, ...pending])
5036
+ // §7.2: a caller that restored the bases itself has just written the
5037
+ // server base of every exact-key row in scope. Each pending commit's
5038
+ // before-image of such a row is re-taken right before the commit
5039
+ // replays, so a later rollback restores that base plus earlier intent.
5040
+ const rebased = restoreBases || scope === undefined ? undefined : new Set(scope);
5041
+ for (const commit of [...acknowledged, ...pending]) {
5042
+ if (rebased !== undefined && outbox.has(commit))
5043
+ replaceOutboxBeforeImages(this.#db, commit, this.#captureBeforeImages(commit.operations, rebased));
4878
5044
  this.#applyOperationsLocally(commit.operations.filter((op) => scope === undefined ||
4879
5045
  scope.includes(JSON.stringify([op.table, op.rowId])) ||
4880
5046
  scope.includes(JSON.stringify([op.table]))), batch, true);
5047
+ }
4881
5048
  };
4882
5049
  const priorRejections = [...this.#rejections];
4883
5050
  try {