@syncular/client 0.58.0 → 0.60.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 (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
package/dist/client.js CHANGED
@@ -14,25 +14,24 @@ 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, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, } from '@syncular/core';
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
- 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';
22
+ import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.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
- 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
- import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, saveSubscriptionScopeSchema, resetSubscriptionsForBump, saveSubscription, setMeta, SUBSCRIPTIONS_TABLE, } from './state.js';
35
- import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
32
+ import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
33
+ import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, resetUnits, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
34
+ import { deletePendingEviction, loadPendingEvictions, loadWindowUnits, savePendingEviction, windowBaseKey, windowRefs, WINDOWS_TABLE, windowUnitScopes, } from './window.js';
36
35
  /** Stable client-local error while protected operations are preflight-gated. */
37
36
  export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
38
37
  /**
@@ -85,7 +84,7 @@ function emptySummary(pushed) {
85
84
  };
86
85
  }
87
86
  const LOG_EPOCH_META_KEY = 'logEpoch';
88
- /** §7.7: one `syncUntilIdle` drive's default total deadline. */
87
+ /** §7.8: one `syncUntilIdle` drive's default total deadline. */
89
88
  const SYNC_IDLE_TIMEOUT_MS = 60_000;
90
89
  /** RFC 0005 defaults (D2/A4/D7). */
91
90
  const PREVIOUS_VERSION_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
