@syncular/client 0.59.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 (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +10 -4
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +11 -11
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +13 -8
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +13 -16
  66. package/src/worker-protocol.ts +8 -8
package/dist/client.js CHANGED
@@ -14,12 +14,12 @@ 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, parseJsonDocument, 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
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';
22
+ import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
23
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';
@@ -29,9 +29,9 @@ import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, }
29
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
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
- 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';
33
- import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, saveSubscriptionScopeSchema, resetSubscriptionsForBump, saveSubscription, setMeta, SUBSCRIPTIONS_TABLE, } from './state.js';
34
- 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';
35
35
  /** Stable client-local error while protected operations are preflight-gated. */
36
36
  export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
37
37
  /**
@@ -84,7 +84,7 @@ function emptySummary(pushed) {
84
84
  };
85
85
  }
86
86
  const LOG_EPOCH_META_KEY = 'logEpoch';
87
- /** §7.7: one `syncUntilIdle` drive's default total deadline. */
87
+ /** §7.8: one `syncUntilIdle` drive's default total deadline. */
88
88
  const SYNC_IDLE_TIMEOUT_MS = 60_000;
89
89
  /** RFC 0005 defaults (D2/A4/D7). */
90
90
  const PREVIOUS_VERSION_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
@@ -92,7 +92,7 @@ const PREVIOUS_VERSION_DEFAULT_MAX_ROWS = 20_000;
92
92
  const PREVIOUS_VERSION_DEFAULT_MAX_TABLES = 32;
93
93
  const PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES = 1024 * 1024;
94
94
  const PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