@@ -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.8: 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;
@@ -147,7 +152,7 @@ export class SyncClient {
147
152
  #securityEpoch = 0;
148
153
  #transportEnabled;
149
154
  #transportEpoch = 0;
150
- #subscriptionEpoch = 0;
155
+ #registrationEpoch = 0;
151
156
  #now;
152
157
  #outcomeRetentionMaxEntries;
153
158
  #retainFailedCommits;
@@ -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 =
@@ -326,7 +348,6 @@ export class SyncClient {
326
348
  // BUSY/BUSY_SNAPSHOT), and one upgraded before the read refuses with
327
349
  // `client.schema_downgrade`. The batch emits its change event only after
328
350
  // the commit. The onUpgrading callback still reports reset intent.
329
- let subscriptions;
330
351
  try {
331
352
  this.#applyBatch(() => {
332
353
  // §7.4.1/§7.4.2: this is the transaction's first read, so it pins the
@@ -420,7 +441,7 @@ export class SyncClient {
420
441
  this.#reconcilePreviousVersionAtBoot();
421
442
  // A registration remains app intent only while its table exists in the
422
443
  // running schema. Removed-table registrations would poison every pull.
423
- subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema);
444
+ pruneUnknownUnits(this.#db, this.#schema);
424
445
  });
425
446
  }
426
447
  catch (error) {
@@ -439,7 +460,7 @@ export class SyncClient {
439
460
  (countOutbox(this.#db) > 0 ||
440
461
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
441
462
  loadPendingEvictions(this.#db).length > 0 ||
442
- subscriptions.some((sub) => sub.status === 'active'));
463
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
443
464
  if (startupWork && this.#securityLifecycle === 'active') {
444
465
  this.#needsPull = true;
445
466
  this.#emitSyncNeeded('startup');
@@ -452,7 +473,7 @@ export class SyncClient {
452
473
  clientId: () => this.#clientId,
453
474
  role: () => 'direct',
454
475
  outbox: async () => this.pendingCommits().length,
455
- subscriptions: async () => this.subscriptions(),
476
+ units: async () => this.units(),
456
477
  conflicts: async () => this.conflicts().length,
457
478
  rejections: async () => this.rejections().length,
458
479
  syncNeeded: async () => this.statusSnapshot().syncNeeded,
@@ -476,7 +497,7 @@ export class SyncClient {
476
497
  ensureLocalSyncedSchema(this.#db, this.#schema);
477
498
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
478
499
  setLocalSchemaDescriptor(this.#db, this.#schema);
479
- saveSubscriptionScopeSchema(this.#db, this.#schema);
500
+ saveUnitScopeSchema(this.#db, this.#schema);
480
501
  });
481
502
  return;
482
503
  }
@@ -487,7 +508,7 @@ export class SyncClient {
487
508
  this.#db.transaction(() => {
488
509
  ensureLocalSyncedSchema(this.#db, this.#schema);
489
510
  setLocalSchemaDescriptor(this.#db, this.#schema);
490
- saveSubscriptionScopeSchema(this.#db, this.#schema);
511
+ saveUnitScopeSchema(this.#db, this.#schema);
491
512
  });
492
513
  return;
493
514
  }
@@ -515,14 +536,14 @@ export class SyncClient {
515
536
  if (this.#previousVersion !== undefined) {
516
537
  writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
517
538
  }
518
- pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema, true);
539
+ pruneUnknownUnits(this.#db, this.#schema, true);
519
540
  this.#discardAcknowledgedRows();
520
541
  dropAndRecreateSyncedTables(this.#db, this.#schema);
521
- resetSubscriptionsForBump(this.#db);
542
+ resetUnits(this.#db);
522
543
  this.#replayOutbox();
523
544
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
524
545
  setLocalSchemaDescriptor(this.#db, this.#schema);
525
- saveSubscriptionScopeSchema(this.#db, this.#schema);
546
+ saveUnitScopeSchema(this.#db, this.#schema);
526
547
  });
527
548
  // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
528
549
  for (const table of this.#schema.tables.values())
@@ -597,7 +618,7 @@ export class SyncClient {
597
618
  this.#emitSyncIntent({ kind: 'interactive' });
598
619
  return [];
599
620
  }
600
- const subscriptions = loadSubscriptions(this.#db);
621
+ const units = loadUnits(this.#db);
601
622
  this.#setUpgrading(true);
602
623
  // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
603
624
  // orphan sweep but captures no new shadow.
@@ -607,7 +628,7 @@ export class SyncClient {
607
628
  this.#db.transaction(() => {
608
629
  this.#discardAcknowledgedRows();
609
630
  dropAndRecreateSyncedTables(this.#db, this.#schema);
610
- resetSubscriptionsForBump(this.#db);
631
+ resetUnits(this.#db);
611
632
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
612
633
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
613
634
  // transaction before they replay, so the reset boundary never fails on
@@ -630,7 +651,7 @@ export class SyncClient {
630
651
  this.#setSyncNeeded(true);
631
652
  this.#emitSyncNeeded('startup');
632
653
  this.#emitSyncIntent({ kind: 'interactive' });
633
- return subscriptions.map((subscription) => subscription.id);
654
+ return units.map((unit) => unit.id);
634
655
  }
635
656
  #setUpgrading(upgrading) {
636
657
  if (this.#upgrading === upgrading)
@@ -716,6 +737,7 @@ export class SyncClient {
716
737
  return;
717
738
  this.#transportEnabled = enabled;
718
739
  this.#transportEpoch += 1;
740
+ this.#disarm();
719
741
  if (!enabled && !this.#syncOutstanding)
720
742
  this.disconnectRealtime();
721
743
  this.#emitSyncIntent(enabled && this.#securityLifecycle === 'active'
@@ -776,7 +798,7 @@ export class SyncClient {
776
798
  (countOutbox(this.#db) > 0 ||
777
799
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
778
800
  loadPendingEvictions(this.#db).length > 0 ||
779
- loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
801
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
780
802
  if (startupWork) {
781
803
  this.#setSyncNeeded(true);
782
804
  this.#emitSyncNeeded('startup');
@@ -809,8 +831,8 @@ export class SyncClient {
809
831
  return this.#db;
810
832
  }
811
833
  /**
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
834
+ * The raw-SQL read tier. Guarded (query-guard.ts): a single statement
835
+ * SQLite reports read-only — writes must go through `mutate()` so they hit the
814
836
  * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
815
837
  * result, so a `SELECT *` row is safe to feed back into `mutate()`
816
838
  * values; alias explicitly (`_sync_version AS v`) to read one. Engine
@@ -818,11 +840,10 @@ export class SyncClient {
818
840
  */
819
841
  query(sql, params) {
820
842
  this.#requireActive();
821
- assertReadOnlyQuery(sql);
822
843
  // RFC 0005's container lives in a separate database file, so this
823
844
  // connection cannot see it and there is no table-access guard to run.
824
845
  try {
825
- return stripSyncColumns(this.#db.query(sql, params));
846
+ return stripSyncColumns(this.#db.queryReadOnly(sql, params));
826
847
  }
827
848
  catch (error) {
828
849
  throw classifySqliteFailure(error).error;
@@ -864,10 +885,9 @@ export class SyncClient {
864
885
  snapshotRead(spec) {
865
886
  return this.#readSnapshot(spec);
866
887
  }
867
- /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
868
- subscriptionCatchup(id) {
869
- return this.#readSnapshot({ statements: [], subscriptions: [id] })
870
- .subscriptions[0];
888
+ /** §7.5: one unit's persisted catch-up state (never the owner cache). */
889
+ unitCatchup(id) {
890
+ return this.#readSnapshot({ statements: [], units: [id] }).units[0];
871
891
  }
872
892
  /** §7.5: one client commit's delivery status: pending, its retained outcome,
873
893
  * or an explicit unknown (never held, or pruned by retention). */
@@ -877,7 +897,7 @@ export class SyncClient {
877
897
  }
878
898
  /**
879
899
  * §7.5: the one atomic read primitive. Every public read (`querySnapshot`,
880
- * `snapshotRead`, `subscriptionCatchup`, `commitDelivery`) enters here, so
900
+ * `snapshotRead`, `unitCatchup`, `commitDelivery`) enters here, so
881
901
  * the read-only guard, transaction, revision, coverage, catch-up, delivery,
882
902
  * and owner-failure observation exist once.
883
903
  */
@@ -885,60 +905,25 @@ export class SyncClient {
885
905
  this.#requireActive();
886
906
  const owner = request.owner;
887
907
  const catchupOf = (id) => {
888
- function corrupt() {
889
- throw new ClientSyncError('sync.local_corrupt', 'persisted subscription state is invalid');
890
- }
891
- const row = this.#db.query(`SELECT tbl,status,cursor,bootstrap_state,effective_scopes,reason_code FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id])[0];
892
- if (row === undefined)
908
+ const unit = getUnit(this.#db, id);
909
+ if (unit === undefined)
893
910
  return { state: 'unknown', id };
894
- const table = row.tbl;
895
- const status = row.status;
896
- const cursor = row.cursor;
897
- if (typeof table !== 'string' ||
898
- (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
899
- typeof cursor !== 'number' ||
900
- !Number.isSafeInteger(cursor)) {
901
- corrupt();
902
- }
903
- const token = row.bootstrap_state;
904
- if (token !== null && typeof token !== 'string')
905
- corrupt();
906
- const rawScopes = row.effective_scopes;
907
- let effectiveScopes;
908
- if (rawScopes !== null) {
909
- if (typeof rawScopes !== 'string')
910
- corrupt();
911
- try {
912
- effectiveScopes = JSON.parse(rawScopes);
913
- if (effectiveScopes === null)
914
- effectiveScopes = undefined;
915
- else if (typeof effectiveScopes !== 'object' ||
916
- Array.isArray(effectiveScopes) ||
917
- !Object.values(effectiveScopes).every((values) => Array.isArray(values) &&
918
- values.every((value) => typeof value === 'string')))
919
- corrupt();
920
- }
921
- catch {
922
- corrupt();
923
- }
924
- }
925
- const reasonCode = row.reason_code;
926
- if (reasonCode !== null && typeof reasonCode !== 'string')
927
- corrupt();
928
- const active = status === 'active';
929
- const hasResumeToken = token !== null;
930
- return {
911
+ const cursor = unit.cursor ?? replicaCursor(this.#db);
912
+ if (!Number.isSafeInteger(cursor))
913
+ throw new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
914
+ const active = unit.status === 'active';
915
+ const pending = bootstrapping(unit);
916
+ return definedObject({
931
917
  state: 'known',
932
918
  id,
933
- table,
934
- status,
919
+ status: unit.status,
920
+ live: unit.cursor === undefined,
935
921
  cursor,
936
- hasResumeToken,
937
- bootstrapComplete: active && cursor >= 0 && !hasResumeToken,
938
- knownPendingPages: active && (hasResumeToken || cursor < 0),
939
- ...(effectiveScopes !== undefined ? { effectiveScopes } : {}),
940
- ...(reasonCode !== null ? { reasonCode } : {}),
941
- };
922
+ hasResumeToken: unit.bootstrapState !== undefined,
923
+ bootstrapComplete: active && !pending,
924
+ knownPendingPages: active && pending,
925
+ reasonCode: unit.reasonCode,
926
+ });
942
927
  };
943
928
  const deliveryOf = (id) => {
944
929
  const pending = this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [id]).length > 0;
@@ -951,12 +936,9 @@ export class SyncClient {
951
936
  };
952
937
  let read;
953
938
  try {
954
- for (const statement of request.statements) {
955
- assertReadOnlyQuery(statement.sql);
956
- }
957
939
  read = this.#db.transaction(() => {
958
940
  const revision = getLocalRevision(this.#db);
959
- const queries = request.statements.map((statement) => stripSyncColumns(this.#db.query(statement.sql, statement.params)));
941
+ const queries = request.statements.map((statement) => stripSyncColumns(this.#db.queryReadOnly(statement.sql, statement.params)));
960
942
  const pending = [];
961
943
  const missing = [];
962
944
  for (const requested of request.coverage ?? []) {
@@ -978,7 +960,7 @@ export class SyncClient {
978
960
  pending,
979
961
  missing,
980
962
  },
981
- subscriptions: (request.subscriptions ?? []).map(catchupOf),
963
+ units: (request.units ?? []).map(catchupOf),
982
964
  deliveries: (request.commitIds ?? []).map(deliveryOf),
983
965
  };
984
966
  });
@@ -1039,7 +1021,7 @@ export class SyncClient {
1039
1021
  this.#discardPreviousVersion();
1040
1022
  return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1041
1023
  }
1042
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1024
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1043
1025
  this.#discardPreviousVersion();
1044
1026
  return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1045
1027
  }
@@ -1129,16 +1111,13 @@ export class SyncClient {
1129
1111
  return lease?.expiresAtMs !== undefined && lease.expiresAtMs <= nowMs;
1130
1112
  }
1131
1113
  /**
1132
- * RFC 0005 D7: the §7.4.5 replacement-coverage predicate — every active
1133
- * subscription has `cursor >= 0` and no resume token. Window units own
1134
- * subscriptions, so their pendency is included. An empty active set is not
1135
- * completion.
1114
+ * RFC 0005 D7: the §7.4.5 replacement-coverage predicate: no active unit
1115
+ * is bootstrapping. Window units are units, so their pendency is included.
1116
+ * An empty active set is not completion.
1136
1117
  */
1137
1118
  #previousVersionCoverageComplete() {
1138
- const active = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
1139
- if (active.length === 0)
1140
- return false;
1141
- return active.every((sub) => sub.cursor >= 0 && sub.bootstrapState === undefined);
1119
+ const active = loadUnits(this.#db).filter((unit) => unit.status === 'active');
1120
+ return active.length > 0 && !active.some(bootstrapping);
1142
1121
  }
1143
1122
  /**
1144
1123
  * Remove the container file and both metadata records. Returns whether
@@ -1173,7 +1152,7 @@ export class SyncClient {
1173
1152
  const record = this.#readPreviousVersionRecord();
1174
1153
  if (record === undefined)
1175
1154
  return;
1176
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1155
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1177
1156
  this.#discardPreviousVersion();
1178
1157
  return;
1179
1158
  }
@@ -1253,89 +1232,38 @@ export class SyncClient {
1253
1232
  * One atomic support/product-health view. It never returns scope values,
1254
1233
  * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
1255
1234
  */
1256
- diagnosticsSnapshot(request = {}) {
1235
+ diagnosticsSnapshot() {
1257
1236
  this.#requireActive();
1258
- const expected = request.expectedSubscriptions ?? [];
1259
- if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
1260
- throw invalidRequest(`diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
1261
- }
1262
- const registered = loadSubscriptions(this.#db);
1263
- const subscriptions = new Map();
1264
- for (const sub of registered) {
1265
- const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
1266
- const complete = sub.status === 'active' &&
1267
- sub.cursor >= 0 &&
1268
- sub.bootstrapState === undefined;
1269
- subscriptions.set(sub.id, {
1270
- id: sub.id,
1271
- table: sub.table,
1272
- state: sub.status === 'revoked'
1273
- ? 'revoked'
1274
- : sub.status === 'failed'
1275
- ? 'failed'
1276
- : reset
1277
- ? 'reset'
1278
- : complete
1279
- ? 'complete'
1280
- : 'bootstrapping',
1281
- complete,
1282
- cursor: sub.cursor,
1283
- ...(sub.reasonCode !== undefined
1284
- ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
1285
- : {}),
1286
- });
1287
- }
1288
- for (const item of expected) {
1289
- if (typeof item.id !== 'string' ||
1290
- item.id.length === 0 ||
1291
- typeof item.table !== 'string' ||
1292
- item.table.length === 0) {
1293
- throw invalidRequest('diagnosticsSnapshot needs subscription id and table');
1294
- }
1295
- const registeredSubscription = subscriptions.get(item.id);
1296
- if (registeredSubscription !== undefined &&
1297
- registeredSubscription.table !== item.table) {
1298
- subscriptions.set(item.id, {
1299
- id: item.id,
1300
- table: item.table,
1301
- state: 'failed',
1302
- complete: false,
1303
- reasonCode: 'client.subscription_intent_mismatch',
1304
- });
1305
- }
1306
- else if (registeredSubscription === undefined) {
1307
- subscriptions.set(item.id, {
1308
- id: item.id,
1309
- table: item.table,
1310
- state: 'unregistered',
1311
- complete: false,
1312
- });
1313
- }
1237
+ const registered = loadUnits(this.#db);
1238
+ const units = {
1239
+ bootstrapping: 0,
1240
+ complete: 0,
1241
+ reset: 0,
1242
+ revoked: 0,
1243
+ failed: 0,
1244
+ };
1245
+ for (const unit of registered) {
1246
+ units[unit.status !== 'active'
1247
+ ? unit.status
1248
+ : !bootstrapping(unit)
1249
+ ? 'complete'
1250
+ : unit.reasonCode === 'sync.cursor_expired'
1251
+ ? 'reset'
1252
+ : 'bootstrapping'] += 1;
1314
1253
  }
1315
1254
  const capturedAtMs = this.#now();
1316
1255
  const leaseState = this.#diagnosticLease(capturedAtMs);
1256
+ const round = this.#lastRound;
1317
1257
  const connectivity = !this.#transportEnabled
1318
1258
  ? 'offline'
1319
- : this.#lastRound?.status === 'succeeded'
1259
+ : round?.status === 'succeeded'
1320
1260
  ? 'online'
1321
- : this.#lastRound?.status === 'failed' &&
1322
- (this.#lastRound.causeKind === 'network' ||
1323
- this.#lastRound.causeKind === 'connect')
1261
+ : round?.status === 'failed' &&
1262
+ (round.causeKind === 'network' || round.causeKind === 'connect')
1324
1263
  ? 'offline'
1325
- : this.#lastRound?.status === 'failed' &&
1326
- this.#lastRound.httpStatus !== undefined
1264
+ : round?.status === 'failed' && round.httpStatus !== undefined
1327
1265
  ? 'online'
1328
1266
  : 'unknown';
1329
- const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
1330
- const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
1331
- const aExpected = expectedOrder.get(a.id);
1332
- const bExpected = expectedOrder.get(b.id);
1333
- if (aExpected !== undefined || bExpected !== undefined) {
1334
- return ((aExpected ?? Number.MAX_SAFE_INTEGER) -
1335
- (bExpected ?? Number.MAX_SAFE_INTEGER));
1336
- }
1337
- return a.id.localeCompare(b.id);
1338
- });
1339
1267
  return definedObject({
1340
1268
  version: CLIENT_DIAGNOSTICS_VERSION,
1341
1269
  capturedAtMs,
@@ -1361,8 +1289,16 @@ export class SyncClient {
1361
1289
  pendingOutbox: countOutbox(this.#db),
1362
1290
  },
1363
1291
  lease: leaseState,
1364
- subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
1365
- subscriptionsTruncated: allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
1292
+ units: {
1293
+ ...units,
1294
+ reasonCodes: [
1295
+ ...new Set(registered.flatMap((unit) => unit.reasonCode === undefined
1296
+ ? []
1297
+ : [this.#diagnosticCode(unit.reasonCode)])),
1298
+ ].sort(),
1299
+ },
1300
+ activeUnits: registered.filter((unit) => unit.status === 'active').length,
1301
+ replicaCursor: replicaCursor(this.#db),
1366
1302
  lastRound: this.#lastRound,
1367
1303
  lastChange: this.#lastChange,
1368
1304
  storage: this.#diagnosticStorage(),
@@ -1389,8 +1325,9 @@ export class SyncClient {
1389
1325
  try {
1390
1326
  const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
1391
1327
  const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
1392
- const outboxBytes = Number(this.#db.query(`SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`)[0]?.bytes ?? 0);
1393
- const outcome = this.#db.query(`SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM ${OUTCOMES_TABLE}`)[0];
1328
+ // One statement for the outbox and outcome-journal sums keeps the
1329
+ // snapshot at its pre-version-4 statement count.
1330
+ 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];
1394
1331
  const blobBytes = this.#hasBlobs
1395
1332
  ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
1396
1333
  : 0;
@@ -1399,9 +1336,9 @@ export class SyncClient {
1399
1336
  return {
1400
1337
  status: pressure ? 'pressure' : 'healthy',
1401
1338
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
1402
- pendingOutboxBytesApprox: Math.max(0, outboxBytes),
1403
- retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
1404
- retainedOutcomeEntries: Math.max(0, Number(outcome?.entries ?? 0)),
1339
+ pendingOutboxBytesApprox: Math.max(0, Number(sums?.outbox ?? 0)),
1340
+ retainedOutcomeBytesApprox: Math.max(0, Number(sums?.bytes ?? 0)),
1341
+ retainedOutcomeEntries: Math.max(0, Number(sums?.entries ?? 0)),
1405
1342
  blobCacheBytesApprox: Math.max(0, blobBytes),
1406
1343
  ...(pressure
1407
1344
  ? { pressureReasonCode: 'client.blob_cache_over_limit' }
@@ -1494,7 +1431,9 @@ export class SyncClient {
1494
1431
  if (revision !== undefined) {
1495
1432
  const event = batch.finish(revision, status);
1496
1433
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
1497
- const windows = [...new Set(event.windows.map((entry) => entry.table))];
1434
+ const windows = [
1435
+ ...new Set(event.windows.map((entry) => entry.baseKey.split('\0')[0])),
1436
+ ];
1498
1437
  this.#lastChange = {
1499
1438
  revision: revision.toString(),
1500
1439
  recordedAtMs: this.#now(),
@@ -1556,7 +1495,7 @@ export class SyncClient {
1556
1495
  }
1557
1496
  async #uploadBlob(bytes, options) {
1558
1497
  if (this.#config.blobs === undefined) {
1559
- throw invalidRequest('uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
1498
+ throw invalidRequest('uploadBlob requires a blob transport');
1560
1499
  }
1561
1500
  const blobId = await computeBlobId(bytes);
1562
1501
  const nowMs = this.#now();
@@ -1586,43 +1525,48 @@ export class SyncClient {
1586
1525
  return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
1587
1526
  }
1588
1527
  async #fetchBlob(blobIdOrRef) {
1589
- const blobId = blobIdOrRef.startsWith('sha256:')
1590
- ? blobIdOrRef
1591
- : parseBlobRef(blobIdOrRef).blobId;
1528
+ // A BlobRef declares the size that caps the download (§5.9.5); a bare
1529
+ // blobId declares none.
1530
+ const ref = blobIdOrRef.startsWith('sha256:')
1531
+ ? undefined
1532
+ : parseBlobRef(blobIdOrRef);
1533
+ const blobId = ref?.blobId ?? blobIdOrRef;
1592
1534
  const cached = getCachedBlob(this.#db, blobId);
1593
1535
  if (cached !== undefined)
1594
1536
  return cached;
1595
1537
  const transport = this.#config.blobs;
1596
1538
  if (transport === undefined) {
1597
- throw invalidRequest('fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
1539
+ throw invalidRequest('fetchBlob requires a blob transport');
1598
1540
  }
1599
1541
  // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
1600
1542
  // presign configured) a signed url the client fetches directly. On a url
1601
1543
  // arm the client MUST NOT attach host auth and MUST NOT fall through:
1602
1544
  // failure => re-request, the caller's next fetchBlob mints a fresh url.
1603
1545
  this.#requireTransport();
1604
- const response = await transport.download(blobId);
1546
+ const response = await transport.download(blobId, ref?.byteLength);
1605
1547
  let bytes;
1606
1548
  if (response.kind === 'url') {
1607
1549
  if (transport.fetchUrl === undefined) {
1608
- throw invalidRequest('blob download returned a url but the transport cannot fetch urls (§5.9.5)');
1550
+ throw invalidRequest('blob transport cannot fetch urls');
1609
1551
  }
1610
1552
  if (response.urlExpiresAtMs !== undefined &&
1611
1553
  response.urlExpiresAtMs <= this.#now()) {
1612
1554
  // §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);
1555
+ throw new ClientSyncError('sync.segment_expired', 'blob url expired before fetch', true);
1614
1556
  }
1615
- bytes = await transport.fetchUrl(response.url);
1557
+ bytes = await transport.fetchUrl(response.url, ref?.byteLength);
1616
1558
  }
1617
1559
  else {
1618
1560
  bytes = response.bytes;
1619
1561
  }
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)`);
1562
+ // §5.9.5 inherits §5.1: the declared size caps the body and the content
1563
+ // address must match. On the url path either failure invalidates the
1564
+ // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
1565
+ if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
1566
+ throw invalidRequest('blob exceeds its byteLength');
1567
+ }
1568
+ if ((await computeBlobId(bytes)) !== blobId) {
1569
+ throw invalidRequest('blob content address mismatch');
1626
1570
  }
1627
1571
  putCachedBlob(this.#db, blobId, bytes, this.#now());
1628
1572
  this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
@@ -1640,15 +1584,23 @@ export class SyncClient {
1640
1584
  return;
1641
1585
  enforceBlobCacheCap(this.#db, this.#schema, cap);
1642
1586
  }
1643
- /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
1587
+ /**
1588
+ * Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. It
1589
+ * runs on the round's operation chain because a refused upload drops
1590
+ * outbox commits a round may have captured.
1591
+ */
1644
1592
  flushBlobUploads() {
1645
1593
  this.#requireTransport();
1646
- return this.#runProtectedAsync(() => this.#flushBlobUploads());
1594
+ return this.#runProtectedAsync(async () => {
1595
+ await this.#serialize(() => this.#flushBlobUploads(undefined));
1596
+ });
1647
1597
  }
1648
- async #flushBlobUploads() {
1598
+ /** Returns the ids of the commits a refused upload dropped (§5.9.7). */
1599
+ async #flushBlobUploads(signal) {
1600
+ const refused = new Set();
1649
1601
  const transport = this.#config.blobs;
1650
1602
  if (transport === undefined || !this.#hasBlobs)
1651
- return;
1603
+ return refused;
1652
1604
  for (const pending of listPendingUploads(this.#db)) {
1653
1605
  const cached = getCachedBlob(this.#db, pending.blobId);
1654
1606
  if (cached === undefined ||
@@ -1658,9 +1610,36 @@ export class SyncClient {
1658
1610
  (await computeBlobId(cached.bytes)) !== pending.blobId) {
1659
1611
  throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload body is missing or corrupt');
1660
1612
  }
1661
- await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType);
1613
+ try {
1614
+ await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType, signal);
1615
+ }
1616
+ catch (error) {
1617
+ // §5.9.7: a non-retryable server refusal is this body's final
1618
+ // outcome. Retryable refusals and transport failures fail the round.
1619
+ // A failure without a server code (`sync.transport_failed`: no
1620
+ // response, or a response without a JSON error body) is not one.
1621
+ if (!(error instanceof Error) ||
1622
+ !('code' in error) ||
1623
+ typeof error.code !== 'string' ||
1624
+ error.code === 'sync.transport_failed' ||
1625
+ !('retryable' in error) ||
1626
+ error.retryable !== false)
1627
+ throw error;
1628
+ clearPendingUpload(this.#db, pending.blobId);
1629
+ const referencing = new Set(this.#db
1630
+ .query(`SELECT commit_id FROM ${BLOB_COMMIT_REFS} WHERE blob_id=?`, [pending.blobId])
1631
+ .map((row) => row.commit_id));
1632
+ for (const commit of listOutbox(this.#db)) {
1633
+ if (!referencing.has(commit.clientCommitId))
1634
+ continue;
1635
+ this.#dropIncompatibleCommit(commit, error.message, error.code);
1636
+ refused.add(commit.clientCommitId);
1637
+ }
1638
+ continue;
1639
+ }
1662
1640
  clearPendingUpload(this.#db, pending.blobId);
1663
1641
  }
1642
+ return refused;
1664
1643
  }
1665
1644
  /**
1666
1645
  * §5.9.3: upload one blob, preferring the presigned direct-to-storage grant
@@ -1670,17 +1649,17 @@ export class SyncClient {
1670
1649
  * *different, host-authenticated capability*, not a fall-through of the
1671
1650
  * grant's authority (the direct endpoint was always the other path, B4).
1672
1651
  */
1673
- async #uploadOne(transport, blobId, bytes, mediaType) {
1652
+ async #uploadOne(transport, blobId, bytes, mediaType, signal) {
1674
1653
  if (transport.uploadGrant !== undefined &&
1675
1654
  transport.uploadToUrl !== undefined) {
1676
- const grant = await transport.uploadGrant(blobId, bytes.length, mediaType);
1655
+ const grant = await transport.uploadGrant(blobId, bytes.length, mediaType, signal);
1677
1656
  if (grant.kind === 'present')
1678
1657
  return; // idempotent §5.9.3 — no PUT needed
1679
1658
  if (grant.kind === 'url') {
1680
1659
  if (grant.urlExpiresAtMs === undefined ||
1681
1660
  grant.urlExpiresAtMs > this.#now()) {
1682
1661
  try {
1683
- await transport.uploadToUrl(grant.url, bytes, mediaType);
1662
+ await transport.uploadToUrl(blobId, grant.url, bytes, mediaType, signal);
1684
1663
  return;
1685
1664
  }
1686
1665
  catch {
@@ -1691,7 +1670,7 @@ export class SyncClient {
1691
1670
  // grant.kind === 'none' (no presign store) or a failed/expired grant:
1692
1671
  // stream through the direct host-authenticated endpoint.
1693
1672
  }
1694
- await transport.upload(blobId, bytes, mediaType);
1673
+ await transport.upload(blobId, bytes, mediaType, signal);
1695
1674
  }
1696
1675
  conflicts() {
1697
1676
  this.#requireActive();
@@ -1709,9 +1688,7 @@ export class SyncClient {
1709
1688
  /** Prove all retained bases against a completed post-rejection pull (§7.2.1). */
1710
1689
  async proveCurrentBase(outcome, maxRounds) {
1711
1690
  this.#requireActive();
1712
- if (maxRounds !== undefined &&
1713
- (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
1714
- throw invalidRequest('maxRounds must be a positive integer');
1691
+ requireRoundBudget(maxRounds);
1715
1692
  const { clientCommitId, sequence } = outcome;
1716
1693
  const provable = (candidate) => candidate !== undefined &&
1717
1694
  candidate.sequence === sequence &&
@@ -1736,11 +1713,11 @@ export class SyncClient {
1736
1713
  if (!this.#transportEnabled)
1737
1714
  return { proven: false, reason: 'offline' };
1738
1715
  const epoch = this.#transportEpoch;
1739
- const subscriptionEpoch = this.#subscriptionEpoch;
1716
+ const registrationEpoch = this.#registrationEpoch;
1740
1717
  const securityEpoch = this.#securityEpoch;
1741
1718
  let before;
1742
1719
  try {
1743
- before = loadSubscriptions(this.#db);
1720
+ before = loadUnits(this.#db);
1744
1721
  }
1745
1722
  catch {
1746
1723
  return { proven: false, reason: 'snapshot_failed' };
@@ -1754,14 +1731,14 @@ export class SyncClient {
1754
1731
  proven: false,
1755
1732
  reason: !this.#transportEnabled || epoch !== this.#transportEpoch
1756
1733
  ? 'offline'
1757
- : subscriptionEpoch !== this.#subscriptionEpoch
1734
+ : registrationEpoch !== this.#registrationEpoch
1758
1735
  ? 'missing_coverage'
1759
1736
  : 'sync_failed',
1760
1737
  };
1761
1738
  }
1762
1739
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
1763
1740
  return { proven: false, reason: 'offline' };
1764
- if (subscriptionEpoch !== this.#subscriptionEpoch)
1741
+ if (registrationEpoch !== this.#registrationEpoch)
1765
1742
  return { proven: false, reason: 'missing_coverage' };
1766
1743
  if (this.#securityLifecycle !== 'active' ||
1767
1744
  securityEpoch !== this.#securityEpoch)
@@ -1774,7 +1751,7 @@ export class SyncClient {
1774
1751
  return this.#db.transaction(() => {
1775
1752
  const snapshot = this.#readSnapshot({
1776
1753
  statements: [],
1777
- subscriptions: before.map((sub) => sub.id),
1754
+ units: before.map((unit) => unit.id),
1778
1755
  commitIds: [clientCommitId],
1779
1756
  });
1780
1757
  const delivery = snapshot.deliveries[0];
@@ -1784,21 +1761,15 @@ export class SyncClient {
1784
1761
  proven: false,
1785
1762
  reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
1786
1763
  };
1787
- const after = new Map(loadSubscriptions(this.#db).map((sub) => [sub.id, sub]));
1788
- const states = new Map(snapshot.subscriptions.map((sub) => [sub.id, sub]));
1764
+ const after = new Map(loadUnits(this.#db).map((unit) => [unit.id, unit]));
1765
+ const complete = new Set(snapshot.units.flatMap((state) => state.state === 'known' && state.bootstrapComplete
1766
+ ? [state.id]
1767
+ : []));
1768
+ // A unit id names one scope map (§4.1), so the same id before and
1769
+ // after the drive is the same registration.
1789
1770
  const candidates = before.flatMap((previous) => {
1790
- const sub = after.get(previous.id);
1791
- const state = states.get(previous.id);
1792
- return sub !== undefined &&
1793
- sub.table === previous.table &&
1794
- sub.params === previous.params &&
1795
- canonicalScopeJson(sub.scopes) ===
1796
- canonicalScopeJson(previous.scopes) &&
1797
- sub.effectiveScopes !== undefined &&
1798
- state?.state === 'known' &&
1799
- state.bootstrapComplete
1800
- ? [{ table: sub.table, scopes: sub.effectiveScopes }]
1801
- : [];
1771
+ const unit = after.get(previous.id);
1772
+ return unit !== undefined && complete.has(unit.id) ? [unit] : [];
1802
1773
  });
1803
1774
  const covered = (tableName, row) => {
1804
1775
  const table = this.#schema.tables.get(tableName);
@@ -1808,16 +1779,19 @@ export class SyncClient {
1808
1779
  key,
1809
1780
  rowValueToJson(value),
1810
1781
  ]));
1811
- return candidates.some((candidate) => {
1812
- return (candidate.table === tableName &&
1813
- Object.keys(candidate.scopes).every((variable) => {
1782
+ return candidates.some((unit) => {
1783
+ const scopes = covers(table, unit.scopes)
1784
+ ? pairScopes(unit.scopes, tableName, unit.echo)
1785
+ : undefined;
1786
+ return (scopes !== undefined &&
1787
+ Object.keys(scopes).every((variable) => {
1814
1788
  const column = table.scopeColumnByVariable.get(variable);
1815
1789
  const value = column === undefined ? undefined : row[column];
1816
1790
  return ((typeof value === 'string' && value.length > 0) ||
1817
1791
  typeof value === 'number' ||
1818
1792
  typeof value === 'boolean');
1819
1793
  }) &&
1820
- matchesLocalScopes(table, candidate.scopes, values));
1794
+ matchesLocalScopes(table, scopes, values));
1821
1795
  });
1822
1796
  };
1823
1797
  for (const row of current.retainedRows) {
@@ -1929,9 +1903,11 @@ export class SyncClient {
1929
1903
  return [...this.#presence.keys()];
1930
1904
  }
1931
1905
  /**
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.
1906
+ * §8.6: subscribe to presence changes (join/update/leave on any held key)
1907
+ * and to the server's refusal of this client's own publish (`error`,
1908
+ * §8.6.2). The subscribable twin of the `onPresence` config callback —
1909
+ * React's `usePresence` targets this so many components can watch one
1910
+ * client.
1935
1911
  * Returns an unsubscribe function.
1936
1912
  */
1937
1913
  onPresence(listener) {
@@ -1969,94 +1945,105 @@ export class SyncClient {
1969
1945
  : 0) |
1970
1946
  (urlCapable ? ACCEPT_SIGNED_URLS : 0));
1971
1947
  }
1972
- subscriptions() {
1948
+ /** Every unit in registration order (§4.1), including revoked and failed. */
1949
+ units() {
1973
1950
  this.#requireActive();
1974
- return loadSubscriptions(this.#db);
1951
+ return loadUnits(this.#db);
1975
1952
  }
1976
- subscription(id) {
1953
+ unit(id) {
1977
1954
  this.#requireActive();
1978
- return getSubscription(this.#db, id);
1955
+ return getUnit(this.#db, id);
1979
1956
  }
1980
1957
  pendingCommits() {
1981
1958
  this.#requireActive();
1982
1959
  return listOutbox(this.#db);
1983
1960
  }
1984
- // -- subscriptions ----------------------------------------------------------
1985
- subscribe(input) {
1986
- this.subscribeMany([input]);
1961
+ // -- units (§4.1) -----------------------------------------------------------
1962
+ /** Register one unit (§4.1) and return its id. */
1963
+ subscribe(scopes) {
1964
+ return this.subscribeMany([scopes])[0];
1987
1965
  }
1988
1966
  /**
1989
- * Register several subscriptions in one local transaction: the same rules
1990
- * as `subscribe` for each input, and one commit for all of them (on OPFS a
1991
- * commit costs milliseconds, so a cold start with hundreds of
1992
- * registrations pays it once). An error rolls back every registration of
1993
- * the call.
1967
+ * Register several units in one local transaction and return their ids:
1968
+ * one commit for all of them (on OPFS a commit costs milliseconds, so a
1969
+ * cold start with hundreds of units pays it once). An error rolls back every
1970
+ * registration of the call. Registering an active unit again changes
1971
+ * nothing; a revoked unit re-arms (§3.3).
1994
1972
  */
1995
- subscribeMany(inputs) {
1973
+ subscribeMany(units) {
1996
1974
  this.#requireActive();
1997
1975
  let registered = false;
1998
- this.#db.transaction(() => {
1999
- for (const input of inputs) {
2000
- if (!this.#schema.tables.has(input.table)) {
2001
- throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
2002
- }
2003
- const existing = getSubscription(this.#db, input.id);
2004
- if (existing !== undefined) {
2005
- const sameIntent = existing.table === input.table &&
2006
- canonicalScopeJson(existing.scopes) ===
2007
- canonicalScopeJson(input.scopes) &&
2008
- existing.params === input.params;
2009
- if (!sameIntent) {
2010
- throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
2011
- }
2012
- // §3.3: a revoked registration keeps its id and intent but no
2013
- // progress. Subscribing again with the same intent re-arms it, so
2014
- // the next pull resolves its scopes from scratch. A `failed`
2015
- // registration is a configuration error and stays put.
2016
- if (existing.status !== 'revoked')
2017
- continue;
2018
- }
2019
- saveSubscription(this.#db, definedObject({
2020
- id: input.id,
2021
- table: input.table,
2022
- scopes: input.scopes,
2023
- params: input.params,
2024
- cursor: -1,
2025
- status: 'active',
2026
- }));
2027
- registered = true;
2028
- }
2029
- });
2030
- if (!registered)
2031
- return;
2032
- this.#subscriptionEpoch += 1;
2033
- this.#setSyncNeeded(true);
2034
- this.#emitSyncIntent({ kind: 'interactive' });
2035
- this.#emitDiagnostics();
1976
+ const ids = this.#db.transaction(() => units.map((scopes) => {
1977
+ const { id, changed } = this.#holdUnit(scopes, true);
1978
+ registered ||= changed;
1979
+ return id;
1980
+ }));
1981
+ if (registered) {
1982
+ this.#registrationEpoch += 1;
1983
+ this.#setSyncNeeded(true);
1984
+ this.#emitSyncIntent({ kind: 'interactive' });
1985
+ this.#emitDiagnostics();
1986
+ }
1987
+ return ids;
2036
1988
  }
1989
+ /**
1990
+ * Release the explicit reference to a unit. The unit leaves the
1991
+ * registration list when no window base holds it (§4.1); its rows stay.
1992
+ */
2037
1993
  unsubscribe(id) {
2038
1994
  this.#requireActive();
2039
- if (getSubscription(this.#db, id) === undefined)
1995
+ const unit = getUnit(this.#db, id);
1996
+ if (unit === undefined || !unit.explicit)
1997
+ return;
1998
+ if (windowRefs(this.#db, id).length > 0) {
1999
+ saveUnit(this.#db, { ...unit, explicit: false });
2000
+ return;
2001
+ }
2002
+ deleteUnit(this.#db, id);
2003
+ this.#registrationEpoch += 1;
2004
+ if (unit.status !== 'active')
2040
2005
  return;
2041
- deleteSubscription(this.#db, id);
2042
- this.#subscriptionEpoch += 1;
2043
2006
  this.#setSyncNeeded(true);
2044
2007
  this.#emitSyncIntent({ kind: 'interactive' });
2045
2008
  this.#emitDiagnostics();
2046
2009
  }
2047
- // -- windowed subscriptions (§4.8) ------------------------------------------
2048
2010
  /**
2049
- * Set the live window units for a base (§4.8): a value-sharded family of
2050
- * subscriptions, one per unit. Computes the diff against the registry —
2051
- * added units get fresh subscriptions (image-lane bootstrap on the next
2052
- * sync); removed units are unsubscribed with their first eviction chunk
2053
- * in one local transaction (E1–E4). Idempotent: calling with the same units is a
2054
- * no-op. Re-entry (a unit removed then re-added) cancels any deferred
2055
- * eviction and fresh-bootstraps.
2056
- *
2057
- * The change takes effect on the next `sync()`/socket round — the pull's
2058
- * subscription list (now with the added unit, without the removed one)
2059
- * re-registers realtime at round end (§8.7). No socket cycle needed.
2011
+ * Take one reference on a unit (§4.1): validate the scope map, register
2012
+ * a new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
2013
+ * `changed` reports whether the registration list changed.
2014
+ */
2015
+ #holdUnit(scopes, explicit) {
2016
+ const entries = Object.entries(scopes ?? {});
2017
+ if (entries.length === 0 ||
2018
+ entries.some(([, value]) => typeof value !== 'string' || value === '*') ||
2019
+ ![...this.#schema.tables.values()].some((table) => covers(table, scopes)))
2020
+ throw new ClientSyncError('sync.invalid_subscription', 'a unit names one non-wildcard value per variable and covers a table');
2021
+ const id = unitId(scopes);
2022
+ const existing = getUnit(this.#db, id);
2023
+ if (existing !== undefined && existing.status !== 'revoked') {
2024
+ if (explicit && !existing.explicit)
2025
+ saveUnit(this.#db, { ...existing, explicit });
2026
+ return { id, changed: false };
2027
+ }
2028
+ deletePendingEviction(this.#db, id);
2029
+ saveUnit(this.#db, {
2030
+ id,
2031
+ scopes: Object.fromEntries(entries),
2032
+ explicit: explicit || existing?.explicit === true,
2033
+ status: 'active',
2034
+ cursor: -1,
2035
+ seeded: [],
2036
+ });
2037
+ return { id, changed: true };
2038
+ }
2039
+ // -- windows (§4.8) ---------------------------------------------------------
2040
+ /**
2041
+ * Set the windowed-in values of a base (§4.8): one unit per value. Added
2042
+ * values take a reference on their unit (a new unit bootstraps on the next
2043
+ * sync); removed values release theirs, and a unit no reference holds leaves
2044
+ * the registration list fused with its first eviction chunk (E1–E4).
2045
+ * Idempotent; re-entry cancels a deferred eviction and fresh-bootstraps.
2046
+ * The change reaches the server with the next round's list (§8.7).
2060
2047
  */
2061
2048
  async setWindow(base, units) {
2062
2049
  await this.setWindowCommand(base, units);
@@ -2064,127 +2051,105 @@ export class SyncClient {
2064
2051
  /** Exact core command result consumed by automatic host loops (§7.5). */
2065
2052
  async setWindowCommand(base, units) {
2066
2053
  this.#requireActive();
2067
- const table = this.#table(base.table);
2068
- if (!table.scopeColumnByVariable.has(base.variable)) {
2069
- throw invalidRequest(`${base.table}: unknown scope variable ${base.variable} (§4.8)`);
2070
- }
2071
- // Serialize the whole window edit: it spans an `await deriveSubId` between
2072
- // db transactions, so without the chain a delta apply (or a concurrent
2073
- // setWindow) could interleave its transactions and corrupt the registry.
2074
2054
  let changed = false;
2075
- let widened = false;
2055
+ // Serialize the whole edit: a shrink yields between eviction chunks, so
2056
+ // without the chain a delta apply or another setWindow could interleave.
2076
2057
  await this.#serialize(async () => {
2077
2058
  const baseKey = windowBaseKey(base);
2078
2059
  const wanted = new Set(units);
2079
2060
  const live = loadWindowUnits(this.#db, baseKey);
2080
- const liveByUnit = new Map(live.map((u) => [u.unit, u.subId]));
2081
- // Widen: units wanted but not live → fresh subscription + registry row.
2082
- for (const unit of wanted) {
2083
- if (liveByUnit.has(unit))
2061
+ const held = new Set(live.map((entry) => entry.value));
2062
+ for (const value of wanted) {
2063
+ if (held.has(value))
2084
2064
  continue;
2085
- const subId = await deriveSubId(base, unit);
2086
2065
  this.#applyBatch((batch) => {
2087
- this.#db.transaction(() => {
2088
- // Re-entry cancels any deferred eviction for this sub id.
2089
- deletePendingEviction(this.#db, subId);
2090
- insertWindowUnit(this.#db, baseKey, unit, subId);
2091
- saveSubscription(this.#db, definedObject({
2092
- id: subId,
2093
- table: base.table,
2094
- scopes: unitScopes(base, unit),
2095
- params: base.params,
2096
- cursor: -1,
2097
- status: 'active',
2098
- }));
2099
- });
2100
- this.#needsPull = true;
2101
- batch.window(baseKey, base.table, unit);
2066
+ const { id, changed: registered } = this.#holdUnit(windowUnitScopes(base, value), false);
2067
+ this.#db.exec(`INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`, [baseKey, value, id]);
2068
+ if (registered)
2069
+ this.#needsPull = true;
2070
+ batch.window(baseKey, value);
2102
2071
  batch.status();
2103
2072
  });
2104
2073
  changed = true;
2105
- widened = true;
2106
- this.#subscriptionEpoch += 1;
2074
+ this.#registrationEpoch += 1;
2107
2075
  }
2108
- // Shrink: units live but not wanted → unsubscribe fused with eviction.
2109
- for (const { unit, subId } of live) {
2110
- if (wanted.has(unit))
2076
+ for (const { value, unitId: id } of live) {
2077
+ if (wanted.has(value))
2111
2078
  continue;
2112
- await this.#evictUnit(baseKey, base, unit, subId);
2079
+ await this.#releaseWindowUnit(baseKey, value, id);
2113
2080
  changed = true;
2114
- this.#subscriptionEpoch += 1;
2081
+ this.#registrationEpoch += 1;
2115
2082
  }
2116
2083
  });
2117
2084
  const effects = {
2118
- sync: this.#transportEnabled && (changed || widened)
2085
+ sync: this.#transportEnabled && changed
2119
2086
  ? { kind: 'interactive' }
2120
2087
  : { kind: 'none' },
2121
2088
  };
2122
- if (effects.sync.kind === 'interactive') {
2089
+ if (effects.sync.kind === 'interactive')
2123
2090
  this.#emitSyncIntent(effects.sync);
2124
- }
2125
2091
  return { value: undefined, effects };
2126
2092
  }
2127
2093
  /**
2128
- * The completeness oracle (§4.8 I3): which units of a base are windowed-in
2129
- * locally, which of those are still bootstrap-pending, and thereby the
2130
- * per-unit verdict a live query renders "may be partial" from. A query
2131
- * whose scope footprint includes an un-windowed OR still-pending unit is
2132
- * NOT answerable in full — the host widens or shows partial, never
2133
- * silently-complete. Registration alone is not completeness: a unit is
2134
- * pending until its subscription completes a bootstrap round (cursor
2135
- * advances past -1 with no resume token held).
2094
+ * The completeness oracle (§4.8): which values of a base are windowed-in
2095
+ * and which of those are pending. A value is complete once its unit is
2096
+ * active and no longer bootstrapping; registration alone is not
2097
+ * completeness.
2136
2098
  */
2137
2099
  windowState(base) {
2138
2100
  this.#requireActive();
2139
- const baseKey = windowBaseKey(base);
2140
- const live = loadWindowUnits(this.#db, baseKey);
2141
- const pending = [];
2142
- for (const { unit, subId } of live) {
2143
- const sub = getSubscription(this.#db, subId);
2144
- if (sub === undefined ||
2145
- sub.status !== 'active' ||
2146
- sub.cursor < 0 ||
2147
- sub.bootstrapState !== undefined) {
2148
- pending.push(unit);
2149
- }
2150
- }
2151
- return { units: live.map((u) => u.unit), pending };
2101
+ const live = loadWindowUnits(this.#db, windowBaseKey(base));
2102
+ const pending = live.flatMap(({ value, unitId: id }) => {
2103
+ const unit = getUnit(this.#db, id);
2104
+ return unit === undefined ||
2105
+ unit.status !== 'active' ||
2106
+ bootstrapping(unit)
2107
+ ? [value]
2108
+ : [];
2109
+ });
2110
+ return { units: live.map((entry) => entry.value), pending };
2152
2111
  }
2153
2112
  /**
2154
- * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
2155
- * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
2156
- * pending outbox commit (E1); if any pin remains, records a deferred
2157
- * eviction retried on the next outbox drain. Discards the subscription's
2158
- * cursor/resume/effective-echo (E3) and its version state with the rows
2159
- * (E2). Emits the evicted table's invalidation keys (I1). Fail-closed:
2160
- * with no local scope-column mapping, surfaces a configuration error and
2161
- * evicts nothing (§4.8/§3.3).
2113
+ * §4.8: release a window value's reference. When no reference holds the
2114
+ * unit, unregister it fused with its first eviction chunk (E3): delete the
2115
+ * rows of every covered table matching the persisted echo, except rows
2116
+ * pinned by the outbox (E1) or owned by another unit (§3.3), and park the
2117
+ * per-table scopes of what remains in the pending-eviction registry. Fails
2118
+ * closed without a local scope-column mapping.
2162
2119
  */
2163
- async #evictUnit(baseKey, base, unit, subId) {
2164
- const table = this.#table(base.table);
2165
- const sub = getSubscription(this.#db, subId);
2166
- // The rows a unit holds live under its LAST effective scopes if it ever
2167
- // synced; before first sync, the requested unit scopes are the match.
2168
- const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
2169
- const pinned = this.#pinnedRowIds(base.table);
2120
+ async #releaseWindowUnit(baseKey, value, id) {
2170
2121
  let remaining = false;
2171
2122
  this.#applyBatch((batch) => {
2172
- this.#db.transaction(() => {
2173
- const result = evictScopedRows(this.#db, table, effective, pinned);
2174
- remaining = result.remaining;
2175
- deleteWindowUnit(this.#db, baseKey, unit);
2176
- deleteSubscription(this.#db, subId);
2177
- if (result.deferred) {
2178
- savePendingEviction(this.#db, subId, base.table, effective);
2179
- }
2180
- else {
2181
- deletePendingEviction(this.#db, subId);
2182
- }
2183
- });
2184
- batch.scopeMap(table, effective);
2185
- batch.window(baseKey, table.name, unit);
2186
- this.#needsPull = true;
2123
+ this.#db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
2124
+ baseKey,
2125
+ value,
2126
+ ]);
2127
+ batch.window(baseKey, value);
2187
2128
  batch.status();
2129
+ const unit = getUnit(this.#db, id);
2130
+ if (unit === undefined ||
2131
+ unit.explicit ||
2132
+ windowRefs(this.#db, id).length > 0)
2133
+ return;
2134
+ const units = loadUnits(this.#db);
2135
+ deleteUnit(this.#db, id);
2136
+ this.#needsPull = true;
2137
+ for (const table of this.#schema.tables.values()) {
2138
+ const effective = covers(table, unit.scopes)
2139
+ ? pairScopes(unit.scopes, table.name, unit.echo)
2140
+ : undefined;
2141
+ if (unit.echo === undefined || effective === undefined)
2142
+ continue;
2143
+ const result = evictScopedRows(this.#db, table, effective, unitOwners(units, table, id), this.#pinnedRowIds(table.name));
2144
+ remaining ||= result.remaining;
2145
+ if (result.deferred)
2146
+ savePendingEviction(this.#db, {
2147
+ unitId: id,
2148
+ table: table.name,
2149
+ effective,
2150
+ });
2151
+ batch.scopeMap(table, effective);
2152
+ }
2188
2153
  });
2189
2154
  if (remaining) {
2190
2155
  await yieldToHost();
@@ -2192,32 +2157,28 @@ export class SyncClient {
2192
2157
  }
2193
2158
  }
2194
2159
  /**
2195
- * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
2196
- * unit's rows are removed once no pending commit references them; a unit
2197
- * that re-entered the window in the meantime has no pending record left.
2160
+ * §4.8 E1: continue deferred evictions after the outbox drains or between
2161
+ * chunks. A unit that re-entered the window has no pending entry left.
2198
2162
  */
2199
2163
  async #drainPendingEvictions() {
2200
- const pending = loadPendingEvictions(this.#db);
2201
- if (pending.length === 0)
2202
- return;
2203
- for (const entry of pending) {
2164
+ for (const entry of loadPendingEvictions(this.#db)) {
2204
2165
  const table = this.#schema.tables.get(entry.table);
2205
2166
  if (table === undefined) {
2206
- deletePendingEviction(this.#db, entry.subId);
2167
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
2207
2168
  continue;
2208
2169
  }
2209
2170
  let remaining;
2210
2171
  do {
2211
- if (!loadPendingEvictions(this.#db).some((item) => item.subId === entry.subId))
2172
+ if (!loadPendingEvictions(this.#db).some((item) => item.unitId === entry.unitId && item.table === entry.table))
2212
2173
  break;
2213
- // Local writes may add pins while the worker yields between chunks.
2174
+ // Local writes may add pins while the host yields between chunks.
2214
2175
  const pinned = this.#pinnedRowIds(entry.table);
2215
2176
  remaining = false;
2216
2177
  this.#applyBatch((batch) => {
2217
- const result = evictScopedRows(this.#db, table, entry.effective, pinned);
2178
+ const result = evictScopedRows(this.#db, table, entry.effective, unitOwners(loadUnits(this.#db), table, entry.unitId), pinned);
2218
2179
  remaining = result.remaining;
2219
2180
  if (!result.deferred)
2220
- deletePendingEviction(this.#db, entry.subId);
2181
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
2221
2182
  batch.scopeMap(table, entry.effective);
2222
2183
  });
2223
2184
  if (remaining)
@@ -2257,6 +2218,9 @@ export class SyncClient {
2257
2218
  const operations = mutations.map((mutation) => {
2258
2219
  const table = this.#table(mutation.table);
2259
2220
  if (mutation.op === 'delete') {
2221
+ // §2.4: the server rejects a rowId holding U+0000.
2222
+ if (mutation.rowId.includes('\u0000'))
2223
+ throw invalidRequest('rowId holds U+0000');
2260
2224
  return definedObject({
2261
2225
  table: mutation.table,
2262
2226
  rowId: mutation.rowId,
@@ -2588,7 +2552,7 @@ export class SyncClient {
2588
2552
  throw invalidRequest('local rebootstrap needs a schema-floor update');
2589
2553
  }
2590
2554
  const pending = listOutbox(this.#db);
2591
- const resetSubscriptions = loadSubscriptions(this.#db).length;
2555
+ const resetSubscriptions = loadUnits(this.#db).length;
2592
2556
  const priorUpgrading = this.#upgrading;
2593
2557
  const priorNeedsPull = this.#needsPull;
2594
2558
  try {
@@ -2598,7 +2562,7 @@ export class SyncClient {
2598
2562
  batch.status();
2599
2563
  this.#discardAcknowledgedRows();
2600
2564
  dropAndRecreateSyncedTables(this.#db, this.#schema);
2601
- resetSubscriptionsForBump(this.#db);
2565
+ resetUnits(this.#db);
2602
2566
  for (const table of this.#schema.tables.values()) {
2603
2567
  batch.table(table.name);
2604
2568
  }
@@ -2702,7 +2666,7 @@ export class SyncClient {
2702
2666
  // per-commit delta measured against the canonical encoder.
2703
2667
  const baseBytes = byteCap === undefined
2704
2668
  ? 0
2705
- : encodeMessage({
2669
+ : encodeRequest({
2706
2670
  wireVersion: PROTOCOL_WIRE_VERSION,
2707
2671
  msgKind: 'request',
2708
2672
  frames: [header, pull],
@@ -2775,7 +2739,7 @@ export class SyncClient {
2775
2739
  }
2776
2740
  const frame = byteCap === undefined
2777
2741
  ? 0
2778
- : encodeMessage({
2742
+ : encodeRequest({
2779
2743
  wireVersion: PROTOCOL_WIRE_VERSION,
2780
2744
  msgKind: 'request',
2781
2745
  frames: [header, pushFrame, pull],
@@ -2865,6 +2829,10 @@ export class SyncClient {
2865
2829
  * `setWindow` at an await point.
2866
2830
  */
2867
2831
  sync() {
2832
+ return this.#sync();
2833
+ }
2834
+ /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
2835
+ #sync(signal) {
2868
2836
  this.#requireActive();
2869
2837
  if (this.#syncOutstanding) {
2870
2838
  return Promise.reject(invalidRequest('sync() is already running; coalesce wake-ups'));
@@ -2872,7 +2840,7 @@ export class SyncClient {
2872
2840
  this.#syncOutstanding = true;
2873
2841
  this.#beginDiagnosticsDeferral();
2874
2842
  const startedAtMs = this.#now();
2875
- return this.#serialize(() => this.#runSync())
2843
+ return this.#serialize(() => this.#runSync(signal))
2876
2844
  .then((summary) => {
2877
2845
  const completedAtMs = this.#now();
2878
2846
  this.#lastRound = {
@@ -2978,7 +2946,7 @@ export class SyncClient {
2978
2946
  ? code
2979
2947
  : 'client.unknown_failure';
2980
2948
  }
2981
- async #runSync() {
2949
+ async #runSync(signal) {
2982
2950
  this.#requireTransport();
2983
2951
  this.#roundRetryDelayMs = undefined;
2984
2952
  this.#progress.emit({
@@ -3013,13 +2981,18 @@ export class SyncClient {
3013
2981
  clientId: this.#clientId,
3014
2982
  schemaVersion: this.#schema.version,
3015
2983
  logEpoch: logEpoch,
2984
+ outboxId: getMeta(this.#db, 'outboxId'),
3016
2985
  });
2986
+ // The registration fields are set after encoding (below).
3017
2987
  const pull = {
3018
2988
  type: 'PULL_HEADER',
3019
2989
  limitCommits: limits?.limitCommits ?? 0,
3020
2990
  limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
3021
2991
  maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
3022
2992
  accept: this.#acceptMask(),
2993
+ cursor: -1,
2994
+ registrationDigest: registrationDigest([]),
2995
+ echoDigest: new Uint8Array(),
3023
2996
  };
3024
2997
  const { pushFrames, outbox, frameBytes, deferred: encodedDeferred, } = logEpoch === undefined
3025
2998
  ? { pushFrames: [], outbox: [], frameBytes: [], deferred: 0 }
@@ -3029,13 +3002,28 @@ export class SyncClient {
3029
3002
  if (logEpoch !== undefined &&
3030
3003
  this.#hasBlobs &&
3031
3004
  this.#config.blobs !== undefined) {
3032
- await this.#flushBlobUploads();
3005
+ const refused = await this.#flushBlobUploads(signal);
3006
+ // §5.9.7: a commit whose blob the server refused left the outbox.
3007
+ for (let index = outbox.length - 1; index >= 0; index--) {
3008
+ if (!refused.has(outbox[index].clientCommitId))
3009
+ continue;
3010
+ outbox.splice(index, 1);
3011
+ pushFrames.splice(index, 1);
3012
+ frameBytes.splice(index, 1);
3013
+ }
3033
3014
  }
3034
3015
  // Captured after encoding: a subscribe/unsubscribe during the
3035
3016
  // encryption await must not make the final request exceed the byte
3036
3017
  // budget, and the reset epoch must be the one the response apply checks.
3037
3018
  const resetEpoch = this.#localResetEpoch;
3038
- const subs = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
3019
+ const registered = loadUnits(this.#db).filter((unit) => unit.status === 'active');
3020
+ pull.cursor = replicaCursor(this.#db);
3021
+ pull.registrationDigest = registrationDigest(registered.map((unit) => unit.scopes));
3022
+ pull.echoDigest = hexToBytes(getMeta(this.#db, ECHO_DIGEST_KEY) ?? '');
3023
+ // §4.1: the list travels when it changed since the server stored it,
3024
+ // after `unregistered` and after a reset (both clear the stored digest).
3025
+ const travels = getMeta(this.#db, REGISTERED_DIGEST_KEY) !==
3026
+ bytesToHex(pull.registrationDigest);
3039
3027
  // §1.5: a kept round-failure code rides every request until a round
3040
3028
  // completes, immediately after REQ_HEADER.
3041
3029
  const report = this.#roundFailureCode;
@@ -3045,26 +3033,31 @@ export class SyncClient {
3045
3033
  ? [{ type: 'ROUND_FAILURE', code: report }]
3046
3034
  : []),
3047
3035
  pull,
3048
- ...subs.map((sub) => definedObject({
3049
- type: 'SUBSCRIPTION',
3050
- id: sub.id,
3051
- table: sub.table,
3052
- scopes: sub.scopes,
3053
- params: sub.params,
3054
- cursor: sub.cursor,
3055
- bootstrapState: sub.bootstrapState,
3056
- })),
3036
+ ...(travels
3037
+ ? registered.map((unit) => ({ type: 'UNIT', scopes: unit.scopes }))
3038
+ : []),
3039
+ // §4.3: one PROGRESS per catching-up unit, in registration order.
3040
+ ...registered.flatMap((unit) => unit.cursor === undefined
3041
+ ? []
3042
+ : [
3043
+ definedObject({
3044
+ type: 'PROGRESS',
3045
+ id: unit.id,
3046
+ cursor: unit.cursor,
3047
+ bootstrapState: unit.bootstrapState,
3048
+ }),
3049
+ ]),
3057
3050
  ];
3058
3051
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
3059
- // sit between them and the pull/subscription tail (§1.5 ordering).
3052
+ // sit between them and the pull/unit/progress tail (§1.5 ordering).
3060
3053
  const lead = fixedFrames.slice(0, report !== undefined ? 2 : 1);
3061
3054
  let admitted = pushFrames.length;
3062
3055
  let deferred = encodedDeferred;
3063
3056
  if (byteCap !== undefined) {
3064
3057
  // The fixed frames encode as envelope + fixed frames + END; each
3065
3058
  // admitted push frame adds its own (5 + payload). Trimming the tail
3066
- // re-fits the request to the final subscription state.
3067
- const fixedBytes = encodeMessage({
3059
+ // re-fits the request to the final registration state.
3060
+ const fixedBytes = encodeRequest({
3068
3061
  wireVersion: PROTOCOL_WIRE_VERSION,
3069
3062
  msgKind: 'request',
3070
3063
  frames: fixedFrames,
@@ -3090,19 +3083,16 @@ export class SyncClient {
3090
3083
  ...pushFrames,
3091
3084
  ...fixedFrames.slice(lead.length),
3092
3085
  ];
3093
- const requestBytes = encodeMessage({
3086
+ const requestBytes = encodeRequest({
3094
3087
  wireVersion: PROTOCOL_WIRE_VERSION,
3095
3088
  msgKind: 'request',
3096
3089
  frames,
3097
3090
  });
3098
- const responseBytes = await this.#roundTrip(requestBytes);
3099
- const message = decodeMessage(responseBytes);
3100
- if (message.msgKind !== 'response') {
3101
- throw invalidRequest('transport returned a non-response message');
3102
- }
3091
+ const responseBytes = await this.#roundTrip(requestBytes, signal);
3092
+ const message = decodeResponse(responseBytes);
3103
3093
  // §1.5: a complete, decodable response ends the report obligation.
3104
3094
  this.#roundFailureCode = undefined;
3105
- const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
3095
+ const summary = await this.#processResponse(message, outbox, bytesToHex(pull.registrationDigest), 'pull', resetEpoch, signal);
3106
3096
  // §4.8 E1: the push half may have drained commits that pinned rows of
3107
3097
  // a shrunk window unit — retry any deferred evictions now.
3108
3098
  await this.#drainPendingEvictions();
@@ -3110,6 +3100,10 @@ export class SyncClient {
3110
3100
  ? { state: 'failed', errorCode: 'sync.scope_revoked' }
3111
3101
  : { state: 'complete' });
3112
3102
  this.#retryDelayMs = 250;
3103
+ // §7.1: a unit still catching up needs another round, also when the
3104
+ // drive that started its bootstrap ends early.
3105
+ if (summary.bootstrapping.length > 0)
3106
+ this.#setSyncNeeded(true);
3113
3107
  if (deferred > 0) {
3114
3108
  // §6.1 splitBatch remainder: more queued commits than this request
3115
3109
  // could carry — keep the sync-needed signal raised for the host.
@@ -3118,12 +3112,15 @@ export class SyncClient {
3118
3112
  }
3119
3113
  return summary;
3120
3114
  }
3121
- catch (error) {
3115
+ catch (caught) {
3122
3116
  // §1.5: a round that ended without a complete, decodable response is a
3123
3117
  // failure the server could not see — keep its code for the next request.
3124
- const unseen = this.#unseenRoundFailureCode(error);
3118
+ const unseen = this.#unseenRoundFailureCode(caught);
3125
3119
  if (unseen !== undefined)
3126
3120
  this.#roundFailureCode = unseen;
3121
+ // §7.8: a round the drive deadline aborted ends with the deadline's
3122
+ // error, whichever transport call observed the abort.
3123
+ const error = signal?.aborted === true ? signal.reason : caught;
3127
3124
  // §7.3.5: a request-level lease code stops-and-surfaces — record it
3128
3125
  // in leaseState (no local-data purge, §7.3.4) and re-throw. Not a
3129
3126
  // silent retry: the app drives recovery to a live resolver. The
@@ -3154,6 +3151,9 @@ export class SyncClient {
3154
3151
  ? details.causeKind
3155
3152
  : undefined;
3156
3153
  const unreachable = causeKind === 'connect' || causeKind === 'network';
3154
+ // The round's work is still owed; the host's connectivity resume runs it.
3155
+ if (unreachable)
3156
+ this.#setSyncNeeded(true);
3157
3157
  if (retryable && !unreachable) {
3158
3158
  const realtimeUnavailable = error instanceof RealtimeUnavailableError;
3159
3159
  const delay = realtimeUnavailable
@@ -3187,7 +3187,7 @@ export class SyncClient {
3187
3187
  * Callers that arrive during the same drive with the same budget share that
3188
3188
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
3189
3189
  *
3190
- * §7.7: one drive is bounded by a total deadline (`timeoutMs`, default
3190
+ * §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
3191
3191
  * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
3192
3192
  * aborts a socket round in flight; the round budget does not bound elapsed
3193
3193
  * time, and a transport that never answers must not hang the caller.
@@ -3197,11 +3197,9 @@ export class SyncClient {
3197
3197
  const timeoutMs = typeof options === 'number'
3198
3198
  ? SYNC_IDLE_TIMEOUT_MS
3199
3199
  : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
3200
- // §7.7: an explicit budget is a strict positive round count. Zero,
3200
+ // §7.8: an explicit budget is a strict positive round count. Zero,
3201
3201
  // 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');
3202
+ requireRoundBudget(maxRounds);
3205
3203
  if (timeoutMs !== Number.POSITIVE_INFINITY &&
3206
3204
  !(Number.isFinite(timeoutMs) && timeoutMs > 0))
3207
3205
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
@@ -3233,17 +3231,8 @@ export class SyncClient {
3233
3231
  async #syncIdleRounds(maxRounds, timeoutMs) {
3234
3232
  const budget = maxRounds ?? 20;
3235
3233
  const aggregate = {
3236
- pushed: 0,
3237
- applied: [],
3238
- rejected: [],
3239
- retryable: [],
3240
- conflicts: [],
3241
- commitsApplied: 0,
3242
- segmentRowsApplied: 0,
3234
+ ...emptySummary(0),
3243
3235
  bootstrapping: [],
3244
- resets: [],
3245
- revoked: [],
3246
- failed: [],
3247
3236
  deferredCommits: 0,
3248
3237
  schemaFloor: undefined,
3249
3238
  };
@@ -3270,27 +3259,29 @@ export class SyncClient {
3270
3259
  let round = 0;
3271
3260
  let expired = false;
3272
3261
  let timer;
3262
+ // One signal reaches every transport call of the drive's rounds.
3263
+ const controller = new AbortController();
3264
+ const expiredError = () => new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3273
3265
  const deadline = timeoutMs === Number.POSITIVE_INFINITY
3274
3266
  ? undefined
3275
3267
  : new Promise((_, reject) => {
3276
3268
  timer = setTimeout(() => {
3277
3269
  expired = true;
3270
+ const error = expiredError();
3278
3271
  // The transport may never answer; release the round so the
3279
3272
  // client can run another one after the caller sees the error.
3273
+ controller.abort(error);
3280
3274
  this.#abortPendingRound('syncUntilIdle deadline exceeded');
3281
- reject(new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round }));
3275
+ reject(error);
3282
3276
  }, timeoutMs);
3283
3277
  });
3284
3278
  const drive = (async () => {
3285
3279
  for (; round < budget; round++) {
3286
3280
  // The race already rejected; stop spending rounds on a dead drive.
3287
3281
  if (expired)
3288
- throw new ClientSyncError('sync.idle_timeout', 'syncUntilIdle exceeded its deadline', true, { timeoutMs, rounds: round });
3289
- const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
3290
- sub.id,
3291
- sub.bootstrapState,
3292
- ]));
3293
- const last = await this.sync();
3282
+ throw expiredError();
3283
+ const before = JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3284
+ const last = await this.#sync(controller.signal);
3294
3285
  // Historical counters accumulate; current readiness (`bootstrapping`,
3295
3286
  // `deferredCommits`, `schemaFloor`) describes the latest round.
3296
3287
  aggregate.pushed += last.pushed;
@@ -3313,10 +3304,7 @@ export class SyncClient {
3313
3304
  last.segmentRowsApplied > 0 &&
3314
3305
  last.bootstrapping.length > 0 &&
3315
3306
  before !==
3316
- JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
3317
- sub.id,
3318
- sub.bootstrapState,
3319
- ])))
3307
+ JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState])))
3320
3308
  round = -1;
3321
3309
  if (last.commitsApplied === 0 &&
3322
3310
  last.segmentRowsApplied === 0 &&
@@ -3347,7 +3335,7 @@ export class SyncClient {
3347
3335
  * refuses the round with `RealtimeUnavailableError` instead of using the
3348
3336
  * seam (SPEC §8.8).
3349
3337
  */
3350
- #roundTrip(request) {
3338
+ #roundTrip(request, signal) {
3351
3339
  const socket = this.#socket;
3352
3340
  if (socket !== undefined && this.#realtimePolicy !== 'off') {
3353
3341
  return new Promise((resolve, reject) => {
@@ -3368,7 +3356,9 @@ export class SyncClient {
3368
3356
  // The socket could not carry the round: record the same loss the
3369
3357
  // Rust core records when its realtime round call fails (§8.8).
3370
3358
  this.#setRealtimeState('lost', 'sync.transport_failed');
3371
- reject(new ClientSyncError('sync.transport_failed', 'socket round send failed', true, { causeKind: 'unknown' }));
3359
+ reject(transportFailed('socket round send failed', {
3360
+ causeKind: 'unknown',
3361
+ }));
3372
3362
  }
3373
3363
  });
3374
3364
  }
@@ -3378,13 +3368,15 @@ export class SyncClient {
3378
3368
  throw this.#realtimeUnavailableError();
3379
3369
  }
3380
3370
  return Promise.resolve()
3381
- .then(() => this.#config.transport(request))
3371
+ .then(() => this.#config.transport(request, signal))
3382
3372
  .catch((error) => {
3383
3373
  if (error instanceof ClientSyncError ||
3384
3374
  typeof error?.code === 'string') {
3385
3375
  throw error;
3386
3376
  }
3387
- throw new ClientSyncError('sync.transport_failed', 'transport round failed', true, { causeKind: 'unknown' });
3377
+ throw transportFailed('transport round failed', {
3378
+ causeKind: 'unknown',
3379
+ });
3388
3380
  });
3389
3381
  }
3390
3382
  /**
@@ -3412,7 +3404,7 @@ export class SyncClient {
3412
3404
  if (round === undefined)
3413
3405
  return;
3414
3406
  this.#pendingRound = undefined;
3415
- round.reject(new ClientSyncError('sync.transport_failed', reason, true));
3407
+ round.reject(typeof reason === 'string' ? transportFailed(reason) : reason);
3416
3408
  }
3417
3409
  // -- realtime (§8 client side) ----------------------------------------------
3418
3410
  /**
@@ -3464,17 +3456,19 @@ export class SyncClient {
3464
3456
  onText: (text) => {
3465
3457
  if (generation !== this.#realtimeGeneration || !this.#started)
3466
3458
  return;
3467
- this.#handleRealtimeText(text);
3459
+ this.#heard(this.#handleRealtimeText(text));
3468
3460
  },
3469
3461
  onBinary: (bytes) => {
3470
3462
  if (generation !== this.#realtimeGeneration || !this.#started)
3471
3463
  return;
3464
+ this.#heard();
3472
3465
  this.#routeRealtimeBinary(bytes);
3473
3466
  },
3474
3467
  onClose: () => {
3475
3468
  if (openedSocket === undefined || this.#socket !== openedSocket)
3476
3469
  return;
3477
3470
  this.#socket = undefined;
3471
+ this.#disarm();
3478
3472
  this.#presence.clear(); // §8.6.1: presence is per-connection
3479
3473
  // §8.8: an undesired close is a visible lost state, not a silent
3480
3474
  // downgrade to HTTP rounds.
@@ -3482,7 +3476,7 @@ export class SyncClient {
3482
3476
  this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
3483
3477
  this.#emitDiagnostics();
3484
3478
  },
3485
- });
3479
+ }, this.#clientId);
3486
3480
  openedSocket = socket;
3487
3481
  if (!this.#transportEnabled) {
3488
3482
  socket.close();
@@ -3513,6 +3507,7 @@ export class SyncClient {
3513
3507
  this.#realtimeConnectPromise = undefined;
3514
3508
  this.#socket?.close();
3515
3509
  this.#socket = undefined;
3510
+ this.#disarm();
3516
3511
  this.#presence.clear(); // §8.6.1: presence is per-connection
3517
3512
  this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
3518
3513
  this.#setRealtimeState(this.#realtimePolicy === 'off'
@@ -3527,14 +3522,37 @@ export class SyncClient {
3527
3522
  * Close the socket and record the loss; later rounds use the configured
3528
3523
  * transport until the supervisor reconnects.
3529
3524
  */
3530
- #loseSocket() {
3525
+ #loseSocket(code = REALTIME_LOST_CODE) {
3531
3526
  const socket = this.#socket;
3532
3527
  this.#socket = undefined;
3528
+ this.#disarm();
3533
3529
  this.#presence.clear(); // §8.6.1: presence is per-connection
3534
- this.#setRealtimeState('lost', REALTIME_LOST_CODE);
3530
+ this.#setRealtimeState('lost', code);
3535
3531
  socket?.close();
3536
3532
  this.#emitDiagnostics();
3537
3533
  }
3534
+ /**
3535
+ * SPEC §8.5 watchdog: the connection's first `heartbeat` arms it; once
3536
+ * armed, every inbound frame restarts it, and twice the interval of
3537
+ * silence loses the socket. A server that sends no heartbeats never arms it.
3538
+ */
3539
+ #heard(heartbeat) {
3540
+ if (this.#socket === undefined ||
3541
+ !this.#transportEnabled ||
3542
+ (this.#watchdog === undefined && heartbeat !== true))
3543
+ return;
3544
+ this.#watchdog?.();
3545
+ this.#watchdog = this.#schedule(() => {
3546
+ this.#loseSocket('transport.timeout');
3547
+ this.#abortPendingRound(new ClientSyncError('transport.timeout', 'realtime heartbeat missed', true, {
3548
+ causeKind: 'heartbeat',
3549
+ }));
3550
+ }, 2 * this.#heartbeatMs);
3551
+ }
3552
+ #disarm() {
3553
+ this.#watchdog?.();
3554
+ this.#watchdog = undefined;
3555
+ }
3538
3556
  /**
3539
3557
  * §8.7 channel-tag routing (synchronous, so chunk order is preserved):
3540
3558
  * `0x01` chunks feed the in-flight round's assembler; `0x00` messages
@@ -3575,6 +3593,7 @@ export class SyncClient {
3575
3593
  }
3576
3594
  // Unknown tag: tolerated and ignored (§8.7 closed registry).
3577
3595
  }
3596
+ /** Returns whether the text was a §8.5 `heartbeat`. */
3578
3597
  #handleRealtimeText(text) {
3579
3598
  let parsed;
3580
3599
  try {
@@ -3599,43 +3618,40 @@ export class SyncClient {
3599
3618
  this.#emitSyncNeeded(event.data.reason);
3600
3619
  return;
3601
3620
  }
3602
- if (event.event === 'presence') {
3621
+ if (event.event === 'presence')
3603
3622
  this.#applyPresence(event.data);
3604
- }
3623
+ return event.event === 'heartbeat';
3605
3624
  }
3606
- /** §8.6 apply an inbound presence fanout to the local map. */
3625
+ /**
3626
+ * §8.6 apply an inbound presence fanout to the local map, or hand a
3627
+ * publisher-directed rejection (§8.6.2) to the listeners unchanged.
3628
+ */
3607
3629
  #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)
3630
+ const { scopeKey, kind, actorId, clientId, doc, error } = data;
3631
+ if (error === undefined) {
3632
+ // No `kind` is the client→server shape. The parser pins both ids and a
3633
+ // join/update doc on a fanout (§8.6.2); these checks narrow types.
3634
+ if (kind === undefined || actorId === undefined || clientId === undefined)
3628
3635
  return;
3629
- if (peers === undefined) {
3630
- peers = new Map();
3631
- this.#presence.set(scopeKey, peers);
3636
+ const peerKey = `${actorId} ${clientId}`;
3637
+ let peers = this.#presence.get(scopeKey);
3638
+ if (kind === 'leave') {
3639
+ peers?.delete(peerKey);
3640
+ if (peers?.size === 0)
3641
+ this.#presence.delete(scopeKey);
3642
+ }
3643
+ else if (doc) {
3644
+ if (peers === undefined) {
3645
+ peers = new Map();
3646
+ this.#presence.set(scopeKey, peers);
3647
+ }
3648
+ peers.set(peerKey, { actorId, clientId, doc });
3632
3649
  }
3633
- peers.set(peerKey, { actorId, clientId, doc });
3634
3650
  }
3635
- this.#config.onPresence?.(scopeKey);
3651
+ this.#config.onPresence?.(scopeKey, error);
3636
3652
  for (const listener of this.#presenceListeners) {
3637
3653
  try {
3638
- listener(scopeKey);
3654
+ listener(scopeKey, error);
3639
3655
  }
3640
3656
  catch {
3641
3657
  // A UI listener must never break presence application.
@@ -3664,9 +3680,7 @@ export class SyncClient {
3664
3680
  return;
3665
3681
  }
3666
3682
  try {
3667
- const message = decodeMessage(bytes);
3668
- if (message.msgKind !== 'response')
3669
- return;
3683
+ const message = decodeResponse(bytes);
3670
3684
  // §8.2: deltas apply like pull responses; ack after apply.
3671
3685
  await this.#processResponse(message, [], undefined, 'delta');
3672
3686
  }
@@ -3681,23 +3695,21 @@ export class SyncClient {
3681
3695
  if (this.#transportEnabled)
3682
3696
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
3683
3697
  }
3684
- /** Ack the highest cursor that is contiguously applied for every sub. */
3698
+ /** §8.2: after a pull round, ack the replica cursor while it is `>= 0`. */
3685
3699
  #ackAfterPull() {
3686
- if (this.#socket === undefined)
3687
- return;
3688
- const cursors = loadSubscriptions(this.#db)
3689
- .filter((sub) => sub.status === 'active' && sub.bootstrapState === undefined)
3690
- .map((sub) => sub.cursor)
3691
- .filter((cursor) => cursor >= 0);
3692
- if (cursors.length === 0)
3693
- return;
3694
- this.#sendAck(Math.min(...cursors));
3700
+ const cursor = replicaCursor(this.#db);
3701
+ if (this.#socket !== undefined && cursor >= 0)
3702
+ this.#sendAck(cursor);
3695
3703
  }
3696
3704
  // -- response processing ------------------------------------------------------
3697
- async #processResponse(message, sentCommits, sentSubs, mode, resetEpoch = this.#localResetEpoch) {
3705
+ /**
3706
+ * Apply one response (§1.6) or realtime delta (§8.2). `sentDigest` is the
3707
+ * hex registration digest of the pull this response answers; the server
3708
+ * stores that list once the round completes (§4.1).
3709
+ */
3710
+ async #processResponse(message, sentCommits, sentDigest, mode, resetEpoch = this.#localResetEpoch, signal) {
3698
3711
  const summary = emptySummary(sentCommits.length);
3699
3712
  const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
3700
- const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
3701
3713
  const rejectionDetailsByCommit = new Map();
3702
3714
  let lastFinalPushResult;
3703
3715
  for (const frame of message.frames) {
@@ -3714,11 +3726,6 @@ export class SyncClient {
3714
3726
  if (header?.type !== 'RESP_HEADER') {
3715
3727
  throw invalidRequest('missing RESP_HEADER');
3716
3728
  }
3717
- if (message.wireVersion < 2 ||
3718
- header.logEpoch === undefined ||
3719
- header.resetRequired === undefined) {
3720
- throw new ClientSyncError('client.invalid_host_response', 'the server response does not carry wire version 2 log-epoch state');
3721
- }
3722
3729
  if (header.requiredSchemaVersion !== undefined) {
3723
3730
  // §1.6 schema floor: nothing else was processed — stop syncing and
3724
3731
  // surface the upgrade requirement. A live-round floor always stops:
@@ -3754,114 +3761,62 @@ export class SyncClient {
3754
3761
  }
3755
3762
  let section;
3756
3763
  let errorFrame;
3764
+ let liveStart;
3765
+ let liveEnded = false;
3757
3766
  let deltaCursor = -1;
3758
- 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.
3767
+ let deltaDropped = false;
3768
+ // §4.5 client application: the units whose persisted echo a live-section
3769
+ // change must match, fixed at LIVE_START after every SUB_END persisted.
3770
+ let receivers = [];
3771
+ // §5.4/§5.5: queue every segment download of this response, so a paged
3772
+ // bootstrap overlaps its page fetches instead of paying one blocking round
3773
+ // trip per page. At most four downloads run at once, the Rust native
3774
+ // transport's pool size: enough to overlap round trips, while the client
3775
+ // holds at most four bodies, the one being applied and three ahead. The
3776
+ // loop takes each body out of the map before applying it and tops the
3777
+ // window up at the next descriptor. Eligibility mirrors the loop: a
3778
+ // descriptor outside an applied section or from an unconfigured
3779
+ // downloader is never queued, and a failure is only observed where the
3780
+ // loop awaits it. A promise left over because an earlier frame ended
3781
+ // apply is handled at creation, never unhandled.
3782
+ const queued = [];
3767
3783
  const prefetched = new Map();
3784
+ const prefetch = () => {
3785
+ for (let next; prefetched.size < 4 && (next = queued.shift());) {
3786
+ const [frame, scopes] = next;
3787
+ const pending = this.#downloadSegment(frame, scopes, (bytes) => {
3788
+ // Only the descriptor the loop is applying reports bytes; a
3789
+ // sibling still in flight would overwrite its progress.
3790
+ if (reporting === frame)
3791
+ this.#progress.update({ bytesReceived: bytes });
3792
+ }, signal);
3793
+ pending.catch(() => { });
3794
+ prefetched.set(frame, pending);
3795
+ }
3796
+ };
3768
3797
  let reporting;
3769
- const deleteKey = (commitSeq, table, rowId) => `${commitSeq}\u0000${table}\u0000${rowId}`;
3770
- {
3771
- let openSub;
3798
+ if (mode === 'pull') {
3799
+ let open;
3772
3800
  for (const frame of message.frames) {
3773
3801
  if (frame.type === 'SUB_START') {
3774
- 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;
3802
+ const unit = getUnit(this.#db, frame.id);
3803
+ open = unit?.status === 'active' ? unit : undefined;
3781
3804
  }
3782
- else if (frame.type === 'SUB_END') {
3783
- openSub = undefined;
3805
+ else if (frame.type === 'SUB_END' || frame.type === 'LIVE_START') {
3806
+ open = undefined;
3784
3807
  }
3785
3808
  else if (frame.type === 'ERROR') {
3786
3809
  break; // the round fails at this frame: later refs are not fetched
3787
3810
  }
3788
3811
  else if (frame.type === 'SEGMENT_REF' &&
3789
- openSub !== undefined &&
3812
+ open !== undefined &&
3790
3813
  this.#config.segments !== undefined &&
3791
3814
  !(frame.mediaType === 'sqlite' &&
3792
3815
  (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);
3801
- }
3802
- }
3803
- }
3804
- // §2.2 scope migration: the server emits the delete tagged with the old
3805
- // scope and the upsert tagged with the new one in one commit. A reader
3806
- // that holds both scopes receives them in two subscription sections, so
3807
- // the section order would otherwise decide whether the row survives. One
3808
- // commit's delete and upsert of the same row are one change, and the
3809
- // upsert wins. A frame that carries both itself keeps its own operation
3810
- // order; only a pair split across sections is coalesced.
3811
- const coalescedDeletes = new Set();
3812
- {
3813
- const ops = new Map();
3814
- const bothInFrame = new Set();
3815
- let openSub;
3816
- let frameIndex = -1;
3817
- for (const frame of message.frames) {
3818
- if (frame.type === 'SUB_START') {
3819
- 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;
3826
- }
3827
- else if (frame.type === 'SUB_END') {
3828
- openSub = undefined;
3829
- }
3830
- else if (frame.type === 'ERROR') {
3831
- break;
3832
- }
3833
- else if (frame.type === 'COMMIT' && openSub !== undefined) {
3834
- frameIndex += 1;
3835
- const local = new Map();
3836
- for (const change of frame.changes) {
3837
- const table = frame.tables[change.tableIndex];
3838
- if (table === undefined)
3839
- continue;
3840
- const key = deleteKey(frame.commitSeq, table, change.rowId);
3841
- const entry = ops.get(key) ?? {
3842
- upserts: new Set(),
3843
- deletes: new Set(),
3844
- };
3845
- if (change.op === 'upsert')
3846
- entry.upserts.add(frameIndex);
3847
- else
3848
- entry.deletes.add(frameIndex);
3849
- ops.set(key, entry);
3850
- local.set(key, (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2));
3851
- }
3852
- for (const [key, seen] of local) {
3853
- if (seen === 3)
3854
- bothInFrame.add(key);
3855
- }
3856
- }
3857
- }
3858
- for (const [key, entry] of ops) {
3859
- if (!bothInFrame.has(key) &&
3860
- entry.upserts.size > 0 &&
3861
- entry.deletes.size > 0) {
3862
- coalescedDeletes.add(key);
3816
+ queued.push([frame, open.scopes]);
3863
3817
  }
3864
3818
  }
3819
+ prefetch();
3865
3820
  }
3866
3821
  // Each durable observer transaction emits its own revisioned batch.
3867
3822
  // Async decrypt/download work happens outside SQLite transactions.
@@ -3926,39 +3881,26 @@ export class SyncClient {
3926
3881
  // Pre-indexed above so companion ordering remains wire-additive.
3927
3882
  break;
3928
3883
  case 'SUB_START': {
3929
- const sub = subsById.get(frame.id);
3930
- const fresh = sub !== undefined &&
3931
- sub.cursor < 0 &&
3932
- sub.bootstrapState === undefined &&
3933
- frame.bootstrap;
3934
- const skip = sub === undefined ||
3935
- (mode === 'delta' &&
3936
- (sub.status !== 'active' || sub.bootstrapState !== undefined));
3937
- section = { start: frame, sub, fresh, skip, cleared: false };
3884
+ // §4.4: a section of a unit the app released while the round was
3885
+ // in flight is skipped; it never re-creates the unit. A delta
3886
+ // carries no unit section (§8.2).
3887
+ const unit = mode === 'pull' ? getUnit(this.#db, frame.id) : undefined;
3888
+ section =
3889
+ unit?.status === 'active'
3890
+ ? {
3891
+ start: frame,
3892
+ unit,
3893
+ seeded: new Set(unit.bootstrapState === undefined ? [] : unit.seeded),
3894
+ skip: false,
3895
+ }
3896
+ : undefined;
3938
3897
  break;
3939
3898
  }
3940
- case 'COMMIT':
3941
- if (section !== undefined &&
3942
- !section.skip &&
3943
- section.sub !== undefined) {
3944
- const changes = frame.changes.filter((change) => {
3945
- if (change.op !== 'delete')
3946
- return true;
3947
- const table = frame.tables[change.tableIndex];
3948
- return (table === undefined ||
3949
- !coalescedDeletes.has(deleteKey(frame.commitSeq, table, change.rowId)));
3950
- });
3951
- if (changes.length > 0) {
3952
- await this.#applyCommit({ ...frame, changes }, summary, section.sub.id, mode);
3953
- }
3954
- }
3955
- break;
3956
3899
  case 'SEGMENT_INLINE':
3957
3900
  case 'SEGMENT_REF': {
3958
- if (section === undefined ||
3959
- section.skip ||
3960
- section.sub === undefined)
3901
+ if (section === undefined || section.skip)
3961
3902
  break;
3903
+ const unitId = section.unit.id;
3962
3904
  if (frame.type === 'SEGMENT_REF' &&
3963
3905
  frame.mediaType === 'sqlite' &&
3964
3906
  (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
@@ -3968,7 +3910,7 @@ export class SyncClient {
3968
3910
  if (frame.type === 'SEGMENT_REF') {
3969
3911
  this.#progress.update({
3970
3912
  phase: 'download',
3971
- subscriptionId: section.sub.id,
3913
+ unitId,
3972
3914
  table: frame.table,
3973
3915
  segmentId: frame.segmentId,
3974
3916
  bytesReceived: 0,
@@ -3976,71 +3918,155 @@ export class SyncClient {
3976
3918
  rowsProcessed: 0,
3977
3919
  rowsTotal: frame.rowCount,
3978
3920
  });
3979
- const prefetch = prefetched.get(frame);
3980
- if (prefetch !== undefined)
3921
+ prefetch();
3922
+ const pending = prefetched.get(frame);
3923
+ prefetched.delete(frame);
3924
+ if (pending !== undefined)
3981
3925
  reporting = frame;
3982
- bytes = await (prefetch ??
3983
- this.#downloadSegment(frame, section.sub, (bytesReceived) => this.#progress.update({ bytesReceived })));
3984
- }
3985
- else {
3986
- bytes = frame.payload;
3987
- }
3988
- if (frame.type === 'SEGMENT_REF')
3926
+ bytes = await (pending ??
3927
+ this.#downloadSegment(frame, section.unit.scopes, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
3989
3928
  this.#progress.update({ phase: 'import' });
3990
- if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
3991
- // Images are whole-table; paged image descriptors are invalid.
3992
- if (frame.rowCursor !== undefined ||
3993
- frame.nextRowCursor !== undefined) {
3994
- throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
3995
- }
3996
- await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
3997
- table: frame.table,
3998
- rowCount: frame.rowCount,
3999
- asOfCommitSeq: frame.asOfCommitSeq,
4000
- scopeDigest: frame.scopeDigest,
4001
- }, this.#segmentApplyOptions(table, clearFirst, effective, frame.rowCount > 0, resetEpoch)), section.fresh && !section.cleared);
4002
3929
  }
4003
3930
  else {
4004
- const segment = decodeRowsSegment(bytes);
4005
- if (frame.type === 'SEGMENT_INLINE') {
4006
- this.#progress.update({
4007
- phase: 'import',
4008
- subscriptionId: section.sub.id,
4009
- table: section.sub.table,
4010
- segmentId: undefined,
4011
- bytesReceived: bytes.byteLength,
4012
- bytesTotal: bytes.byteLength,
4013
- rowsProcessed: 0,
4014
- rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
4015
- });
4016
- }
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 &&
4018
- !section.cleared &&
4019
- (frame.type === 'SEGMENT_INLINE' ||
4020
- frame.rowCursor === undefined));
3931
+ bytes = frame.payload;
4021
3932
  }
3933
+ const image = frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
3934
+ ? frame
3935
+ : undefined;
3936
+ // Images are whole-table; paged image descriptors are invalid.
3937
+ if (image !== undefined &&
3938
+ (image.rowCursor !== undefined ||
3939
+ image.nextRowCursor !== undefined))
3940
+ throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
3941
+ const segment = image === undefined ? decodeRowsSegment(bytes) : undefined;
3942
+ if (frame.type === 'SEGMENT_INLINE' && segment !== undefined)
3943
+ this.#progress.update({
3944
+ phase: 'import',
3945
+ unitId,
3946
+ table: segment.table,
3947
+ segmentId: undefined,
3948
+ bytesReceived: bytes.byteLength,
3949
+ bytesTotal: bytes.byteLength,
3950
+ rowsProcessed: 0,
3951
+ rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
3952
+ });
3953
+ await this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
3954
+ const options = this.#segmentApplyOptions(table, clearFirst, effective, owners, image !== undefined
3955
+ ? image.rowCount > 0
3956
+ : segment.blocks.some((block) => block.length > 0), resetEpoch);
3957
+ return image !== undefined
3958
+ ? applySqliteSegment(this.#db, this.#schema, table, bytes, image, options)
3959
+ : applyRowsSegment(this.#db, this.#schema, table, segment, options, this.#encryption);
3960
+ });
4022
3961
  break;
4023
3962
  }
4024
3963
  case 'SUB_END': {
4025
- if (section?.sub !== undefined &&
4026
- !section.skip &&
4027
- this.#localResetEpoch === resetEpoch) {
4028
- incompleteSubscriptions.delete(section.sub.id);
4029
- }
3964
+ // Reset fence: a rebootstrap that landed mid-round already rewound
3965
+ // this unit; the captured SUB_END predates the rewind and stays
3966
+ // unpersisted so the next round runs the fresh bootstrap.
4030
3967
  if (section !== undefined &&
4031
3968
  !section.skip &&
4032
- section.sub !== undefined &&
4033
- // Reset fence: a rebootstrap that landed mid-round already
4034
- // rewound this subscription's cursor; the captured SUB_END
4035
- // state predates the rewind and must stay unpersisted so the
4036
- // next round runs the fresh bootstrap.
4037
- this.#localResetEpoch === resetEpoch) {
4038
- const applied = this.#finishSection(section.sub, section.start, frame.nextCursor, frame.bootstrapState, summary);
4039
- if (mode === 'delta' && applied) {
4040
- deltaCursor = Math.max(deltaCursor, frame.nextCursor);
3969
+ this.#localResetEpoch === resetEpoch)
3970
+ this.#finishSection(section, frame, summary);
3971
+ section = undefined;
3972
+ break;
3973
+ }
3974
+ case 'LIVE_START': {
3975
+ liveStart = frame;
3976
+ const cursor = replicaCursor(this.#db);
3977
+ if (mode === 'delta') {
3978
+ const end = message.frames.find((candidate) => candidate.type === 'LIVE_END');
3979
+ // §8.2: a delta while no unit is live is a drop; one at or
3980
+ // below the replica cursor is a duplicate and no drop.
3981
+ if (frame.status !== 'active' || cursor < 0) {
3982
+ deltaDropped = true;
3983
+ liveStart = undefined;
4041
3984
  }
3985
+ else if (end?.type === 'LIVE_END' && end.throughSeq <= cursor)
3986
+ liveStart = undefined;
4042
3987
  }
4043
- section = undefined;
3988
+ receivers =
3989
+ liveStart?.status === 'active'
3990
+ ? loadUnits(this.#db).filter((unit) => owning(unit) &&
3991
+ (mode === 'pull' || unit.cursor === undefined))
3992
+ : [];
3993
+ break;
3994
+ }
3995
+ case 'COMMIT': {
3996
+ if (liveStart?.status !== 'active')
3997
+ break;
3998
+ const changes = frame.changes.filter((change) => {
3999
+ const table = this.#schema.tables.get(frame.tables[change.tableIndex] ?? '');
4000
+ // An unknown table fails loud in the apply below.
4001
+ return (table === undefined ||
4002
+ receivers.some((unit) => {
4003
+ const scopes = covers(table, unit.scopes)
4004
+ ? pairScopes(unit.scopes, table.name, unit.echo)
4005
+ : undefined;
4006
+ return (scopes !== undefined &&
4007
+ Object.entries(scopes).every(([variable, values]) => values.includes(change.scopes[variable] ?? '\0')));
4008
+ }));
4009
+ });
4010
+ if (changes.length > 0)
4011
+ await this.#applyCommit({ ...frame, changes }, summary, mode);
4012
+ break;
4013
+ }
4014
+ case 'LIVE_END': {
4015
+ if (mode === 'delta') {
4016
+ if (liveStart !== undefined) {
4017
+ setMeta(this.#db, REPLICA_CURSOR_KEY, String(frame.throughSeq));
4018
+ deltaCursor = frame.throughSeq;
4019
+ }
4020
+ break;
4021
+ }
4022
+ if (liveStart === undefined || this.#localResetEpoch !== resetEpoch)
4023
+ break;
4024
+ liveEnded = true;
4025
+ const status = liveStart.status;
4026
+ const reasonCode = liveStart.reasonCode;
4027
+ const before = replicaCursor(this.#db);
4028
+ this.#applyBatch((batch) => {
4029
+ let cursor = status === 'unregistered' ? before : -1;
4030
+ const joined = Math.max(before, frame.throughSeq);
4031
+ for (const unit of loadUnits(this.#db)) {
4032
+ if (unit.status !== 'active' || bootstrapping(unit))
4033
+ continue;
4034
+ if (status === 'reset') {
4035
+ // §4.6 replica reset: every live unit bootstraps again;
4036
+ // post-bootstrap units keep their cursors.
4037
+ if (unit.cursor !== undefined)
4038
+ continue;
4039
+ saveUnit(this.#db, {
4040
+ ...unit,
4041
+ reasonCode,
4042
+ cursor: -1,
4043
+ seeded: [],
4044
+ });
4045
+ summary.resets.push(unit.id);
4046
+ for (const ref of windowRefs(this.#db, unit.id))
4047
+ batch.window(ref.baseKey, ref.value);
4048
+ }
4049
+ else if (status === 'active') {
4050
+ // §4.5 join rule J.
4051
+ const next = Math.max(unit.cursor ?? joined, frame.throughSeq);
4052
+ if (next >= joined)
4053
+ cursor = joined;
4054
+ if (unit.cursor !== undefined)
4055
+ saveUnit(this.#db, {
4056
+ ...unit,
4057
+ cursor: next >= joined ? undefined : next,
4058
+ });
4059
+ }
4060
+ }
4061
+ setMeta(this.#db, REPLICA_CURSOR_KEY, String(cursor));
4062
+ setMeta(this.#db, ECHO_DIGEST_KEY, bytesToHex(frame.echoDigest));
4063
+ if (status === 'unregistered')
4064
+ this.#db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
4065
+ REGISTERED_DIGEST_KEY,
4066
+ ]);
4067
+ else
4068
+ setMeta(this.#db, REGISTERED_DIGEST_KEY, sentDigest);
4069
+ });
4044
4070
  break;
4045
4071
  }
4046
4072
  case 'ERROR': {
@@ -4076,34 +4102,44 @@ export class SyncClient {
4076
4102
  }
4077
4103
  if (errorFrame !== undefined)
4078
4104
  throw errorFrame;
4079
- if (incompleteSubscriptions.size > 0) {
4080
- this.#setSyncNeeded(true);
4081
- this.#emitSyncIntent({ kind: 'interactive' });
4082
- }
4083
4105
  if (mode === 'delta') {
4084
4106
  if (deltaCursor >= 0)
4085
4107
  this.#sendAck(deltaCursor);
4108
+ // §8.2: an unapplied delta is a drop; a pull repairs it.
4109
+ if (deltaDropped) {
4110
+ this.#setSyncNeeded(true);
4111
+ this.#emitSyncNeeded('catchup-required');
4112
+ }
4086
4113
  }
4087
4114
  else {
4088
4115
  this.#ackAfterPull();
4089
4116
  }
4090
- const bootstrapping = loadSubscriptions(this.#db)
4091
- .filter((sub) => sub.status === 'active' && sub.bootstrapState !== undefined)
4092
- .map((sub) => sub.id);
4117
+ const catchingUp = loadUnits(this.#db)
4118
+ .filter((unit) => unit.status === 'active' && unit.cursor !== undefined)
4119
+ .map((unit) => unit.id);
4120
+ // §7.1: a response without LIVE_END, one answered `unregistered` or
4121
+ // `reset`, or a unit still catching up leaves sync-needed raised; after
4122
+ // `unregistered` the next round starts at once.
4123
+ if (mode === 'pull' &&
4124
+ (!liveEnded || liveStart?.status !== 'active' || catchingUp.length > 0)) {
4125
+ this.#setSyncNeeded(true);
4126
+ if (liveStart?.status === 'unregistered')
4127
+ this.#emitSyncIntent({ kind: 'interactive' });
4128
+ }
4093
4129
  // §7.4.5: the reset is over once the first post-reset pull round leaves
4094
- // no subscription mid-bootstrap — the tables are rebuilt and current.
4095
- // The epoch check keeps a round that predates a mid-flight rebootstrap
4096
- // from declaring that reset finished before its bootstrap ran.
4130
+ // no unit catching up: the tables are rebuilt and current. The epoch
4131
+ // check keeps a round that predates a mid-flight rebootstrap from
4132
+ // declaring that reset finished before its bootstrap ran.
4097
4133
  if (this.#upgrading &&
4098
4134
  mode === 'pull' &&
4099
- bootstrapping.length === 0 &&
4135
+ catchingUp.length === 0 &&
4100
4136
  this.#localResetEpoch === resetEpoch) {
4101
4137
  this.#setUpgrading(false);
4102
4138
  }
4103
4139
  // RFC 0005 D7: coverage completion, lease end, scope revocation and TTL are
4104
4140
  // evaluated once per round, after the apply.
4105
4141
  this.#previousVersionLifetimeCheck();
4106
- return { ...summary, bootstrapping };
4142
+ return { ...summary, bootstrapping: catchingUp };
4107
4143
  }
4108
4144
  #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
4109
4145
  const commit = commitsById.get(frame.clientCommitId);
@@ -4259,7 +4295,7 @@ export class SyncClient {
4259
4295
  });
4260
4296
  return names;
4261
4297
  }
4262
- async #applyCommit(frame, summary, subscriptionId, source) {
4298
+ async #applyCommit(frame, summary, source) {
4263
4299
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4264
4300
  this.#recordCommitChanges(batch, frame);
4265
4301
  const result = fn();
@@ -4267,7 +4303,6 @@ export class SyncClient {
4267
4303
  for (const table of new Set(frame.changes.map((change) => frame.tables[change.tableIndex]))) {
4268
4304
  if (table !== undefined)
4269
4305
  batch.appliedCommit({
4270
- subscriptionId,
4271
4306
  table,
4272
4307
  commitSeq: frame.commitSeq,
4273
4308
  source,
@@ -4316,21 +4351,22 @@ export class SyncClient {
4316
4351
  return recorded;
4317
4352
  }
4318
4353
  /** Whether a fresh-bootstrap clear would remove at least one local row. */
4319
- #scopedRowsExist(table, effective) {
4320
- const scope = localScopePredicate(table, effective);
4354
+ #scopedRowsExist(table, effective, owners) {
4355
+ const scope = localScopePredicate(table, effective, owners);
4321
4356
  return (scope !== undefined &&
4322
4357
  this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
4323
4358
  }
4324
4359
  /** Shared transaction, reset fence and progress for both segment formats. */
4325
- #segmentApplyOptions(table, clearFirst, effective, hasRows, resetEpoch) {
4360
+ #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch) {
4326
4361
  return {
4327
4362
  clearFirst,
4328
4363
  effective,
4364
+ owners,
4329
4365
  isCurrent: () => this.#localResetEpoch === resetEpoch,
4330
4366
  onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
4331
4367
  transaction: (fn) => this.#applyBatch((batch) => {
4332
4368
  if (hasRows ||
4333
- (clearFirst && this.#scopedRowsExist(table, effective)))
4369
+ (clearFirst && this.#scopedRowsExist(table, effective, owners)))
4334
4370
  batch.table(table.name);
4335
4371
  const result = fn();
4336
4372
  this.#replayOutbox(result, false);
@@ -4339,46 +4375,44 @@ export class SyncClient {
4339
4375
  };
4340
4376
  }
4341
4377
  /**
4342
- * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
4343
- * (no local scope-column mapping) marks the subscription `failed` and
4344
- * stops syncing the table without failing the whole request.
4378
+ * Apply a segment (rows or sqlite image) of `tableName` within a unit
4379
+ * section: the first segment of the table in the bootstrap clears the
4380
+ * pair's scope first (§5.6). A fail-closed error (no local scope-column
4381
+ * mapping) marks the unit `failed` without failing the whole response.
4345
4382
  */
4346
- async #applySegmentOrFail(section, summary, apply, clearFirst) {
4347
- const sub = section.sub;
4348
- if (sub === undefined)
4349
- return;
4350
- const table = this.#table(sub.table);
4383
+ async #applySegmentOrFail(section, summary, tableName, apply) {
4384
+ const { unit } = section;
4385
+ const table = this.#table(tableName);
4386
+ const effective = covers(table, unit.scopes)
4387
+ ? pairScopes(unit.scopes, tableName, section.start.fenced)
4388
+ : undefined;
4389
+ if (effective === undefined)
4390
+ throw invalidRequest('a segment names no active pair of its unit');
4351
4391
  try {
4352
- summary.segmentRowsApplied += await apply(table, clearFirst, section.start.effectiveScopes);
4353
- section.cleared = true;
4392
+ summary.segmentRowsApplied += await apply(table, !section.seeded.has(tableName), effective, unitOwners(loadUnits(this.#db), table, unit.id));
4393
+ section.seeded.add(tableName);
4354
4394
  }
4355
4395
  catch (error) {
4356
- if (error instanceof ClientSyncError &&
4357
- error.code === 'sync.scope_revoked') {
4358
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4359
- this.#applyBatch((batch) => {
4360
- saveSubscription(this.#db, definedObject({
4361
- id: sub.id,
4362
- table: sub.table,
4363
- scopes: sub.scopes,
4364
- params: sub.params,
4365
- cursor: sub.cursor,
4366
- effectiveScopes: sub.effectiveScopes,
4367
- status: 'failed',
4368
- reasonCode: 'sync.scope_revoked',
4369
- }));
4370
- if (registered !== undefined) {
4371
- batch.window(registered.baseKey, sub.table, registered.unit);
4372
- }
4373
- });
4374
- summary.failed.push(sub.id);
4375
- section.skip = true;
4396
+ if (!(error instanceof ClientSyncError) ||
4397
+ error.code !== 'sync.scope_revoked')
4398
+ throw error;
4399
+ section.skip = true;
4400
+ const current = getUnit(this.#db, unit.id);
4401
+ if (current === undefined)
4376
4402
  return;
4377
- }
4378
- throw error;
4403
+ this.#applyBatch((batch) => {
4404
+ saveUnit(this.#db, {
4405
+ ...current,
4406
+ status: 'failed',
4407
+ reasonCode: 'sync.scope_revoked',
4408
+ });
4409
+ for (const ref of windowRefs(this.#db, unit.id))
4410
+ batch.window(ref.baseKey, ref.value);
4411
+ });
4412
+ summary.failed.push(unit.id);
4379
4413
  }
4380
4414
  }
4381
- async #downloadSegment(frame, sub, onProgress) {
4415
+ async #downloadSegment(frame, scopes, onProgress, signal) {
4382
4416
  const downloader = this.#config.segments;
4383
4417
  if (downloader === undefined) {
4384
4418
  throw invalidRequest('received SEGMENT_REF but no segment downloader is configured');
@@ -4399,19 +4433,29 @@ export class SyncClient {
4399
4433
  // §5.4: MUST NOT start a fetch at/past expiry.
4400
4434
  throw new ClientSyncError('sync.segment_expired', `segment download grant expired; pull again (§5.4)`, true);
4401
4435
  }
4402
- bytes = await fetchUrl(frame.url, onProgress);
4436
+ bytes = await fetchUrl(frame.url, onProgress, signal, frame.byteLength);
4403
4437
  }
4404
4438
  else {
4405
4439
  bytes = await downloader({
4406
4440
  segmentId: frame.segmentId,
4407
4441
  table: frame.table,
4408
- requestedScopesJson: canonicalScopeJson(sub.scopes),
4442
+ // §5.5: the owning unit's scope map, each value a one-element list.
4443
+ requestedScopesJson: canonicalScopeJson(Object.fromEntries(Object.entries(scopes).map(([variable, value]) => [
4444
+ variable,
4445
+ [value],
4446
+ ]))),
4447
+ byteLength: frame.byteLength,
4409
4448
  onProgress,
4449
+ ...(signal !== undefined ? { signal } : {}),
4410
4450
  });
4411
4451
  }
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.
4452
+ // §5.4: the descriptor's byteLength caps the body; §5.1: verify the
4453
+ // content address before applying. On either failure the segment is
4454
+ // discarded and the cursor/resume token stay unpersisted, so the next
4455
+ // pull re-delivers.
4456
+ if (bytes.byteLength > frame.byteLength) {
4457
+ throw invalidRequest('segment exceeds its byteLength', true);
4458
+ }
4415
4459
  onProgress(bytes.byteLength);
4416
4460
  const hash = await sha256Hex(bytes);
4417
4461
  if (`sha256:${hash}` !== frame.segmentId) {
@@ -4420,159 +4464,172 @@ export class SyncClient {
4420
4464
  return bytes;
4421
4465
  }
4422
4466
  /** Returns whether SUB_END state was persisted (section applied). */
4423
- #finishSection(sub, start, nextCursor, bootstrapState, summary) {
4424
- if (start.status === 'active') {
4425
- // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
4426
- // §3.3: the effective-scope echo is persisted for the purge contract.
4427
- // An absent bootstrapState clears any previous resume token (§4.4:
4428
- // absent = bootstrap complete, or not bootstrapping).
4429
- const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
4430
- const completed = wasPending && nextCursor >= 0 && bootstrapState === undefined;
4431
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4432
- this.#applyBatch((batch) => {
4433
- saveSubscription(this.#db, definedObject({
4434
- id: sub.id,
4435
- table: sub.table,
4436
- scopes: sub.scopes,
4437
- params: sub.params,
4438
- cursor: nextCursor,
4439
- bootstrapState: bootstrapState,
4440
- effectiveScopes: start.effectiveScopes,
4441
- status: 'active',
4442
- }));
4443
- if (completed) {
4444
- const table = this.#table(sub.table);
4445
- const effective = start.effectiveScopes;
4446
- const covered = this.#db
4447
- .query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`, [sub.table, nextCursor])
4448
- .filter((row) => [row.intent, row.base].some((json) => {
4449
- if (json === null)
4450
- return false;
4451
- const values = JSON.parse(String(json));
4452
- return matchesLocalScopes(table, effective, values);
4453
- }));
4454
- if (covered.length) {
4455
- const scope = covered.map((row) => JSON.stringify([sub.table, String(row.id)]));
4456
- restoreFailedBases(this.#db, this.#schema, scope);
4457
- for (const row of covered)
4458
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [sub.table, String(row.id), nextCursor]);
4459
- batch.table(sub.table);
4460
- this.#replayOutbox(scope, false);
4461
- }
4462
- }
4463
- if (completed && registered !== undefined) {
4464
- // A zero-row bootstrap is a window-domain transition, not a fake
4465
- // row/table change (SPEC §4.8 / §7.5).
4466
- batch.window(registered.baseKey, sub.table, registered.unit);
4467
- }
4468
- });
4469
- return true;
4470
- }
4471
- if (start.status === 'reset') {
4472
- // §4.6: discard cursor + resume token, keep local rows, re-bootstrap
4473
- // with cursor = -1 on the next pull. Staleness, not a purge.
4474
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4475
- this.#applyBatch((batch) => {
4476
- saveSubscription(this.#db, definedObject({
4477
- id: sub.id,
4478
- table: sub.table,
4479
- scopes: sub.scopes,
4480
- params: sub.params,
4481
- cursor: -1,
4482
- effectiveScopes: sub.effectiveScopes,
4483
- status: 'active',
4484
- reasonCode: start.reasonCode,
4485
- }));
4486
- if (registered !== undefined) {
4487
- batch.window(registered.baseKey, sub.table, registered.unit);
4488
- }
4489
- });
4490
- summary.resets.push(sub.id);
4491
- return false;
4492
- }
4493
- // revoked (§3.3): purge rows matching the LAST-echoed effective scopes
4494
- // (never the requested map), drop doomed outbox commits, stop pulling.
4495
- const table = this.#table(sub.table);
4496
- const lastEffective = sub.effectiveScopes;
4497
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4498
- let failed = false;
4467
+ /**
4468
+ * Persist a unit section at its `SUB_END` (§4.4): the cursor, resume token,
4469
+ * seeded tables and echo of an active section; the reset of a `reset`
4470
+ * section (§4.6); the purge of every pair the response revokes (§3.3).
4471
+ */
4472
+ #finishSection(section, end, summary) {
4473
+ const { start } = section;
4474
+ // §4.4: SUB_END writes only into a unit that is still registered. An
4475
+ // unsubscribe during this round's awaits removed it.
4476
+ const unit = getUnit(this.#db, start.id);
4477
+ if (unit?.status !== 'active')
4478
+ return;
4479
+ const refs = windowRefs(this.#db, unit.id);
4499
4480
  this.#applyBatch((batch) => {
4500
- if (lastEffective !== undefined &&
4501
- Object.keys(lastEffective).length > 0) {
4502
- try {
4503
- const scope = [
4504
- JSON.stringify([table.name]),
4505
- ...this.#dropRetainedRows(batch, (name, values) => name === table.name &&
4506
- matchesLocalScopes(table, lastEffective, values)),
4507
- ];
4508
- deleteScopedRows(this.#db, table, lastEffective);
4509
- 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;
4520
- const results = commit.operations.map((operation, opIndex) => {
4521
- const rejection = {
4522
- clientCommitId,
4523
- opIndex,
4524
- code: 'sync.scope_revoked',
4525
- message: 'the commit was dropped because its effective scope was revoked',
4526
- retryable: false,
4527
- operation,
4528
- };
4529
- this.#rejections.push(rejection);
4530
- return { status: 'error', rejection };
4531
- });
4532
- recordCommitOutcome(this.#db, {
4533
- clientCommitId,
4534
- status: 'rejected',
4535
- recordedAtMs: this.#now(),
4536
- results,
4537
- operations: commit.operations,
4538
- });
4539
- }
4540
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4541
- batch.status();
4542
- batch.rejections();
4543
- batch.outcomes();
4544
- }
4545
- this.#replayOutbox(scope);
4546
- this.#deleteUnreferencedBlobs();
4547
- }
4548
- catch (error) {
4549
- if (error instanceof ClientSyncError &&
4550
- error.code === 'sync.scope_revoked') {
4551
- failed = true;
4552
- }
4553
- else {
4554
- throw error;
4555
- }
4556
- }
4481
+ for (const ref of refs)
4482
+ batch.window(ref.baseKey, ref.value);
4483
+ if (start.status === 'reset') {
4484
+ // §4.6: discard cursor and resume token; the rows stay until the
4485
+ // bootstrap replaces them. Staleness, not a purge.
4486
+ saveUnit(this.#db, {
4487
+ ...unit,
4488
+ reasonCode: start.reasonCode,
4489
+ cursor: -1,
4490
+ bootstrapState: undefined,
4491
+ seeded: [],
4492
+ });
4493
+ summary.resets.push(unit.id);
4494
+ return;
4557
4495
  }
4558
- saveSubscription(this.#db, definedObject({
4559
- id: sub.id,
4560
- table: sub.table,
4561
- scopes: sub.scopes,
4562
- params: sub.params,
4563
- cursor: nextCursor,
4564
- effectiveScopes: lastEffective,
4565
- status: failed ? 'failed' : 'revoked',
4566
- reasonCode: start.reasonCode,
4567
- }));
4568
- if (registered !== undefined) {
4569
- batch.window(registered.baseKey, sub.table, registered.unit);
4496
+ const revoked = start.status === 'revoked';
4497
+ const units = loadUnits(this.#db);
4498
+ let failed = false;
4499
+ let rearmed = false;
4500
+ for (const table of this.#schema.tables.values()) {
4501
+ if (!covers(table, unit.scopes))
4502
+ continue;
4503
+ const last = unit.echo === undefined
4504
+ ? undefined
4505
+ : pairScopes(unit.scopes, table.name, unit.echo);
4506
+ const next = revoked
4507
+ ? undefined
4508
+ : pairScopes(unit.scopes, table.name, start.fenced);
4509
+ // §3.3: a revoked fenced record that turns active again re-bootstraps.
4510
+ if (unit.echo !== undefined && last === undefined && next !== undefined)
4511
+ rearmed = true;
4512
+ // §3.3: purge a pair the response revokes, keyed on the echo the
4513
+ // client persisted while the pair was active.
4514
+ if (last !== undefined && next === undefined)
4515
+ failed ||= !this.#purgePair(batch, table, last, unitOwners(units, table, unit.id));
4516
+ }
4517
+ if (revoked || failed) {
4518
+ saveUnit(this.#db, {
4519
+ ...unit,
4520
+ status: failed ? 'failed' : 'revoked',
4521
+ reasonCode: failed ? 'sync.scope_revoked' : start.reasonCode,
4522
+ cursor: -1,
4523
+ bootstrapState: undefined,
4524
+ seeded: [],
4525
+ echo: undefined,
4526
+ });
4527
+ if (revoked)
4528
+ summary.revoked.push(unit.id);
4529
+ if (failed)
4530
+ summary.failed.push(unit.id);
4531
+ batch.status();
4532
+ return;
4533
+ }
4534
+ const fresh = rearmed || start.bootstrap;
4535
+ saveUnit(this.#db, {
4536
+ ...unit,
4537
+ reasonCode: undefined,
4538
+ echo: start.fenced,
4539
+ ...(rearmed
4540
+ ? { cursor: -1, bootstrapState: undefined, seeded: [] }
4541
+ : start.bootstrap
4542
+ ? {
4543
+ cursor: end.nextCursor,
4544
+ bootstrapState: end.bootstrapState,
4545
+ seeded: end.bootstrapState === undefined ? [] : [...section.seeded],
4546
+ }
4547
+ : {}),
4548
+ });
4549
+ if (!fresh || rearmed || end.bootstrapState !== undefined)
4550
+ return;
4551
+ // §7.1: a completed bootstrap covers acknowledged intent of its pairs
4552
+ // at or below its pin.
4553
+ for (const table of this.#schema.tables.values()) {
4554
+ const effective = covers(table, unit.scopes)
4555
+ ? pairScopes(unit.scopes, table.name, start.fenced)
4556
+ : undefined;
4557
+ if (effective === undefined)
4558
+ continue;
4559
+ const covered = this.#db
4560
+ .query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`, [table.name, end.nextCursor])
4561
+ .filter((row) => [row.intent, row.base].some((json) => json !== null &&
4562
+ matchesLocalScopes(table, effective, JSON.parse(String(json)))));
4563
+ if (covered.length === 0)
4564
+ continue;
4565
+ const scope = covered.map((row) => JSON.stringify([table.name, String(row.id)]));
4566
+ restoreFailedBases(this.#db, this.#schema, scope);
4567
+ for (const row of covered)
4568
+ this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [table.name, String(row.id), end.nextCursor]);
4569
+ batch.table(table.name);
4570
+ this.#replayOutbox(scope, false);
4570
4571
  }
4571
4572
  });
4572
- summary.revoked.push(sub.id);
4573
- if (failed)
4574
- summary.failed.push(sub.id);
4575
- return false;
4573
+ }
4574
+ /**
4575
+ * §3.3: purge one revoked pair: delete the rows matching its last effective
4576
+ * scopes that no owner holds, drop every pending commit that provably
4577
+ * writes into them, and rebuild the overlay. Returns false when the table
4578
+ * has no local scope-column mapping (fail closed: nothing deleted).
4579
+ */
4580
+ #purgePair(batch, table, lastEffective, owners) {
4581
+ try {
4582
+ const scope = [
4583
+ JSON.stringify([table.name]),
4584
+ ...this.#dropRetainedRows(batch, (name, values) => name === table.name &&
4585
+ ownsLocalRow(table, lastEffective, owners, values)),
4586
+ ];
4587
+ deleteScopedRows(this.#db, table, lastEffective, owners);
4588
+ batch.scopeMap(table, lastEffective);
4589
+ // §3.3: a whole pending commit leaves when one of its upserts
4590
+ // provably lands in the revoked scopes and no other owner covers it.
4591
+ const doomed = listOutbox(this.#db).filter((commit) => commit.operations.some((op) => op.table === table.name &&
4592
+ op.values !== undefined &&
4593
+ ownsLocalRow(table, lastEffective, owners, op.values)));
4594
+ for (const commit of doomed) {
4595
+ const { clientCommitId } = commit;
4596
+ deleteOutboxCommit(this.#db, clientCommitId);
4597
+ const results = commit.operations.map((operation, opIndex) => {
4598
+ const rejection = {
4599
+ clientCommitId,
4600
+ opIndex,
4601
+ code: 'sync.scope_revoked',
4602
+ message: 'the commit was dropped because its effective scope was revoked',
4603
+ retryable: false,
4604
+ operation,
4605
+ };
4606
+ this.#rejections.push(rejection);
4607
+ return { status: 'error', rejection };
4608
+ });
4609
+ recordCommitOutcome(this.#db, {
4610
+ clientCommitId,
4611
+ status: 'rejected',
4612
+ recordedAtMs: this.#now(),
4613
+ results,
4614
+ operations: commit.operations,
4615
+ });
4616
+ }
4617
+ if (doomed.length > 0) {
4618
+ pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4619
+ batch.status();
4620
+ batch.rejections();
4621
+ batch.outcomes();
4622
+ }
4623
+ this.#replayOutbox(scope);
4624
+ this.#deleteUnreferencedBlobs();
4625
+ return true;
4626
+ }
4627
+ catch (error) {
4628
+ if (error instanceof ClientSyncError &&
4629
+ error.code === 'sync.scope_revoked')
4630
+ return false;
4631
+ throw error;
4632
+ }
4576
4633
  }
4577
4634
  // -- optimistic state ----------------------------------------------------------
4578
4635
  #captureBeforeImage(operation, opIndex) {
@@ -4596,8 +4653,10 @@ export class SyncClient {
4596
4653
  }
4597
4654
  return { opIndex, existed: true, syncVersion, values };
4598
4655
  }
4656
+ /** `onlyKeys` holds overlay row keys (`JSON [table,rowId]`). */
4599
4657
  #captureBeforeImages(operations, onlyKeys) {
4600
- return operations.flatMap((operation, opIndex) => onlyKeys && !onlyKeys.has(`${operation.table}\u0000${operation.rowId}`)
4658
+ return operations.flatMap((operation, opIndex) => onlyKeys &&
4659
+ !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
4601
4660
  ? []
4602
4661
  : [this.#captureBeforeImage(operation, opIndex)]);
4603
4662
  }
@@ -4634,11 +4693,11 @@ export class SyncClient {
4634
4693
  const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
4635
4694
  const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
4636
4695
  const complete = commit.operations.every((_, index) => imageByIndex.has(index));
4637
- const affectedKeys = new Set(commit.operations.map((operation) => `${operation.table}\u0000${operation.rowId}`));
4696
+ const affectedKeys = new Set(commit.operations.map((operation) => JSON.stringify([operation.table, operation.rowId])));
4638
4697
  if (complete) {
4639
4698
  const restored = new Set();
4640
4699
  commit.operations.forEach((operation, index) => {
4641
- const key = `${operation.table}\u0000${operation.rowId}`;
4700
+ const key = JSON.stringify([operation.table, operation.rowId]);
4642
4701
  if (restored.has(key))
4643
4702
  return;
4644
4703
  const image = imageByIndex.get(index);
@@ -4655,13 +4714,13 @@ export class SyncClient {
4655
4714
  deleteOutboxCommit(this.#db, commit.clientCommitId);
4656
4715
  if (!complete)
4657
4716
  return;
4658
- for (const later of listOutbox(this.#db)) {
4717
+ for (const later of listOutbox(this.#db, [...affectedKeys])) {
4659
4718
  if (later.seq <= commit.seq)
4660
4719
  continue;
4661
- const affectedOperations = later.operations.filter((operation) => affectedKeys.has(`${operation.table}\u0000${operation.rowId}`));
4720
+ const affectedOperations = later.operations.filter((operation) => affectedKeys.has(JSON.stringify([operation.table, operation.rowId])));
4662
4721
  if (affectedOperations.length === 0)
4663
4722
  continue;
4664
- replaceOutboxBeforeImages(this.#db, later.clientCommitId, this.#captureBeforeImages(later.operations, affectedKeys));
4723
+ replaceOutboxBeforeImages(this.#db, later, this.#captureBeforeImages(later.operations, affectedKeys));
4665
4724
  // §7.4.4: a later commit the recovery already classified refused never
4666
4725
  // replays. Its before-image is still rebased above, so dropping it later
4667
4726
  // restores the same base this rollback just restored.
@@ -4795,26 +4854,30 @@ export class SyncClient {
4795
4854
  type: localColumnType(column),
4796
4855
  }));
4797
4856
  const sparse = [];
4798
- for (const column of table.columns) {
4799
- const raw = values[column.name];
4857
+ for (const { name, type } of declared) {
4858
+ const raw = values[name];
4800
4859
  if (raw === undefined) {
4801
4860
  sparse.push(undefined);
4802
4861
  continue;
4803
4862
  }
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' &&
4863
+ // §2.4/§7.1: authoring refuses the push admission values the server
4864
+ // rejects. JSON would also turn NaN and ±Infinity into null, so the
4865
+ // outbox never records a different value.
4866
+ if ((type === 'float' &&
4809
4867
  typeof raw === 'number' &&
4810
- !Number.isFinite(raw))
4811
- return `column ${column.name} (float) requires a finite number value`;
4868
+ !Number.isFinite(raw)) ||
4869
+ (type === 'string' && typeof raw === 'string' && raw.includes('\0')))
4870
+ return `column ${name} holds a value push admission rejects`;
4812
4871
  try {
4872
+ if (typeof raw === 'string' && type === 'json')
4873
+ parseJsonDocument(raw, 'json value');
4874
+ if (typeof raw === 'string' && type === 'blob_ref')
4875
+ parseBlobRef(raw);
4813
4876
  sparse.push(jsonToRowValue(raw));
4814
4877
  }
4815
4878
  catch (error) {
4816
- if (error instanceof ClientSyncError)
4817
- return `column ${column.name}: ${error.message}`;
4879
+ if (error instanceof ClientSyncError || error instanceof DecodeError)
4880
+ return `column ${name}: ${error.message}`;
4818
4881
  throw error;
4819
4882
  }
4820
4883
  }
@@ -4870,14 +4933,23 @@ export class SyncClient {
4870
4933
  if (restoreBases)
4871
4934
  restoreFailedBases(this.#db, this.#schema, scope);
4872
4935
  const acknowledged = failedOverlayCommits(this.#db, true, scope, this.#schema);
4936
+ const outbox = new Set(listOutbox(this.#db, scope));
4873
4937
  const pending = [
4874
4938
  ...failedOverlayCommits(this.#db, false, scope, this.#schema),
4875
- ...listOutbox(this.#db, scope),
4939
+ ...outbox,
4876
4940
  ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
4877
- for (const commit of [...acknowledged, ...pending])
4941
+ // §7.2: a caller that restored the bases itself has just written the
4942
+ // server base of every exact-key row in scope. Each pending commit's
4943
+ // before-image of such a row is re-taken right before the commit
4944
+ // replays, so a later rollback restores that base plus earlier intent.
4945
+ const rebased = restoreBases || scope === undefined ? undefined : new Set(scope);
4946
+ for (const commit of [...acknowledged, ...pending]) {
4947
+ if (rebased !== undefined && outbox.has(commit))
4948
+ replaceOutboxBeforeImages(this.#db, commit, this.#captureBeforeImages(commit.operations, rebased));
4878
4949
  this.#applyOperationsLocally(commit.operations.filter((op) => scope === undefined ||
4879
4950
  scope.includes(JSON.stringify([op.table, op.rowId])) ||
4880
4951
  scope.includes(JSON.stringify([op.table]))), batch, true);
4952
+ }
4881
4953
  };
4882
4954
  const priorRejections = [...this.#rejections];
4883
4955
  try {