95
- /** §7.7: an explicit round budget is a strict positive u32 count. */
95
+ /** §7.8: an explicit round budget is a strict positive u32 count. */
96
96
  function requireRoundBudget(maxRounds) {
97
97
  if (maxRounds !== undefined &&
98
98
  (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff))
@@ -152,7 +152,7 @@ export class SyncClient {
152
152
  #securityEpoch = 0;
153
153
  #transportEnabled;
154
154
  #transportEpoch = 0;
155
- #subscriptionEpoch = 0;
155
+ #registrationEpoch = 0;
156
156
  #now;
157
157
  #outcomeRetentionMaxEntries;
158
158
  #retainFailedCommits;
@@ -348,7 +348,6 @@ export class SyncClient {
348
348
  // BUSY/BUSY_SNAPSHOT), and one upgraded before the read refuses with
349
349
  // `client.schema_downgrade`. The batch emits its change event only after
350
350
  // the commit. The onUpgrading callback still reports reset intent.
351
- let subscriptions;
352
351
  try {
353
352
  this.#applyBatch(() => {
354
353
  // §7.4.1/§7.4.2: this is the transaction's first read, so it pins the
@@ -442,7 +441,7 @@ export class SyncClient {
442
441
  this.#reconcilePreviousVersionAtBoot();
443
442
  // A registration remains app intent only while its table exists in the
444
443
  // running schema. Removed-table registrations would poison every pull.
445
- subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema);
444
+ pruneUnknownUnits(this.#db, this.#schema);
446
445
  });
447
446
  }
448
447
  catch (error) {
@@ -461,7 +460,7 @@ export class SyncClient {
461
460
  (countOutbox(this.#db) > 0 ||
462
461
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
463
462
  loadPendingEvictions(this.#db).length > 0 ||
464
- subscriptions.some((sub) => sub.status === 'active'));
463
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
465
464
  if (startupWork && this.#securityLifecycle === 'active') {
466
465
  this.#needsPull = true;
467
466
  this.#emitSyncNeeded('startup');
@@ -474,7 +473,7 @@ export class SyncClient {
474
473
  clientId: () => this.#clientId,
475
474
  role: () => 'direct',
476
475
  outbox: async () => this.pendingCommits().length,
477
- subscriptions: async () => this.subscriptions(),
476
+ units: async () => this.units(),
478
477
  conflicts: async () => this.conflicts().length,
479
478
  rejections: async () => this.rejections().length,
480
479
  syncNeeded: async () => this.statusSnapshot().syncNeeded,
@@ -498,7 +497,7 @@ export class SyncClient {
498
497
  ensureLocalSyncedSchema(this.#db, this.#schema);
499
498
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
500
499
  setLocalSchemaDescriptor(this.#db, this.#schema);
501
- saveSubscriptionScopeSchema(this.#db, this.#schema);
500
+ saveUnitScopeSchema(this.#db, this.#schema);
502
501
  });
503
502
  return;
504
503
  }
@@ -509,7 +508,7 @@ export class SyncClient {
509
508
  this.#db.transaction(() => {
510
509
  ensureLocalSyncedSchema(this.#db, this.#schema);
511
510
  setLocalSchemaDescriptor(this.#db, this.#schema);
512
- saveSubscriptionScopeSchema(this.#db, this.#schema);
511
+ saveUnitScopeSchema(this.#db, this.#schema);
513
512
  });
514
513
  return;
515
514
  }
@@ -537,14 +536,14 @@ export class SyncClient {
537
536
  if (this.#previousVersion !== undefined) {
538
537
  writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
539
538
  }
540
- pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), this.#schema, true);
539
+ pruneUnknownUnits(this.#db, this.#schema, true);
541
540
  this.#discardAcknowledgedRows();
542
541
  dropAndRecreateSyncedTables(this.#db, this.#schema);
543
- resetSubscriptionsForBump(this.#db);
542
+ resetUnits(this.#db);
544
543
  this.#replayOutbox();
545
544
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
546
545
  setLocalSchemaDescriptor(this.#db, this.#schema);
547
- saveSubscriptionScopeSchema(this.#db, this.#schema);
546
+ saveUnitScopeSchema(this.#db, this.#schema);
548
547
  });
549
548
  // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
550
549
  for (const table of this.#schema.tables.values())
@@ -619,7 +618,7 @@ export class SyncClient {
619
618
  this.#emitSyncIntent({ kind: 'interactive' });
620
619
  return [];
621
620
  }
622
- const subscriptions = loadSubscriptions(this.#db);
621
+ const units = loadUnits(this.#db);
623
622
  this.#setUpgrading(true);
624
623
  // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
625
624
  // orphan sweep but captures no new shadow.
@@ -629,7 +628,7 @@ export class SyncClient {
629
628
  this.#db.transaction(() => {
630
629
  this.#discardAcknowledgedRows();
631
630
  dropAndRecreateSyncedTables(this.#db, this.#schema);
632
- resetSubscriptionsForBump(this.#db);
631
+ resetUnits(this.#db);
633
632
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
634
633
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
635
634
  // transaction before they replay, so the reset boundary never fails on
@@ -652,7 +651,7 @@ export class SyncClient {
652
651
  this.#setSyncNeeded(true);
653
652
  this.#emitSyncNeeded('startup');
654
653
  this.#emitSyncIntent({ kind: 'interactive' });
655
- return subscriptions.map((subscription) => subscription.id);
654
+ return units.map((unit) => unit.id);
656
655
  }
657
656
  #setUpgrading(upgrading) {
658
657
  if (this.#upgrading === upgrading)
@@ -799,7 +798,7 @@ export class SyncClient {
799
798
  (countOutbox(this.#db) > 0 ||
800
799
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`).length > 0 ||
801
800
  loadPendingEvictions(this.#db).length > 0 ||
802
- loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
801
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
803
802
  if (startupWork) {
804
803
  this.#setSyncNeeded(true);
805
804
  this.#emitSyncNeeded('startup');
@@ -886,10 +885,9 @@ export class SyncClient {
886
885
  snapshotRead(spec) {
887
886
  return this.#readSnapshot(spec);
888
887
  }
889
- /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
890
- subscriptionCatchup(id) {
891
- return this.#readSnapshot({ statements: [], subscriptions: [id] })
892
- .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];
893
891
  }
894
892
  /** §7.5: one client commit's delivery status: pending, its retained outcome,
895
893
  * or an explicit unknown (never held, or pruned by retention). */
@@ -899,7 +897,7 @@ export class SyncClient {
899
897
  }
900
898
  /**
901
899
  * §7.5: the one atomic read primitive. Every public read (`querySnapshot`,
902
- * `snapshotRead`, `subscriptionCatchup`, `commitDelivery`) enters here, so
900
+ * `snapshotRead`, `unitCatchup`, `commitDelivery`) enters here, so
903
901
  * the read-only guard, transaction, revision, coverage, catch-up, delivery,
904
902
  * and owner-failure observation exist once.
905
903
  */
@@ -907,60 +905,25 @@ export class SyncClient {
907
905
  this.#requireActive();
908
906
  const owner = request.owner;
909
907
  const catchupOf = (id) => {
910
- function corrupt() {
911
- throw new ClientSyncError('sync.local_corrupt', 'persisted subscription state is invalid');
912
- }
913
- const row = this.#db.query(`SELECT tbl,status,cursor,bootstrap_state,effective_scopes,reason_code FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id])[0];
914
- if (row === undefined)
908
+ const unit = getUnit(this.#db, id);
909
+ if (unit === undefined)
915
910
  return { state: 'unknown', id };
916
- const table = row.tbl;
917
- const status = row.status;
918
- const cursor = row.cursor;
919
- if (typeof table !== 'string' ||
920
- (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
921
- typeof cursor !== 'number' ||
922
- !Number.isSafeInteger(cursor)) {
923
- corrupt();
924
- }
925
- const token = row.bootstrap_state;
926
- if (token !== null && typeof token !== 'string')
927
- corrupt();
928
- const rawScopes = row.effective_scopes;
929
- let effectiveScopes;
930
- if (rawScopes !== null) {
931
- if (typeof rawScopes !== 'string')
932
- corrupt();
933
- try {
934
- effectiveScopes = JSON.parse(rawScopes);
935
- if (effectiveScopes === null)
936
- effectiveScopes = undefined;
937
- else if (typeof effectiveScopes !== 'object' ||
938
- Array.isArray(effectiveScopes) ||
939
- !Object.values(effectiveScopes).every((values) => Array.isArray(values) &&
940
- values.every((value) => typeof value === 'string')))
941
- corrupt();
942
- }
943
- catch {
944
- corrupt();
945
- }
946
- }
947
- const reasonCode = row.reason_code;
948
- if (reasonCode !== null && typeof reasonCode !== 'string')
949
- corrupt();
950
- const active = status === 'active';
951
- const hasResumeToken = token !== null;
952
- 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({
953
917
  state: 'known',
954
918
  id,
955
- table,
956
- status,
919
+ status: unit.status,
920
+ live: unit.cursor === undefined,
957
921
  cursor,
958
- hasResumeToken,
959
- bootstrapComplete: active && cursor >= 0 && !hasResumeToken,
960
- knownPendingPages: active && (hasResumeToken || cursor < 0),
961
- ...(effectiveScopes !== undefined ? { effectiveScopes } : {}),
962
- ...(reasonCode !== null ? { reasonCode } : {}),
963
- };
922
+ hasResumeToken: unit.bootstrapState !== undefined,
923
+ bootstrapComplete: active && !pending,
924
+ knownPendingPages: active && pending,
925
+ reasonCode: unit.reasonCode,
926
+ });
964
927
  };
965
928
  const deliveryOf = (id) => {
966
929
  const pending = this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [id]).length > 0;
@@ -997,7 +960,7 @@ export class SyncClient {
997
960
  pending,
998
961
  missing,
999
962
  },
1000
- subscriptions: (request.subscriptions ?? []).map(catchupOf),
963
+ units: (request.units ?? []).map(catchupOf),
1001
964
  deliveries: (request.commitIds ?? []).map(deliveryOf),
1002
965
  };
1003
966
  });
@@ -1058,7 +1021,7 @@ export class SyncClient {
1058
1021
  this.#discardPreviousVersion();
1059
1022
  return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1060
1023
  }
1061
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1024
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1062
1025
  this.#discardPreviousVersion();
1063
1026
  return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1064
1027
  }
@@ -1148,16 +1111,13 @@ export class SyncClient {
1148
1111
  return lease?.expiresAtMs !== undefined && lease.expiresAtMs <= nowMs;
1149
1112
  }
1150
1113
  /**
1151
- * RFC 0005 D7: the §7.4.5 replacement-coverage predicate — every active
1152
- * subscription has `cursor >= 0` and no resume token. Window units own
1153
- * subscriptions, so their pendency is included. An empty active set is not
1154
- * 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.
1155
1117
  */
1156
1118
  #previousVersionCoverageComplete() {
1157
- const active = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
1158
- if (active.length === 0)
1159
- return false;
1160
- 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);
1161
1121
  }
1162
1122
  /**
1163
1123
  * Remove the container file and both metadata records. Returns whether
@@ -1192,7 +1152,7 @@ export class SyncClient {
1192
1152
  const record = this.#readPreviousVersionRecord();
1193
1153
  if (record === undefined)
1194
1154
  return;
1195
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1155
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1196
1156
  this.#discardPreviousVersion();
1197
1157
  return;
1198
1158
  }
@@ -1272,89 +1232,38 @@ export class SyncClient {
1272
1232
  * One atomic support/product-health view. It never returns scope values,
1273
1233
  * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
1274
1234
  */
1275
- diagnosticsSnapshot(request = {}) {
1235
+ diagnosticsSnapshot() {
1276
1236
  this.#requireActive();
1277
- const expected = request.expectedSubscriptions ?? [];
1278
- if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
1279
- throw invalidRequest(`diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`);
1280
- }
1281
- const registered = loadSubscriptions(this.#db);
1282
- const subscriptions = new Map();
1283
- for (const sub of registered) {
1284
- const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
1285
- const complete = sub.status === 'active' &&
1286
- sub.cursor >= 0 &&
1287
- sub.bootstrapState === undefined;
1288
- subscriptions.set(sub.id, {
1289
- id: sub.id,
1290
- table: sub.table,
1291
- state: sub.status === 'revoked'
1292
- ? 'revoked'
1293
- : sub.status === 'failed'
1294
- ? 'failed'
1295
- : reset
1296
- ? 'reset'
1297
- : complete
1298
- ? 'complete'
1299
- : 'bootstrapping',
1300
- complete,
1301
- cursor: sub.cursor,
1302
- ...(sub.reasonCode !== undefined
1303
- ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
1304
- : {}),
1305
- });
1306
- }
1307
- for (const item of expected) {
1308
- if (typeof item.id !== 'string' ||
1309
- item.id.length === 0 ||
1310
- typeof item.table !== 'string' ||
1311
- item.table.length === 0) {
1312
- throw invalidRequest('diagnosticsSnapshot needs subscription id and table');
1313
- }
1314
- const registeredSubscription = subscriptions.get(item.id);
1315
- if (registeredSubscription !== undefined &&
1316
- registeredSubscription.table !== item.table) {
1317
- subscriptions.set(item.id, {
1318
- id: item.id,
1319
- table: item.table,
1320
- state: 'failed',
1321
- complete: false,
1322
- reasonCode: 'client.subscription_intent_mismatch',
1323
- });
1324
- }
1325
- else if (registeredSubscription === undefined) {
1326
- subscriptions.set(item.id, {
1327
- id: item.id,
1328
- table: item.table,
1329
- state: 'unregistered',
1330
- complete: false,
1331
- });
1332
- }
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;
1333
1253
  }
1334
1254
  const capturedAtMs = this.#now();
1335
1255
  const leaseState = this.#diagnosticLease(capturedAtMs);
1256
+ const round = this.#lastRound;
1336
1257
  const connectivity = !this.#transportEnabled
1337
1258
  ? 'offline'
1338
- : this.#lastRound?.status === 'succeeded'
1259
+ : round?.status === 'succeeded'
1339
1260
  ? 'online'
1340
- : this.#lastRound?.status === 'failed' &&
1341
- (this.#lastRound.causeKind === 'network' ||
1342
- this.#lastRound.causeKind === 'connect')
1261
+ : round?.status === 'failed' &&
1262
+ (round.causeKind === 'network' || round.causeKind === 'connect')
1343
1263
  ? 'offline'
1344
- : this.#lastRound?.status === 'failed' &&
1345
- this.#lastRound.httpStatus !== undefined
1264
+ : round?.status === 'failed' && round.httpStatus !== undefined
1346
1265
  ? 'online'
1347
1266
  : 'unknown';
1348
- const expectedOrder = new Map(expected.map((item, index) => [item.id, index]));
1349
- const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
1350
- const aExpected = expectedOrder.get(a.id);
1351
- const bExpected = expectedOrder.get(b.id);
1352
- if (aExpected !== undefined || bExpected !== undefined) {
1353
- return ((aExpected ?? Number.MAX_SAFE_INTEGER) -
1354
- (bExpected ?? Number.MAX_SAFE_INTEGER));
1355
- }
1356
- return a.id.localeCompare(b.id);
1357
- });
1358
1267
  return definedObject({
1359
1268
  version: CLIENT_DIAGNOSTICS_VERSION,
1360
1269
  capturedAtMs,
@@ -1380,8 +1289,16 @@ export class SyncClient {
1380
1289
  pendingOutbox: countOutbox(this.#db),
1381
1290
  },
1382
1291
  lease: leaseState,
1383
- subscriptions: allSubscriptions.slice(0, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS),
1384
- 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),
1385
1302
  lastRound: this.#lastRound,
1386
1303
  lastChange: this.#lastChange,
1387
1304
  storage: this.#diagnosticStorage(),
@@ -1408,8 +1325,9 @@ export class SyncClient {
1408
1325
  try {
1409
1326
  const pageCount = Number(this.#db.query('PRAGMA page_count')[0]?.page_count ?? 0);
1410
1327
  const pageSize = Number(this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0);
1411
- const outboxBytes = Number(this.#db.query(`SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`)[0]?.bytes ?? 0);
1412
- 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];
1413
1331
  const blobBytes = this.#hasBlobs
1414
1332
  ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
1415
1333
  : 0;
@@ -1418,9 +1336,9 @@ export class SyncClient {
1418
1336
  return {
1419
1337
  status: pressure ? 'pressure' : 'healthy',
1420
1338
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
1421
- pendingOutboxBytesApprox: Math.max(0, outboxBytes),
1422
- retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
1423
- 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)),
1424
1342
  blobCacheBytesApprox: Math.max(0, blobBytes),
1425
1343
  ...(pressure
1426
1344
  ? { pressureReasonCode: 'client.blob_cache_over_limit' }
@@ -1513,7 +1431,9 @@ export class SyncClient {
1513
1431
  if (revision !== undefined) {
1514
1432
  const event = batch.finish(revision, status);
1515
1433
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
1516
- 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
+ ];
1517
1437
  this.#lastChange = {
1518
1438
  revision: revision.toString(),
1519
1439
  recordedAtMs: this.#now(),
@@ -1739,7 +1659,7 @@ export class SyncClient {
1739
1659
  if (grant.urlExpiresAtMs === undefined ||
1740
1660
  grant.urlExpiresAtMs > this.#now()) {
1741
1661
  try {
1742
- await transport.uploadToUrl(grant.url, bytes, mediaType, signal);
1662
+ await transport.uploadToUrl(blobId, grant.url, bytes, mediaType, signal);
1743
1663
  return;
1744
1664
  }
1745
1665
  catch {
@@ -1793,11 +1713,11 @@ export class SyncClient {
1793
1713
  if (!this.#transportEnabled)
1794
1714
  return { proven: false, reason: 'offline' };
1795
1715
  const epoch = this.#transportEpoch;
1796
- const subscriptionEpoch = this.#subscriptionEpoch;
1716
+ const registrationEpoch = this.#registrationEpoch;
1797
1717
  const securityEpoch = this.#securityEpoch;
1798
1718
  let before;
1799
1719
  try {
1800
- before = loadSubscriptions(this.#db);
1720
+ before = loadUnits(this.#db);
1801
1721
  }
1802
1722
  catch {
1803
1723
  return { proven: false, reason: 'snapshot_failed' };
@@ -1811,14 +1731,14 @@ export class SyncClient {
1811
1731
  proven: false,
1812
1732
  reason: !this.#transportEnabled || epoch !== this.#transportEpoch
1813
1733
  ? 'offline'
1814
- : subscriptionEpoch !== this.#subscriptionEpoch
1734
+ : registrationEpoch !== this.#registrationEpoch
1815
1735
  ? 'missing_coverage'
1816
1736
  : 'sync_failed',
1817
1737
  };
1818
1738
  }
1819
1739
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
1820
1740
  return { proven: false, reason: 'offline' };
1821
- if (subscriptionEpoch !== this.#subscriptionEpoch)
1741
+ if (registrationEpoch !== this.#registrationEpoch)
1822
1742
  return { proven: false, reason: 'missing_coverage' };
1823
1743
  if (this.#securityLifecycle !== 'active' ||
1824
1744
  securityEpoch !== this.#securityEpoch)
@@ -1831,7 +1751,7 @@ export class SyncClient {
1831
1751
  return this.#db.transaction(() => {
1832
1752
  const snapshot = this.#readSnapshot({
1833
1753
  statements: [],
1834
- subscriptions: before.map((sub) => sub.id),
1754
+ units: before.map((unit) => unit.id),
1835
1755
  commitIds: [clientCommitId],
1836
1756
  });
1837
1757
  const delivery = snapshot.deliveries[0];
@@ -1841,21 +1761,15 @@ export class SyncClient {
1841
1761
  proven: false,
1842
1762
  reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
1843
1763
  };
1844
- const after = new Map(loadSubscriptions(this.#db).map((sub) => [sub.id, sub]));
1845
- 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.
1846
1770
  const candidates = before.flatMap((previous) => {
1847
- const sub = after.get(previous.id);
1848
- const state = states.get(previous.id);
1849
- return sub !== undefined &&
1850
- sub.table === previous.table &&
1851
- sub.params === previous.params &&
1852
- canonicalScopeJson(sub.scopes) ===
1853
- canonicalScopeJson(previous.scopes) &&
1854
- sub.effectiveScopes !== undefined &&
1855
- state?.state === 'known' &&
1856
- state.bootstrapComplete
1857
- ? [{ table: sub.table, scopes: sub.effectiveScopes }]
1858
- : [];
1771
+ const unit = after.get(previous.id);
1772
+ return unit !== undefined && complete.has(unit.id) ? [unit] : [];
1859
1773
  });
1860
1774
  const covered = (tableName, row) => {
1861
1775
  const table = this.#schema.tables.get(tableName);
@@ -1865,16 +1779,19 @@ export class SyncClient {
1865
1779
  key,
1866
1780
  rowValueToJson(value),
1867
1781
  ]));
1868
- return candidates.some((candidate) => {
1869
- return (candidate.table === tableName &&
1870
- 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) => {
1871
1788
  const column = table.scopeColumnByVariable.get(variable);
1872
1789
  const value = column === undefined ? undefined : row[column];
1873
1790
  return ((typeof value === 'string' && value.length > 0) ||
1874
1791
  typeof value === 'number' ||
1875
1792
  typeof value === 'boolean');
1876
1793
  }) &&
1877
- matchesLocalScopes(table, candidate.scopes, values));
1794
+ matchesLocalScopes(table, scopes, values));
1878
1795
  });
1879
1796
  };
1880
1797
  for (const row of current.retainedRows) {
@@ -2028,94 +1945,105 @@ export class SyncClient {
2028
1945
  : 0) |
2029
1946
  (urlCapable ? ACCEPT_SIGNED_URLS : 0));
2030
1947
  }
2031
- subscriptions() {
1948
+ /** Every unit in registration order (§4.1), including revoked and failed. */
1949
+ units() {
2032
1950
  this.#requireActive();
2033
- return loadSubscriptions(this.#db);
1951
+ return loadUnits(this.#db);
2034
1952
  }
2035
- subscription(id) {
1953
+ unit(id) {
2036
1954
  this.#requireActive();
2037
- return getSubscription(this.#db, id);
1955
+ return getUnit(this.#db, id);
2038
1956
  }
2039
1957
  pendingCommits() {
2040
1958
  this.#requireActive();
2041
1959
  return listOutbox(this.#db);
2042
1960
  }
2043
- // -- subscriptions ----------------------------------------------------------
2044
- subscribe(input) {
2045
- 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];
2046
1965
  }
2047
1966
  /**
2048
- * Register several subscriptions in one local transaction: the same rules
2049
- * as `subscribe` for each input, and one commit for all of them (on OPFS a
2050
- * commit costs milliseconds, so a cold start with hundreds of
2051
- * registrations pays it once). An error rolls back every registration of
2052
- * 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).
2053
1972
  */
2054
- subscribeMany(inputs) {
1973
+ subscribeMany(units) {
2055
1974
  this.#requireActive();
2056
1975
  let registered = false;
2057
- this.#db.transaction(() => {
2058
- for (const input of inputs) {
2059
- if (!this.#schema.tables.has(input.table)) {
2060
- throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
2061
- }
2062
- const existing = getSubscription(this.#db, input.id);
2063
- if (existing !== undefined) {
2064
- const sameIntent = existing.table === input.table &&
2065
- canonicalScopeJson(existing.scopes) ===
2066
- canonicalScopeJson(input.scopes) &&
2067
- existing.params === input.params;
2068
- if (!sameIntent) {
2069
- throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
2070
- }
2071
- // §3.3: a revoked registration keeps its id and intent but no
2072
- // progress. Subscribing again with the same intent re-arms it, so
2073
- // the next pull resolves its scopes from scratch. A `failed`
2074
- // registration is a configuration error and stays put.
2075
- if (existing.status !== 'revoked')
2076
- continue;
2077
- }
2078
- saveSubscription(this.#db, definedObject({
2079
- id: input.id,
2080
- table: input.table,
2081
- scopes: input.scopes,
2082
- params: input.params,
2083
- cursor: -1,
2084
- status: 'active',
2085
- }));
2086
- registered = true;
2087
- }
2088
- });
2089
- if (!registered)
2090
- return;
2091
- this.#subscriptionEpoch += 1;
2092
- this.#setSyncNeeded(true);
2093
- this.#emitSyncIntent({ kind: 'interactive' });
2094
- 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;
2095
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
+ */
2096
1993
  unsubscribe(id) {
2097
1994
  this.#requireActive();
2098
- 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')
2099
2005
  return;
2100
- deleteSubscription(this.#db, id);
2101
- this.#subscriptionEpoch += 1;
2102
2006
  this.#setSyncNeeded(true);
2103
2007
  this.#emitSyncIntent({ kind: 'interactive' });
2104
2008
  this.#emitDiagnostics();
2105
2009
  }
2106
- // -- windowed subscriptions (§4.8) ------------------------------------------
2107
2010
  /**
2108
- * Set the live window units for a base (§4.8): a value-sharded family of
2109
- * subscriptions, one per unit. Computes the diff against the registry —
2110
- * added units get fresh subscriptions (image-lane bootstrap on the next
2111
- * sync); removed units are unsubscribed with their first eviction chunk
2112
- * in one local transaction (E1–E4). Idempotent: calling with the same units is a
2113
- * no-op. Re-entry (a unit removed then re-added) cancels any deferred
2114
- * eviction and fresh-bootstraps.
2115
- *
2116
- * The change takes effect on the next `sync()`/socket round — the pull's
2117
- * subscription list (now with the added unit, without the removed one)
2118
- * 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).
2119
2047
  */
2120
2048
  async setWindow(base, units) {
2121
2049
  await this.setWindowCommand(base, units);
@@ -2123,127 +2051,105 @@ export class SyncClient {
2123
2051
  /** Exact core command result consumed by automatic host loops (§7.5). */
2124
2052
  async setWindowCommand(base, units) {
2125
2053
  this.#requireActive();
2126
- const table = this.#table(base.table);
2127
- if (!table.scopeColumnByVariable.has(base.variable)) {
2128
- throw invalidRequest(`${base.table}: unknown scope variable ${base.variable} (§4.8)`);
2129
- }
2130
- // Serialize the whole window edit: it spans an `await deriveSubId` between
2131
- // db transactions, so without the chain a delta apply (or a concurrent
2132
- // setWindow) could interleave its transactions and corrupt the registry.
2133
2054
  let changed = false;
2134
- 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.
2135
2057
  await this.#serialize(async () => {
2136
2058
  const baseKey = windowBaseKey(base);
2137
2059
  const wanted = new Set(units);
2138
2060
  const live = loadWindowUnits(this.#db, baseKey);
2139
- const liveByUnit = new Map(live.map((u) => [u.unit, u.subId]));
2140
- // Widen: units wanted but not live → fresh subscription + registry row.
2141
- for (const unit of wanted) {
2142
- 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))
2143
2064
  continue;
2144
- const subId = await deriveSubId(base, unit);
2145
2065
  this.#applyBatch((batch) => {
2146
- this.#db.transaction(() => {
2147
- // Re-entry cancels any deferred eviction for this sub id.
2148
- deletePendingEviction(this.#db, subId);
2149
- insertWindowUnit(this.#db, baseKey, unit, subId);
2150
- saveSubscription(this.#db, definedObject({
2151
- id: subId,
2152
- table: base.table,
2153
- scopes: unitScopes(base, unit),
2154
- params: base.params,
2155
- cursor: -1,
2156
- status: 'active',
2157
- }));
2158
- });
2159
- this.#needsPull = true;
2160
- 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);
2161
2071
  batch.status();
2162
2072
  });
2163
2073
  changed = true;
2164
- widened = true;
2165
- this.#subscriptionEpoch += 1;
2074
+ this.#registrationEpoch += 1;
2166
2075
  }
2167
- // Shrink: units live but not wanted → unsubscribe fused with eviction.
2168
- for (const { unit, subId } of live) {
2169
- if (wanted.has(unit))
2076
+ for (const { value, unitId: id } of live) {
2077
+ if (wanted.has(value))
2170
2078
  continue;
2171
- await this.#evictUnit(baseKey, base, unit, subId);
2079
+ await this.#releaseWindowUnit(baseKey, value, id);
2172
2080
  changed = true;
2173
- this.#subscriptionEpoch += 1;
2081
+ this.#registrationEpoch += 1;
2174
2082
  }
2175
2083
  });
2176
2084
  const effects = {
2177
- sync: this.#transportEnabled && (changed || widened)
2085
+ sync: this.#transportEnabled && changed
2178
2086
  ? { kind: 'interactive' }
2179
2087
  : { kind: 'none' },
2180
2088
  };
2181
- if (effects.sync.kind === 'interactive') {
2089
+ if (effects.sync.kind === 'interactive')
2182
2090
  this.#emitSyncIntent(effects.sync);
2183
- }
2184
2091
  return { value: undefined, effects };
2185
2092
  }
2186
2093
  /**
2187
- * The completeness oracle (§4.8 I3): which units of a base are windowed-in
2188
- * locally, which of those are still bootstrap-pending, and thereby the
2189
- * per-unit verdict a live query renders "may be partial" from. A query
2190
- * whose scope footprint includes an un-windowed OR still-pending unit is
2191
- * NOT answerable in full — the host widens or shows partial, never
2192
- * silently-complete. Registration alone is not completeness: a unit is
2193
- * pending until its subscription completes a bootstrap round (cursor
2194
- * 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.
2195
2098
  */
2196
2099
  windowState(base) {
2197
2100
  this.#requireActive();
2198
- const baseKey = windowBaseKey(base);
2199
- const live = loadWindowUnits(this.#db, baseKey);
2200
- const pending = [];
2201
- for (const { unit, subId } of live) {
2202
- const sub = getSubscription(this.#db, subId);
2203
- if (sub === undefined ||
2204
- sub.status !== 'active' ||
2205
- sub.cursor < 0 ||
2206
- sub.bootstrapState !== undefined) {
2207
- pending.push(unit);
2208
- }
2209
- }
2210
- 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 };
2211
2111
  }
2212
2112
  /**
2213
- * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
2214
- * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
2215
- * pending outbox commit (E1); if any pin remains, records a deferred
2216
- * eviction retried on the next outbox drain. Discards the subscription's
2217
- * cursor/resume/effective-echo (E3) and its version state with the rows
2218
- * (E2). Emits the evicted table's invalidation keys (I1). Fail-closed:
2219
- * with no local scope-column mapping, surfaces a configuration error and
2220
- * 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.
2221
2119
  */
2222
- async #evictUnit(baseKey, base, unit, subId) {
2223
- const table = this.#table(base.table);
2224
- const sub = getSubscription(this.#db, subId);
2225
- // The rows a unit holds live under its LAST effective scopes if it ever
2226
- // synced; before first sync, the requested unit scopes are the match.
2227
- const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
2228
- const pinned = this.#pinnedRowIds(base.table);
2120
+ async #releaseWindowUnit(baseKey, value, id) {
2229
2121
  let remaining = false;
2230
2122
  this.#applyBatch((batch) => {
2231
- this.#db.transaction(() => {
2232
- const result = evictScopedRows(this.#db, table, effective, this.#scopeOwners(base.table, subId), pinned);
2233
- remaining = result.remaining;
2234
- deleteWindowUnit(this.#db, baseKey, unit);
2235
- deleteSubscription(this.#db, subId);
2236
- if (result.deferred) {
2237
- savePendingEviction(this.#db, subId, base.table, effective);
2238
- }
2239
- else {
2240
- deletePendingEviction(this.#db, subId);
2241
- }
2242
- });
2243
- batch.scopeMap(table, effective);
2244
- batch.window(baseKey, table.name, unit);
2245
- 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);
2246
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
+ }
2247
2153
  });
2248
2154
  if (remaining) {
2249
2155
  await yieldToHost();
@@ -2251,32 +2157,28 @@ export class SyncClient {
2251
2157
  }
2252
2158
  }
2253
2159
  /**
2254
- * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
2255
- * unit's rows are removed once no pending commit references them; a unit
2256
- * 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.
2257
2162
  */
2258
2163
  async #drainPendingEvictions() {
2259
- const pending = loadPendingEvictions(this.#db);
2260
- if (pending.length === 0)
2261
- return;
2262
- for (const entry of pending) {
2164
+ for (const entry of loadPendingEvictions(this.#db)) {
2263
2165
  const table = this.#schema.tables.get(entry.table);
2264
2166
  if (table === undefined) {
2265
- deletePendingEviction(this.#db, entry.subId);
2167
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
2266
2168
  continue;
2267
2169
  }
2268
2170
  let remaining;
2269
2171
  do {
2270
- 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))
2271
2173
  break;
2272
- // Local writes may add pins while the worker yields between chunks.
2174
+ // Local writes may add pins while the host yields between chunks.
2273
2175
  const pinned = this.#pinnedRowIds(entry.table);
2274
2176
  remaining = false;
2275
2177
  this.#applyBatch((batch) => {
2276
- const result = evictScopedRows(this.#db, table, entry.effective, this.#scopeOwners(entry.table, entry.subId), pinned);
2178
+ const result = evictScopedRows(this.#db, table, entry.effective, unitOwners(loadUnits(this.#db), table, entry.unitId), pinned);
2277
2179
  remaining = result.remaining;
2278
2180
  if (!result.deferred)
2279
- deletePendingEviction(this.#db, entry.subId);
2181
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
2280
2182
  batch.scopeMap(table, entry.effective);
2281
2183
  });
2282
2184
  if (remaining)
@@ -2284,20 +2186,6 @@ export class SyncClient {
2284
2186
  } while (remaining);
2285
2187
  }
2286
2188
  }
2287
- /**
2288
- * §3.3/§4.8/§5.6 row ownership: the effective scopes of every other
2289
- * active subscription on `table` that holds rows (`cursor >= 0`). A
2290
- * scoped delete keeps every row one of them still covers.
2291
- */
2292
- #scopeOwners(table, exceptId) {
2293
- return loadSubscriptions(this.#db).flatMap((sub) => sub.id !== exceptId &&
2294
- sub.table === table &&
2295
- sub.status === 'active' &&
2296
- sub.cursor >= 0 &&
2297
- sub.effectiveScopes !== undefined
2298
- ? [sub.effectiveScopes]
2299
- : []);
2300
- }
2301
2189
  /**
2302
2190
  * §4.8 E1: primary keys of `table` referenced by any still-pending outbox
2303
2191
  * commit — rows that MUST NOT be evicted until the commit drains.
@@ -2664,7 +2552,7 @@ export class SyncClient {
2664
2552
  throw invalidRequest('local rebootstrap needs a schema-floor update');
2665
2553
  }
2666
2554
  const pending = listOutbox(this.#db);
2667
- const resetSubscriptions = loadSubscriptions(this.#db).length;
2555
+ const resetSubscriptions = loadUnits(this.#db).length;
2668
2556
  const priorUpgrading = this.#upgrading;
2669
2557
  const priorNeedsPull = this.#needsPull;
2670
2558
  try {
@@ -2674,7 +2562,7 @@ export class SyncClient {
2674
2562
  batch.status();
2675
2563
  this.#discardAcknowledgedRows();
2676
2564
  dropAndRecreateSyncedTables(this.#db, this.#schema);
2677
- resetSubscriptionsForBump(this.#db);
2565
+ resetUnits(this.#db);
2678
2566
  for (const table of this.#schema.tables.values()) {
2679
2567
  batch.table(table.name);
2680
2568
  }
@@ -2778,7 +2666,7 @@ export class SyncClient {
2778
2666
  // per-commit delta measured against the canonical encoder.
2779
2667
  const baseBytes = byteCap === undefined
2780
2668
  ? 0
2781
- : encodeMessage({
2669
+ : encodeRequest({
2782
2670
  wireVersion: PROTOCOL_WIRE_VERSION,
2783
2671
  msgKind: 'request',
2784
2672
  frames: [header, pull],
@@ -2851,7 +2739,7 @@ export class SyncClient {
2851
2739
  }
2852
2740
  const frame = byteCap === undefined
2853
2741
  ? 0
2854
- : encodeMessage({
2742
+ : encodeRequest({
2855
2743
  wireVersion: PROTOCOL_WIRE_VERSION,
2856
2744
  msgKind: 'request',
2857
2745
  frames: [header, pushFrame, pull],
@@ -2943,7 +2831,7 @@ export class SyncClient {
2943
2831
  sync() {
2944
2832
  return this.#sync();
2945
2833
  }
2946
- /** `signal` is the `syncUntilIdle` deadline (§7.7); `sync()` has none. */
2834
+ /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
2947
2835
  #sync(signal) {
2948
2836
  this.#requireActive();
2949
2837
  if (this.#syncOutstanding) {
@@ -3093,13 +2981,18 @@ export class SyncClient {
3093
2981
  clientId: this.#clientId,
3094
2982
  schemaVersion: this.#schema.version,
3095
2983
  logEpoch: logEpoch,
2984
+ outboxId: getMeta(this.#db, 'outboxId'),
3096
2985
  });
2986
+ // The registration fields are set after encoding (below).
3097
2987
  const pull = {
3098
2988
  type: 'PULL_HEADER',
3099
2989
  limitCommits: limits?.limitCommits ?? 0,
3100
2990
  limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
3101
2991
  maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
3102
2992
  accept: this.#acceptMask(),
2993
+ cursor: -1,
2994
+ registrationDigest: registrationDigest([]),
2995
+ echoDigest: new Uint8Array(),
3103
2996
  };
3104
2997
  const { pushFrames, outbox, frameBytes, deferred: encodedDeferred, } = logEpoch === undefined
3105
2998
  ? { pushFrames: [], outbox: [], frameBytes: [], deferred: 0 }
@@ -3123,7 +3016,14 @@ export class SyncClient {
3123
3016
  // encryption await must not make the final request exceed the byte
3124
3017
  // budget, and the reset epoch must be the one the response apply checks.
3125
3018
  const resetEpoch = this.#localResetEpoch;
3126
- 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);
3127
3027
  // §1.5: a kept round-failure code rides every request until a round
3128
3028
  // completes, immediately after REQ_HEADER.
3129
3029
  const report = this.#roundFailureCode;
@@ -3133,26 +3033,31 @@ export class SyncClient {
3133
3033
  ? [{ type: 'ROUND_FAILURE', code: report }]
3134
3034
  : []),
3135
3035
  pull,
3136
- ...subs.map((sub) => definedObject({
3137
- type: 'SUBSCRIPTION',
3138
- id: sub.id,
3139
- table: sub.table,
3140
- scopes: sub.scopes,
3141
- params: sub.params,
3142
- cursor: sub.cursor,
3143
- bootstrapState: sub.bootstrapState,
3144
- })),
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
+ ]),
3145
3050
  ];
3146
3051
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
3147
- // sit between them and the pull/subscription tail (§1.5 ordering).
3052
+ // sit between them and the pull/unit/progress tail (§1.5 ordering).
3148
3053
  const lead = fixedFrames.slice(0, report !== undefined ? 2 : 1);
3149
3054
  let admitted = pushFrames.length;
3150
3055
  let deferred = encodedDeferred;
3151
3056
  if (byteCap !== undefined) {
3152
3057
  // The fixed frames encode as envelope + fixed frames + END; each
3153
3058
  // admitted push frame adds its own (5 + payload). Trimming the tail
3154
- // re-fits the request to the final subscription state.
3155
- const fixedBytes = encodeMessage({
3059
+ // re-fits the request to the final registration state.
3060
+ const fixedBytes = encodeRequest({
3156
3061
  wireVersion: PROTOCOL_WIRE_VERSION,
3157
3062
  msgKind: 'request',
3158
3063
  frames: fixedFrames,
@@ -3178,19 +3083,16 @@ export class SyncClient {
3178
3083
  ...pushFrames,
3179
3084
  ...fixedFrames.slice(lead.length),
3180
3085
  ];
3181
- const requestBytes = encodeMessage({
3086
+ const requestBytes = encodeRequest({
3182
3087
  wireVersion: PROTOCOL_WIRE_VERSION,
3183
3088
  msgKind: 'request',
3184
3089
  frames,
3185
3090
  });
3186
3091
  const responseBytes = await this.#roundTrip(requestBytes, signal);
3187
- const message = decodeMessage(responseBytes);
3188
- if (message.msgKind !== 'response') {
3189
- throw invalidRequest('transport returned a non-response message');
3190
- }
3092
+ const message = decodeResponse(responseBytes);
3191
3093
  // §1.5: a complete, decodable response ends the report obligation.
3192
3094
  this.#roundFailureCode = undefined;
3193
- const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch, signal);
3095
+ const summary = await this.#processResponse(message, outbox, bytesToHex(pull.registrationDigest), 'pull', resetEpoch, signal);
3194
3096
  // §4.8 E1: the push half may have drained commits that pinned rows of
3195
3097
  // a shrunk window unit — retry any deferred evictions now.
3196
3098
  await this.#drainPendingEvictions();
@@ -3198,8 +3100,8 @@ export class SyncClient {
3198
3100
  ? { state: 'failed', errorCode: 'sync.scope_revoked' }
3199
3101
  : { state: 'complete' });
3200
3102
  this.#retryDelayMs = 250;
3201
- // §4.7: a subscription that still holds a resume token needs another
3202
- // round, also when the drive that started its bootstrap ends early.
3103
+ // §7.1: a unit still catching up needs another round, also when the
3104
+ // drive that started its bootstrap ends early.
3203
3105
  if (summary.bootstrapping.length > 0)
3204
3106
  this.#setSyncNeeded(true);
3205
3107
  if (deferred > 0) {
@@ -3216,7 +3118,7 @@ export class SyncClient {
3216
3118
  const unseen = this.#unseenRoundFailureCode(caught);
3217
3119
  if (unseen !== undefined)
3218
3120
  this.#roundFailureCode = unseen;
3219
- // §7.7: a round the drive deadline aborted ends with the deadline's
3121
+ // §7.8: a round the drive deadline aborted ends with the deadline's
3220
3122
  // error, whichever transport call observed the abort.
3221
3123
  const error = signal?.aborted === true ? signal.reason : caught;
3222
3124
  // §7.3.5: a request-level lease code stops-and-surfaces — record it
@@ -3285,7 +3187,7 @@ export class SyncClient {
3285
3187
  * Callers that arrive during the same drive with the same budget share that
3286
3188
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
3287
3189
  *
3288
- * §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
3289
3191
  * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
3290
3192
  * aborts a socket round in flight; the round budget does not bound elapsed
3291
3193
  * time, and a transport that never answers must not hang the caller.
@@ -3295,7 +3197,7 @@ export class SyncClient {
3295
3197
  const timeoutMs = typeof options === 'number'
3296
3198
  ? SYNC_IDLE_TIMEOUT_MS
3297
3199
  : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
3298
- // §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,
3299
3201
  // fractional, and out-of-range values are caller errors.
3300
3202
  requireRoundBudget(maxRounds);
3301
3203
  if (timeoutMs !== Number.POSITIVE_INFINITY &&
@@ -3378,10 +3280,7 @@ export class SyncClient {
3378
3280
  // The race already rejected; stop spending rounds on a dead drive.
3379
3281
  if (expired)
3380
3282
  throw expiredError();
3381
- const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
3382
- sub.id,
3383
- sub.bootstrapState,
3384
- ]));
3283
+ const before = JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3385
3284
  const last = await this.#sync(controller.signal);
3386
3285
  // Historical counters accumulate; current readiness (`bootstrapping`,
3387
3286
  // `deferredCommits`, `schemaFloor`) describes the latest round.
@@ -3405,10 +3304,7 @@ export class SyncClient {
3405
3304
  last.segmentRowsApplied > 0 &&
3406
3305
  last.bootstrapping.length > 0 &&
3407
3306
  before !==
3408
- JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
3409
- sub.id,
3410
- sub.bootstrapState,
3411
- ])))
3307
+ JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState])))
3412
3308
  round = -1;
3413
3309
  if (last.commitsApplied === 0 &&
3414
3310
  last.segmentRowsApplied === 0 &&
@@ -3784,9 +3680,7 @@ export class SyncClient {
3784
3680
  return;
3785
3681
  }
3786
3682
  try {
3787
- const message = decodeMessage(bytes);
3788
- if (message.msgKind !== 'response')
3789
- return;
3683
+ const message = decodeResponse(bytes);
3790
3684
  // §8.2: deltas apply like pull responses; ack after apply.
3791
3685
  await this.#processResponse(message, [], undefined, 'delta');
3792
3686
  }
@@ -3801,23 +3695,21 @@ export class SyncClient {
3801
3695
  if (this.#transportEnabled)
3802
3696
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
3803
3697
  }
3804
- /** 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`. */
3805
3699
  #ackAfterPull() {
3806
- if (this.#socket === undefined)
3807
- return;
3808
- const cursors = loadSubscriptions(this.#db)
3809
- .filter((sub) => sub.status === 'active' && sub.bootstrapState === undefined)
3810
- .map((sub) => sub.cursor)
3811
- .filter((cursor) => cursor >= 0);
3812
- if (cursors.length === 0)
3813
- return;
3814
- this.#sendAck(Math.min(...cursors));
3700
+ const cursor = replicaCursor(this.#db);
3701
+ if (this.#socket !== undefined && cursor >= 0)
3702
+ this.#sendAck(cursor);
3815
3703
  }
3816
3704
  // -- response processing ------------------------------------------------------
3817
- async #processResponse(message, sentCommits, sentSubs, mode, resetEpoch = this.#localResetEpoch, signal) {
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) {
3818
3711
  const summary = emptySummary(sentCommits.length);
3819
3712
  const commitsById = new Map(sentCommits.map((commit) => [commit.clientCommitId, commit]));
3820
- const subsById = new Map((sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]));
3821
3713
  const rejectionDetailsByCommit = new Map();
3822
3714
  let lastFinalPushResult;
3823
3715
  for (const frame of message.frames) {
@@ -3834,9 +3726,6 @@ export class SyncClient {
3834
3726
  if (header?.type !== 'RESP_HEADER') {
3835
3727
  throw invalidRequest('missing RESP_HEADER');
3836
3728
  }
3837
- if (message.wireVersion < 2) {
3838
- throw new ClientSyncError('client.invalid_host_response', 'the server response does not carry wire version 2 log-epoch state');
3839
- }
3840
3729
  if (header.requiredSchemaVersion !== undefined) {
3841
3730
  // §1.6 schema floor: nothing else was processed — stop syncing and
3842
3731
  // surface the upgrade requirement. A live-round floor always stops:
@@ -3872,17 +3761,13 @@ export class SyncClient {
3872
3761
  }
3873
3762
  let section;
3874
3763
  let errorFrame;
3764
+ let liveStart;
3765
+ let liveEnded = false;
3875
3766
  let deltaCursor = -1;
3876
3767
  let deltaDropped = false;
3877
- // §8.2: a delta section applies only to a locally active subscription
3878
- // that holds a cursor and no resume token. A subscription at cursor -1
3879
- // (never synced, reset, or rebootstrapped) bootstraps on its own pull.
3880
- const skipsSection = (sub) => sub === undefined ||
3881
- (mode === 'delta' &&
3882
- (sub.status !== 'active' ||
3883
- sub.cursor < 0 ||
3884
- sub.bootstrapState !== undefined));
3885
- const incompleteSubscriptions = new Set(mode === 'pull' ? subsById.keys() : []);
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 = [];
3886
3771
  // §5.4/§5.5: queue every segment download of this response, so a paged
3887
3772
  // bootstrap overlaps its page fetches instead of paying one blocking round
3888
3773
  // trip per page. At most four downloads run at once, the Rust native
@@ -3890,16 +3775,16 @@ export class SyncClient {
3890
3775
  // holds at most four bodies, the one being applied and three ahead. The
3891
3776
  // loop takes each body out of the map before applying it and tops the
3892
3777
  // window up at the next descriptor. Eligibility mirrors the loop: a
3893
- // descriptor outside an applied section, inside a skipped delta section,
3894
- // or from an unconfigured downloader is never queued, and a failure is
3895
- // only observed where the loop awaits it. A promise left over because an
3896
- // earlier frame ended apply is handled at creation, never unhandled.
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.
3897
3782
  const queued = [];
3898
3783
  const prefetched = new Map();
3899
3784
  const prefetch = () => {
3900
3785
  for (let next; prefetched.size < 4 && (next = queued.shift());) {
3901
- const [frame, sub] = next;
3902
- const pending = this.#downloadSegment(frame, sub, (bytes) => {
3786
+ const [frame, scopes] = next;
3787
+ const pending = this.#downloadSegment(frame, scopes, (bytes) => {
3903
3788
  // Only the descriptor the loop is applying reports bytes; a
3904
3789
  // sibling still in flight would overwrite its progress.
3905
3790
  if (reporting === frame)
@@ -3910,87 +3795,29 @@ export class SyncClient {
3910
3795
  }
3911
3796
  };
3912
3797
  let reporting;
3913
- const deleteKey = (commitSeq, table, rowId) => `${commitSeq}\u0000${table}\u0000${rowId}`;
3914
- {
3915
- let openSub;
3798
+ if (mode === 'pull') {
3799
+ let open;
3916
3800
  for (const frame of message.frames) {
3917
3801
  if (frame.type === 'SUB_START') {
3918
- const sub = subsById.get(frame.id);
3919
- openSub = skipsSection(sub) ? undefined : sub;
3802
+ const unit = getUnit(this.#db, frame.id);
3803
+ open = unit?.status === 'active' ? unit : undefined;
3920
3804
  }
3921
- else if (frame.type === 'SUB_END') {
3922
- openSub = undefined;
3805
+ else if (frame.type === 'SUB_END' || frame.type === 'LIVE_START') {
3806
+ open = undefined;
3923
3807
  }
3924
3808
  else if (frame.type === 'ERROR') {
3925
3809
  break; // the round fails at this frame: later refs are not fetched
3926
3810
  }
3927
3811
  else if (frame.type === 'SEGMENT_REF' &&
3928
- openSub !== undefined &&
3812
+ open !== undefined &&
3929
3813
  this.#config.segments !== undefined &&
3930
3814
  !(frame.mediaType === 'sqlite' &&
3931
3815
  (this.#acceptMask() & ACCEPT_SQLITE) === 0)) {
3932
- queued.push([frame, openSub]);
3816
+ queued.push([frame, open.scopes]);
3933
3817
  }
3934
3818
  }
3935
3819
  prefetch();
3936
3820
  }
3937
- // §2.2 scope migration: the server emits the delete tagged with the old
3938
- // scope and the upsert tagged with the new one in one commit. A reader
3939
- // that holds both scopes receives them in two subscription sections, so
3940
- // the section order would otherwise decide whether the row survives. One
3941
- // commit's delete and upsert of the same row are one change, and the
3942
- // upsert wins. A frame that carries both itself keeps its own operation
3943
- // order; only a pair split across sections is coalesced.
3944
- const coalescedDeletes = new Set();
3945
- {
3946
- const ops = new Map();
3947
- const bothInFrame = new Set();
3948
- let openSub;
3949
- let frameIndex = -1;
3950
- for (const frame of message.frames) {
3951
- if (frame.type === 'SUB_START') {
3952
- const sub = subsById.get(frame.id);
3953
- openSub = skipsSection(sub) ? undefined : sub;
3954
- }
3955
- else if (frame.type === 'SUB_END') {
3956
- openSub = undefined;
3957
- }
3958
- else if (frame.type === 'ERROR') {
3959
- break;
3960
- }
3961
- else if (frame.type === 'COMMIT' && openSub !== undefined) {
3962
- frameIndex += 1;
3963
- const local = new Map();
3964
- for (const change of frame.changes) {
3965
- const table = frame.tables[change.tableIndex];
3966
- if (table === undefined)
3967
- continue;
3968
- const key = deleteKey(frame.commitSeq, table, change.rowId);
3969
- const entry = ops.get(key) ?? {
3970
- upserts: new Set(),
3971
- deletes: new Set(),
3972
- };
3973
- if (change.op === 'upsert')
3974
- entry.upserts.add(frameIndex);
3975
- else
3976
- entry.deletes.add(frameIndex);
3977
- ops.set(key, entry);
3978
- local.set(key, (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2));
3979
- }
3980
- for (const [key, seen] of local) {
3981
- if (seen === 3)
3982
- bothInFrame.add(key);
3983
- }
3984
- }
3985
- }
3986
- for (const [key, entry] of ops) {
3987
- if (!bothInFrame.has(key) &&
3988
- entry.upserts.size > 0 &&
3989
- entry.deletes.size > 0) {
3990
- coalescedDeletes.add(key);
3991
- }
3992
- }
3993
- }
3994
3821
  // Each durable observer transaction emits its own revisioned batch.
3995
3822
  // Async decrypt/download work happens outside SQLite transactions.
3996
3823
  this.#beginDiagnosticsDeferral();
@@ -4054,42 +3881,26 @@ export class SyncClient {
4054
3881
  // Pre-indexed above so companion ordering remains wire-additive.
4055
3882
  break;
4056
3883
  case 'SUB_START': {
4057
- const sub = subsById.get(frame.id);
4058
- const fresh = sub !== undefined &&
4059
- sub.cursor < 0 &&
4060
- sub.bootstrapState === undefined &&
4061
- frame.bootstrap;
4062
- // §4.4: a section whose registration was removed mid-round
4063
- // (unsubscribe, eviction) is skipped; it never re-creates it.
4064
- const skip = skipsSection(sub) ||
4065
- getSubscription(this.#db, frame.id) === undefined;
4066
- if (skip && mode === 'delta')
4067
- deltaDropped = true;
4068
- 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;
4069
3897
  break;
4070
3898
  }
4071
- case 'COMMIT':
4072
- if (section !== undefined &&
4073
- !section.skip &&
4074
- section.sub !== undefined) {
4075
- const changes = frame.changes.filter((change) => {
4076
- if (change.op !== 'delete')
4077
- return true;
4078
- const table = frame.tables[change.tableIndex];
4079
- return (table === undefined ||
4080
- !coalescedDeletes.has(deleteKey(frame.commitSeq, table, change.rowId)));
4081
- });
4082
- if (changes.length > 0) {
4083
- await this.#applyCommit({ ...frame, changes }, summary, section.sub.id, mode);
4084
- }
4085
- }
4086
- break;
4087
3899
  case 'SEGMENT_INLINE':
4088
3900
  case 'SEGMENT_REF': {
4089
- if (section === undefined ||
4090
- section.skip ||
4091
- section.sub === undefined)
3901
+ if (section === undefined || section.skip)
4092
3902
  break;
3903
+ const unitId = section.unit.id;
4093
3904
  if (frame.type === 'SEGMENT_REF' &&
4094
3905
  frame.mediaType === 'sqlite' &&
4095
3906
  (this.#acceptMask() & ACCEPT_SQLITE) === 0) {
@@ -4099,7 +3910,7 @@ export class SyncClient {
4099
3910
  if (frame.type === 'SEGMENT_REF') {
4100
3911
  this.#progress.update({
4101
3912
  phase: 'download',
4102
- subscriptionId: section.sub.id,
3913
+ unitId,
4103
3914
  table: frame.table,
4104
3915
  segmentId: frame.segmentId,
4105
3916
  bytesReceived: 0,
@@ -4113,67 +3924,149 @@ export class SyncClient {
4113
3924
  if (pending !== undefined)
4114
3925
  reporting = frame;
4115
3926
  bytes = await (pending ??
4116
- this.#downloadSegment(frame, section.sub, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
4117
- }
4118
- else {
4119
- bytes = frame.payload;
4120
- }
4121
- if (frame.type === 'SEGMENT_REF')
3927
+ this.#downloadSegment(frame, section.unit.scopes, (bytesReceived) => this.#progress.update({ bytesReceived }), signal));
4122
3928
  this.#progress.update({ phase: 'import' });
4123
- if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
4124
- // Images are whole-table; paged image descriptors are invalid.
4125
- if (frame.rowCursor !== undefined ||
4126
- frame.nextRowCursor !== undefined) {
4127
- throw invalidRequest('sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)');
4128
- }
4129
- await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective, owners) => applySqliteSegment(this.#db, this.#schema, table, bytes, {
4130
- table: frame.table,
4131
- rowCount: frame.rowCount,
4132
- asOfCommitSeq: frame.asOfCommitSeq,
4133
- scopeDigest: frame.scopeDigest,
4134
- }, this.#segmentApplyOptions(table, clearFirst, effective, owners, frame.rowCount > 0, resetEpoch)), section.fresh && !section.cleared);
4135
3929
  }
4136
3930
  else {
4137
- const segment = decodeRowsSegment(bytes);
4138
- if (frame.type === 'SEGMENT_INLINE') {
4139
- this.#progress.update({
4140
- phase: 'import',
4141
- subscriptionId: section.sub.id,
4142
- table: section.sub.table,
4143
- segmentId: undefined,
4144
- bytesReceived: bytes.byteLength,
4145
- bytesTotal: bytes.byteLength,
4146
- rowsProcessed: 0,
4147
- rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
4148
- });
4149
- }
4150
- await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective, owners) => applyRowsSegment(this.#db, this.#schema, table, segment, this.#segmentApplyOptions(table, clearFirst, effective, owners, segment.blocks.some((block) => block.length > 0), resetEpoch), this.#encryption), section.fresh &&
4151
- !section.cleared &&
4152
- (frame.type === 'SEGMENT_INLINE' ||
4153
- frame.rowCursor === undefined));
3931
+ bytes = frame.payload;
4154
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
+ });
4155
3961
  break;
4156
3962
  }
4157
3963
  case 'SUB_END': {
4158
- if (section?.sub !== undefined &&
4159
- !section.skip &&
4160
- this.#localResetEpoch === resetEpoch) {
4161
- incompleteSubscriptions.delete(section.sub.id);
4162
- }
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.
4163
3967
  if (section !== undefined &&
4164
3968
  !section.skip &&
4165
- section.sub !== undefined &&
4166
- // Reset fence: a rebootstrap that landed mid-round already
4167
- // rewound this subscription's cursor; the captured SUB_END
4168
- // state predates the rewind and must stay unpersisted so the
4169
- // next round runs the fresh bootstrap.
4170
- this.#localResetEpoch === resetEpoch) {
4171
- const applied = this.#finishSection(section.sub, section.start, frame.nextCursor, frame.bootstrapState, summary);
4172
- if (mode === 'delta' && applied) {
4173
- 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;
4174
3984
  }
3985
+ else if (end?.type === 'LIVE_END' && end.throughSeq <= cursor)
3986
+ liveStart = undefined;
4175
3987
  }
4176
- 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
+ });
4177
4070
  break;
4178
4071
  }
4179
4072
  case 'ERROR': {
@@ -4209,14 +4102,10 @@ export class SyncClient {
4209
4102
  }
4210
4103
  if (errorFrame !== undefined)
4211
4104
  throw errorFrame;
4212
- if (incompleteSubscriptions.size > 0) {
4213
- this.#setSyncNeeded(true);
4214
- this.#emitSyncIntent({ kind: 'interactive' });
4215
- }
4216
4105
  if (mode === 'delta') {
4217
4106
  if (deltaCursor >= 0)
4218
4107
  this.#sendAck(deltaCursor);
4219
- // §8.2: a skipped delta section is a drop; a pull repairs it.
4108
+ // §8.2: an unapplied delta is a drop; a pull repairs it.
4220
4109
  if (deltaDropped) {
4221
4110
  this.#setSyncNeeded(true);
4222
4111
  this.#emitSyncNeeded('catchup-required');
@@ -4225,23 +4114,32 @@ export class SyncClient {
4225
4114
  else {
4226
4115
  this.#ackAfterPull();
4227
4116
  }
4228
- const bootstrapping = loadSubscriptions(this.#db)
4229
- .filter((sub) => sub.status === 'active' && sub.bootstrapState !== undefined)
4230
- .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
+ }
4231
4129
  // §7.4.5: the reset is over once the first post-reset pull round leaves
4232
- // no subscription mid-bootstrap — the tables are rebuilt and current.
4233
- // The epoch check keeps a round that predates a mid-flight rebootstrap
4234
- // 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.
4235
4133
  if (this.#upgrading &&
4236
4134
  mode === 'pull' &&
4237
- bootstrapping.length === 0 &&
4135
+ catchingUp.length === 0 &&
4238
4136
  this.#localResetEpoch === resetEpoch) {
4239
4137
  this.#setUpgrading(false);
4240
4138
  }
4241
4139
  // RFC 0005 D7: coverage completion, lease end, scope revocation and TTL are
4242
4140
  // evaluated once per round, after the apply.
4243
4141
  this.#previousVersionLifetimeCheck();
4244
- return { ...summary, bootstrapping };
4142
+ return { ...summary, bootstrapping: catchingUp };
4245
4143
  }
4246
4144
  #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {
4247
4145
  const commit = commitsById.get(frame.clientCommitId);
@@ -4397,7 +4295,7 @@ export class SyncClient {
4397
4295
  });
4398
4296
  return names;
4399
4297
  }
4400
- async #applyCommit(frame, summary, subscriptionId, source) {
4298
+ async #applyCommit(frame, summary, source) {
4401
4299
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4402
4300
  this.#recordCommitChanges(batch, frame);
4403
4301
  const result = fn();
@@ -4405,7 +4303,6 @@ export class SyncClient {
4405
4303
  for (const table of new Set(frame.changes.map((change) => frame.tables[change.tableIndex]))) {
4406
4304
  if (table !== undefined)
4407
4305
  batch.appliedCommit({
4408
- subscriptionId,
4409
4306
  table,
4410
4307
  commitSeq: frame.commitSeq,
4411
4308
  source,
@@ -4478,48 +4375,44 @@ export class SyncClient {
4478
4375
  };
4479
4376
  }
4480
4377
  /**
4481
- * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
4482
- * (no local scope-column mapping) marks the subscription `failed` and
4483
- * 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.
4484
4382
  */
4485
- async #applySegmentOrFail(section, summary, apply, clearFirst) {
4486
- const sub = section.sub;
4487
- if (sub === undefined)
4488
- return;
4489
- 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');
4490
4391
  try {
4491
- summary.segmentRowsApplied += await apply(table, clearFirst, section.start.effectiveScopes, this.#scopeOwners(sub.table, sub.id));
4492
- 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);
4493
4394
  }
4494
4395
  catch (error) {
4495
- if (error instanceof ClientSyncError &&
4496
- error.code === 'sync.scope_revoked') {
4497
- section.skip = true;
4498
- if (getSubscription(this.#db, sub.id) === undefined)
4499
- return;
4500
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4501
- this.#applyBatch((batch) => {
4502
- saveSubscription(this.#db, definedObject({
4503
- id: sub.id,
4504
- table: sub.table,
4505
- scopes: sub.scopes,
4506
- params: sub.params,
4507
- cursor: sub.cursor,
4508
- effectiveScopes: sub.effectiveScopes,
4509
- status: 'failed',
4510
- reasonCode: 'sync.scope_revoked',
4511
- }));
4512
- if (registered !== undefined) {
4513
- batch.window(registered.baseKey, sub.table, registered.unit);
4514
- }
4515
- });
4516
- summary.failed.push(sub.id);
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)
4517
4402
  return;
4518
- }
4519
- 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);
4520
4413
  }
4521
4414
  }
4522
- async #downloadSegment(frame, sub, onProgress, signal) {
4415
+ async #downloadSegment(frame, scopes, onProgress, signal) {
4523
4416
  const downloader = this.#config.segments;
4524
4417
  if (downloader === undefined) {
4525
4418
  throw invalidRequest('received SEGMENT_REF but no segment downloader is configured');
@@ -4546,7 +4439,11 @@ export class SyncClient {
4546
4439
  bytes = await downloader({
4547
4440
  segmentId: frame.segmentId,
4548
4441
  table: frame.table,
4549
- 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
+ ]))),
4550
4447
  byteLength: frame.byteLength,
4551
4448
  onProgress,
4552
4449
  ...(signal !== undefined ? { signal } : {}),
@@ -4567,164 +4464,172 @@ export class SyncClient {
4567
4464
  return bytes;
4568
4465
  }
4569
4466
  /** Returns whether SUB_END state was persisted (section applied). */
4570
- #finishSection(sub, start, nextCursor, bootstrapState, summary) {
4571
- // §4.4: SUB_END rewrites a live registration only. An unsubscribe or
4572
- // eviction during this round's awaits removed it; persisting now would
4573
- // re-create it. Everything below is synchronous with this check.
4574
- if (getSubscription(this.#db, sub.id) === undefined)
4575
- return false;
4576
- if (start.status === 'active') {
4577
- // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
4578
- // §3.3: the effective-scope echo is persisted for the purge contract.
4579
- // An absent bootstrapState clears any previous resume token (§4.4:
4580
- // absent = bootstrap complete, or not bootstrapping).
4581
- const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
4582
- const completed = wasPending && nextCursor >= 0 && bootstrapState === undefined;
4583
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4584
- this.#applyBatch((batch) => {
4585
- saveSubscription(this.#db, definedObject({
4586
- id: sub.id,
4587
- table: sub.table,
4588
- scopes: sub.scopes,
4589
- params: sub.params,
4590
- cursor: nextCursor,
4591
- bootstrapState: bootstrapState,
4592
- effectiveScopes: start.effectiveScopes,
4593
- status: 'active',
4594
- }));
4595
- if (completed) {
4596
- const table = this.#table(sub.table);
4597
- const effective = start.effectiveScopes;
4598
- const covered = this.#db
4599
- .query(`SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`, [sub.table, nextCursor])
4600
- .filter((row) => [row.intent, row.base].some((json) => {
4601
- if (json === null)
4602
- return false;
4603
- const values = JSON.parse(String(json));
4604
- return matchesLocalScopes(table, effective, values);
4605
- }));
4606
- if (covered.length) {
4607
- const scope = covered.map((row) => JSON.stringify([sub.table, String(row.id)]));
4608
- restoreFailedBases(this.#db, this.#schema, scope);
4609
- for (const row of covered)
4610
- this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [sub.table, String(row.id), nextCursor]);
4611
- batch.table(sub.table);
4612
- this.#replayOutbox(scope, false);
4613
- }
4614
- }
4615
- if (completed && registered !== undefined) {
4616
- // A zero-row bootstrap is a window-domain transition, not a fake
4617
- // row/table change (SPEC §4.8 / §7.5).
4618
- batch.window(registered.baseKey, sub.table, registered.unit);
4619
- }
4620
- });
4621
- return true;
4622
- }
4623
- if (start.status === 'reset') {
4624
- // §4.6: discard cursor + resume token, keep local rows, re-bootstrap
4625
- // with cursor = -1 on the next pull. Staleness, not a purge.
4626
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4627
- this.#applyBatch((batch) => {
4628
- saveSubscription(this.#db, definedObject({
4629
- id: sub.id,
4630
- table: sub.table,
4631
- scopes: sub.scopes,
4632
- params: sub.params,
4633
- cursor: -1,
4634
- effectiveScopes: sub.effectiveScopes,
4635
- status: 'active',
4636
- reasonCode: start.reasonCode,
4637
- }));
4638
- if (registered !== undefined) {
4639
- batch.window(registered.baseKey, sub.table, registered.unit);
4640
- }
4641
- });
4642
- summary.resets.push(sub.id);
4643
- return false;
4644
- }
4645
- // revoked (§3.3): purge rows matching the LAST-echoed effective scopes
4646
- // (never the requested map), drop doomed outbox commits, stop pulling.
4647
- const table = this.#table(sub.table);
4648
- const lastEffective = sub.effectiveScopes;
4649
- const owners = this.#scopeOwners(sub.table, sub.id);
4650
- const registered = getWindowUnitBySubId(this.#db, sub.id);
4651
- 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);
4652
4480
  this.#applyBatch((batch) => {
4653
- if (lastEffective !== undefined &&
4654
- Object.keys(lastEffective).length > 0) {
4655
- try {
4656
- const scope = [
4657
- JSON.stringify([table.name]),
4658
- ...this.#dropRetainedRows(batch, (name, values) => name === table.name &&
4659
- ownsLocalRow(table, lastEffective, owners, values)),
4660
- ];
4661
- deleteScopedRows(this.#db, table, lastEffective, owners);
4662
- batch.scopeMap(table, lastEffective);
4663
- // §3.3: a whole pending commit leaves when one of its upserts
4664
- // provably lands in the revoked scopes and no other owner covers it.
4665
- const doomed = listOutbox(this.#db).filter((commit) => commit.operations.some((op) => op.table === table.name &&
4666
- op.values !== undefined &&
4667
- ownsLocalRow(table, lastEffective, owners, op.values)));
4668
- if (doomed.length > 0) {
4669
- for (const commit of doomed) {
4670
- const { clientCommitId } = commit;
4671
- deleteOutboxCommit(this.#db, clientCommitId);
4672
- const results = commit.operations.map((operation, opIndex) => {
4673
- const rejection = {
4674
- clientCommitId,
4675
- opIndex,
4676
- code: 'sync.scope_revoked',
4677
- message: 'the commit was dropped because its effective scope was revoked',
4678
- retryable: false,
4679
- operation,
4680
- };
4681
- this.#rejections.push(rejection);
4682
- return { status: 'error', rejection };
4683
- });
4684
- recordCommitOutcome(this.#db, {
4685
- clientCommitId,
4686
- status: 'rejected',
4687
- recordedAtMs: this.#now(),
4688
- results,
4689
- operations: commit.operations,
4690
- });
4691
- }
4692
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4693
- batch.status();
4694
- batch.rejections();
4695
- batch.outcomes();
4696
- }
4697
- this.#replayOutbox(scope);
4698
- this.#deleteUnreferencedBlobs();
4699
- }
4700
- catch (error) {
4701
- if (error instanceof ClientSyncError &&
4702
- error.code === 'sync.scope_revoked') {
4703
- failed = true;
4704
- }
4705
- else {
4706
- throw error;
4707
- }
4708
- }
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;
4709
4495
  }
4710
- saveSubscription(this.#db, definedObject({
4711
- id: sub.id,
4712
- table: sub.table,
4713
- scopes: sub.scopes,
4714
- params: sub.params,
4715
- cursor: nextCursor,
4716
- effectiveScopes: lastEffective,
4717
- status: failed ? 'failed' : 'revoked',
4718
- reasonCode: start.reasonCode,
4719
- }));
4720
- if (registered !== undefined) {
4721
- 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);
4722
4571
  }
4723
4572
  });
4724
- summary.revoked.push(sub.id);
4725
- if (failed)
4726
- summary.failed.push(sub.id);
4727
- 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
+ }
4728
4633
  }
4729
4634
  // -- optimistic state ----------------------------------------------------------
4730
4635
  #captureBeforeImage(operation, opIndex) {