@syncular/client 0.59.0 → 0.60.1

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 +19 -5
  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 +23 -14
  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 +22 -9
  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 +27 -19
  66. package/src/worker-protocol.ts +8 -8
package/src/client.ts CHANGED
@@ -29,11 +29,11 @@ import {
29
29
  import {
30
30
  type CommitFrame,
31
31
  canonicalScopeJson,
32
- decodeMessage,
32
+ decodeResponse,
33
33
  DecodeError,
34
34
  decodeRow,
35
35
  decodeRowsSegment,
36
- encodeMessage,
36
+ encodeRequest,
37
37
  encodeRow,
38
38
  encodeSparseRow,
39
39
  encodePresencePublish,
@@ -52,9 +52,15 @@ import {
52
52
  type ResponseMessage,
53
53
  type RowColumn,
54
54
  type RowValue,
55
+ type LiveStartFrame,
56
+ type PullHeaderFrame,
57
+ registrationDigest,
55
58
  type ScopeMap,
56
59
  type SegmentRefFrame,
60
+ type SubEndFrame,
57
61
  type SubStartFrame,
62
+ unitId,
63
+ type UnitScopes,
58
64
  type WakeReason,
59
65
  } from '@syncular/core';
60
66
  import { EncryptError } from '@syncular/core';
@@ -94,16 +100,13 @@ import {
94
100
  CLIENT_DIAGNOSTICS_VERSION,
95
101
  ClientDiagnosticsEmitter,
96
102
  type ClientDiagnosticsListener,
97
- type ClientDiagnosticsRequest,
98
103
  type ClientDiagnosticsSnapshot,
99
104
  type ClientDiagnosticsStorage,
100
105
  type DiagnosticLastChange,
101
106
  type DiagnosticLastRound,
102
107
  type DiagnosticQueryFailure,
103
108
  type DiagnosticRoundCounters,
104
- type DiagnosticSubscription,
105
109
  MAX_DIAGNOSTIC_DOMAINS,
106
- MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
107
110
  MAX_DIAGNOSTIC_QUERY_FAILURES,
108
111
  type RealtimePolicy,
109
112
  type RealtimeState,
@@ -211,10 +214,12 @@ import {
211
214
  writePreviousVersionRefusal,
212
215
  } from './previous-version';
213
216
  import {
217
+ bytesToHex,
214
218
  type ClientSchema,
215
219
  type CompiledClientSchema,
216
220
  type CompiledClientTable,
217
221
  compileClientSchema,
222
+ hexToBytes,
218
223
  matchesLocalScopes,
219
224
  dropAndRecreateSyncedTables,
220
225
  ensureLocalBookkeepingSchema,
@@ -234,19 +239,28 @@ import {
234
239
  stripSyncColumns,
235
240
  } from './schema';
236
241
  import {
242
+ bootstrapping,
237
243
  bumpLocalRevision,
238
- deleteSubscription,
244
+ covers,
245
+ deleteUnit,
246
+ ECHO_DIGEST_KEY,
239
247
  getLocalRevision,
240
248
  getMeta,
241
- getSubscription,
242
- loadSubscriptions,
243
- pruneUnknownSubscriptions,
244
- saveSubscriptionScopeSchema,
245
- resetSubscriptionsForBump,
246
- type SubscriptionRecord,
247
- saveSubscription,
249
+ getUnit,
250
+ loadUnits,
251
+ META_TABLE,
252
+ owning,
253
+ pairScopes,
254
+ pruneUnknownUnits,
255
+ REGISTERED_DIGEST_KEY,
256
+ REPLICA_CURSOR_KEY,
257
+ replicaCursor,
258
+ resetUnits,
259
+ saveUnit,
260
+ saveUnitScopeSchema,
248
261
  setMeta,
249
- SUBSCRIPTIONS_TABLE,
262
+ type UnitRecord,
263
+ unitOwners,
250
264
  } from './state';
251
265
  import type {
252
266
  RealtimeConnector,
@@ -256,16 +270,14 @@ import type {
256
270
  } from './transport';
257
271
  import {
258
272
  deletePendingEviction,
259
- deleteWindowUnit,
260
- deriveSubId,
261
- getWindowUnitBySubId,
262
- insertWindowUnit,
263
273
  loadPendingEvictions,
264
274
  loadWindowUnits,
265
275
  savePendingEviction,
266
- unitScopes,
267
276
  type WindowBase,
268
277
  windowBaseKey,
278
+ windowRefs,
279
+ WINDOWS_TABLE,
280
+ windowUnitScopes,
269
281
  } from './window';
270
282
 
271
283
  // ---------------------------------------------------------------------------
@@ -332,14 +344,14 @@ export interface SyncSummary {
332
344
  readonly commitsApplied: number;
333
345
  /** Snapshot rows applied from segments. */
334
346
  readonly segmentRowsApplied: number;
335
- /** Subscriptions still mid-bootstrap (resume token pending). */
347
+ /** Ids of the units still catching up after the round (§4.1). */
336
348
  readonly bootstrapping: readonly string[];
337
- /** Subscriptions reset via `sync.cursor_expired` (re-pull needed). */
349
+ /** Units reset via `sync.cursor_expired` (§4.6). */
338
350
  readonly resets: readonly string[];
339
- /** Subscriptions revoked this round (§3.3 purge ran). */
351
+ /** Units revoked this round (§3.3 purge ran). */
340
352
  readonly revoked: readonly string[];
341
- /** Subscriptions stopped by a fatal configuration error (§3.3/§5.6
342
- * fail-closed: no local scope-column mapping). */
353
+ /** Units stopped by a fatal configuration error (§3.3/§5.6 fail-closed:
354
+ * no local scope-column mapping). */
343
355
  readonly failed: readonly string[];
344
356
  /** Present when the server declared a schema floor — syncing stopped. */
345
357
  readonly schemaFloor?: SchemaFloor;
@@ -359,7 +371,7 @@ export interface SyncIdleResult extends SyncSummary {
359
371
  }
360
372
 
361
373
  export interface SyncIdleOptions {
362
- /** §7.7: a strict positive round count. Default: 20. */
374
+ /** §7.8: a strict positive round count. Default: 20. */
363
375
  readonly maxRounds?: number;
364
376
  /**
365
377
  * Total wall-clock budget for one drive, across every round. When it
@@ -391,7 +403,7 @@ export interface SyncClientLimits {
391
403
  /**
392
404
  * §4.2 accept bitmask; defaults to inline + external rows (0b0011)
393
405
  * plus SQLite images and signed URLs when supported. Both image chunks
394
- * and rows blocks commit before yielding to local reads (§7.7).
406
+ * and rows blocks commit before yielding to local reads (§7.8).
395
407
  */
396
408
  readonly accept?: number;
397
409
  /**
@@ -410,7 +422,8 @@ export interface SyncClientLimits {
410
422
  readonly maxPushOperationsPerRequest?: number;
411
423
  /**
412
424
  * §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
413
- * envelope, request header, push commits, pull header, subscriptions,
425
+ * envelope, request header, push commits, pull header, unit and progress
426
+ * frames,
414
427
  * framing, and any §5.11 ciphertext). Default: unbounded. A request whose
415
428
  * fixed frames alone exceed it, or whose first commit alone does not fit,
416
429
  * raises `client.push_request_too_large` and stays queued.
@@ -549,13 +562,6 @@ export interface PresencePeer {
549
562
  readonly doc: Record<string, unknown>;
550
563
  }
551
564
 
552
- export interface SubscribeInput {
553
- readonly id: string;
554
- readonly table: string;
555
- readonly scopes: ScopeMap;
556
- readonly params?: string;
557
- }
558
-
559
565
  /**
560
566
  * The live state of a window base (§4.8) — the completeness oracle (I3),
561
567
  * as plain serializable data so it crosses the worker/follower boundary
@@ -568,11 +574,10 @@ export interface WindowState {
568
574
  /** Windowed-in units for this base, ordered by value. */
569
575
  readonly units: readonly string[];
570
576
  /**
571
- * Registered units whose bootstrap has not yet completed (§4.8): the
572
- * unit's subscription still has `cursor: -1` (never synced) or holds a
573
- * resume token (mid-bootstrap). Between `setWindow` and the bootstrap
574
- * landing, the local replica for a pending unit may be empty or partial —
575
- * it MUST NOT be rendered as complete.
577
+ * Windowed-in values whose unit is not complete (§4.8): bootstrapping
578
+ * (cursor `-1` or a resume token), revoked or failed. Between `setWindow`
579
+ * and the bootstrap landing, the local replica for a pending value may be
580
+ * empty or partial; it MUST NOT be rendered as complete.
576
581
  */
577
582
  readonly pending: readonly string[];
578
583
  }
@@ -624,25 +629,24 @@ export interface SnapshotStatement {
624
629
  }
625
630
 
626
631
  /**
627
- * §7.5: the catch-up state of one subscription as persisted in the snapshot,
628
- * never the mutable owner cache. `unknown` means the client does not currently
629
- * hold the subscription (never registered, forgotten, or removed) and carries
630
- * no fabricated table or cursor.
632
+ * §7.5: the catch-up state of one unit as persisted in the snapshot, never
633
+ * the mutable owner cache. `unknown` means the client does not currently hold
634
+ * the unit (never registered, released, or removed).
631
635
  */
632
- export type SubscriptionCatchup =
636
+ export type UnitCatchup =
633
637
  | { readonly state: 'unknown'; readonly id: string }
634
638
  | {
635
639
  readonly state: 'known';
636
640
  readonly id: string;
637
- readonly table: string;
638
641
  readonly status: 'active' | 'revoked' | 'failed';
642
+ readonly live: boolean;
643
+ /** The unit's cursor while it catches up, the replica cursor while live. */
639
644
  readonly cursor: number;
640
645
  readonly hasResumeToken: boolean;
641
- /** True only for `active` with `cursor >= 0` and no resume token. */
646
+ /** True only for an `active` unit that is live or post-bootstrap. */
642
647
  readonly bootstrapComplete: boolean;
643
- /** True only for `active` while a resume token remains or `cursor < 0`. */
648
+ /** True only for an `active` unit with cursor `-1` or a resume token. */
644
649
  readonly knownPendingPages: boolean;
645
- readonly effectiveScopes?: unknown;
646
650
  readonly reasonCode?: string;
647
651
  };
648
652
 
@@ -665,7 +669,8 @@ export type CommitDelivery =
665
669
  export interface SnapshotReadRequest {
666
670
  readonly statements: readonly SnapshotStatement[];
667
671
  readonly coverage?: readonly WindowCoverage[];
668
- readonly subscriptions?: readonly string[];
672
+ /** Unit ids whose catch-up state the read reports. */
673
+ readonly units?: readonly string[];
669
674
  readonly commitIds?: readonly string[];
670
675
  /** §7.5 owner: a failed owned read is reported in `queryFailures`. */
671
676
  readonly owner?: QueryOwner;
@@ -677,7 +682,7 @@ export interface SnapshotRead<Row = SqlRow> {
677
682
  readonly revision: LocalRevision;
678
683
  readonly queries: readonly (readonly Row[])[];
679
684
  readonly coverage: CoverageSnapshot;
680
- readonly subscriptions: readonly SubscriptionCatchup[];
685
+ readonly units: readonly UnitCatchup[];
681
686
  readonly deliveries: readonly CommitDelivery[];
682
687
  }
683
688
 
@@ -728,12 +733,11 @@ async function sha256Hex(bytes: Uint8Array): Promise<string> {
728
733
 
729
734
  interface OpenSection {
730
735
  readonly start: SubStartFrame;
731
- readonly sub: SubscriptionRecord | undefined;
732
- /** Fresh bootstrap (§5.6): request had cursor < 0 and no resume token. */
733
- readonly fresh: boolean;
734
- /** Skip application entirely (unknown sub, delta during bootstrap, …). */
736
+ readonly unit: UnitRecord;
737
+ /** Tables that received a segment in the current bootstrap (§5.6). */
738
+ readonly seeded: Set<string>;
739
+ /** A unit unregistered in flight or failed closed applies nothing. */
735
740
  skip: boolean;
736
- cleared: boolean;
737
741
  }
738
742
 
739
743
  /** §8.7 client side: one in-flight socket round's response assembly. */
@@ -773,7 +777,7 @@ function emptySummary(pushed: number): MutableSummary {
773
777
 
774
778
  const LOG_EPOCH_META_KEY = 'logEpoch';
775
779
 
776
- /** §7.7: one `syncUntilIdle` drive's default total deadline. */
780
+ /** §7.8: one `syncUntilIdle` drive's default total deadline. */
777
781
  const SYNC_IDLE_TIMEOUT_MS = 60_000;
778
782
 
779
783
  /** RFC 0005 defaults (D2/A4/D7). */
@@ -783,7 +787,7 @@ const PREVIOUS_VERSION_DEFAULT_MAX_TABLES = 32;
783
787
  const PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES = 1024 * 1024;
784
788
  const PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
785
789
 
786
- /** §7.7: an explicit round budget is a strict positive u32 count. */
790
+ /** §7.8: an explicit round budget is a strict positive u32 count. */
787
791
  function requireRoundBudget(maxRounds: number | undefined): void {
788
792
  if (
789
793
  maxRounds !== undefined &&
@@ -918,7 +922,7 @@ export class SyncClient {
918
922
  #securityEpoch = 0;
919
923
  #transportEnabled: boolean;
920
924
  #transportEpoch = 0;
921
- #subscriptionEpoch = 0;
925
+ #registrationEpoch = 0;
922
926
  readonly #now: () => number;
923
927
  readonly #outcomeRetentionMaxEntries: number;
924
928
  readonly #retainFailedCommits: boolean;
@@ -1148,7 +1152,6 @@ export class SyncClient {
1148
1152
  // BUSY/BUSY_SNAPSHOT), and one upgraded before the read refuses with
1149
1153
  // `client.schema_downgrade`. The batch emits its change event only after
1150
1154
  // the commit. The onUpgrading callback still reports reset intent.
1151
- let subscriptions!: ReturnType<typeof pruneUnknownSubscriptions>;
1152
1155
  try {
1153
1156
  this.#applyBatch(() => {
1154
1157
  // §7.4.1/§7.4.2: this is the transaction's first read, so it pins the
@@ -1264,11 +1267,7 @@ export class SyncClient {
1264
1267
  this.#reconcilePreviousVersionAtBoot();
1265
1268
  // A registration remains app intent only while its table exists in the
1266
1269
  // running schema. Removed-table registrations would poison every pull.
1267
- subscriptions = pruneUnknownSubscriptions(
1268
- this.#db,
1269
- loadSubscriptions(this.#db),
1270
- this.#schema,
1271
- );
1270
+ pruneUnknownUnits(this.#db, this.#schema);
1272
1271
  });
1273
1272
  } catch (error) {
1274
1273
  await this.#lease.release();
@@ -1289,7 +1288,7 @@ export class SyncClient {
1289
1288
  `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
1290
1289
  ).length > 0 ||
1291
1290
  loadPendingEvictions(this.#db).length > 0 ||
1292
- subscriptions.some((sub) => sub.status === 'active'));
1291
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
1293
1292
  if (startupWork && this.#securityLifecycle === 'active') {
1294
1293
  this.#needsPull = true;
1295
1294
  this.#emitSyncNeeded('startup');
@@ -1302,7 +1301,7 @@ export class SyncClient {
1302
1301
  clientId: () => this.#clientId,
1303
1302
  role: () => 'direct',
1304
1303
  outbox: async () => this.pendingCommits().length,
1305
- subscriptions: async () => this.subscriptions(),
1304
+ units: async () => this.units(),
1306
1305
  conflicts: async () => this.conflicts().length,
1307
1306
  rejections: async () => this.rejections().length,
1308
1307
  syncNeeded: async () => this.statusSnapshot().syncNeeded,
@@ -1331,7 +1330,7 @@ export class SyncClient {
1331
1330
  String(this.#schema.version),
1332
1331
  );
1333
1332
  setLocalSchemaDescriptor(this.#db, this.#schema);
1334
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1333
+ saveUnitScopeSchema(this.#db, this.#schema);
1335
1334
  });
1336
1335
  return;
1337
1336
  }
@@ -1342,7 +1341,7 @@ export class SyncClient {
1342
1341
  this.#db.transaction(() => {
1343
1342
  ensureLocalSyncedSchema(this.#db, this.#schema);
1344
1343
  setLocalSchemaDescriptor(this.#db, this.#schema);
1345
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1344
+ saveUnitScopeSchema(this.#db, this.#schema);
1346
1345
  });
1347
1346
  return;
1348
1347
  }
@@ -1382,15 +1381,10 @@ export class SyncClient {
1382
1381
  ),
1383
1382
  );
1384
1383
  }
1385
- pruneUnknownSubscriptions(
1386
- this.#db,
1387
- loadSubscriptions(this.#db),
1388
- this.#schema,
1389
- true,
1390
- );
1384
+ pruneUnknownUnits(this.#db, this.#schema, true);
1391
1385
  this.#discardAcknowledgedRows();
1392
1386
  dropAndRecreateSyncedTables(this.#db, this.#schema);
1393
- resetSubscriptionsForBump(this.#db);
1387
+ resetUnits(this.#db);
1394
1388
  this.#replayOutbox();
1395
1389
  setMeta(
1396
1390
  this.#db,
@@ -1398,7 +1392,7 @@ export class SyncClient {
1398
1392
  String(this.#schema.version),
1399
1393
  );
1400
1394
  setLocalSchemaDescriptor(this.#db, this.#schema);
1401
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1395
+ saveUnitScopeSchema(this.#db, this.#schema);
1402
1396
  });
1403
1397
  // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
1404
1398
  for (const table of this.#schema.tables.values()) batch.table(table.name);
@@ -1488,7 +1482,7 @@ export class SyncClient {
1488
1482
  this.#emitSyncIntent({ kind: 'interactive' });
1489
1483
  return [];
1490
1484
  }
1491
- const subscriptions = loadSubscriptions(this.#db);
1485
+ const units = loadUnits(this.#db);
1492
1486
  this.#setUpgrading(true);
1493
1487
  // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
1494
1488
  // orphan sweep but captures no new shadow.
@@ -1499,7 +1493,7 @@ export class SyncClient {
1499
1493
  this.#db.transaction(() => {
1500
1494
  this.#discardAcknowledgedRows();
1501
1495
  dropAndRecreateSyncedTables(this.#db, this.#schema);
1502
- resetSubscriptionsForBump(this.#db);
1496
+ resetUnits(this.#db);
1503
1497
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
1504
1498
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
1505
1499
  // transaction before they replay, so the reset boundary never fails on
@@ -1525,7 +1519,7 @@ export class SyncClient {
1525
1519
  this.#setSyncNeeded(true);
1526
1520
  this.#emitSyncNeeded('startup');
1527
1521
  this.#emitSyncIntent({ kind: 'interactive' });
1528
- return subscriptions.map((subscription) => subscription.id);
1522
+ return units.map((unit) => unit.id);
1529
1523
  }
1530
1524
 
1531
1525
  #setUpgrading(upgrading: boolean): void {
@@ -1681,7 +1675,7 @@ export class SyncClient {
1681
1675
  `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
1682
1676
  ).length > 0 ||
1683
1677
  loadPendingEvictions(this.#db).length > 0 ||
1684
- loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
1678
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
1685
1679
  if (startupWork) {
1686
1680
  this.#setSyncNeeded(true);
1687
1681
  this.#emitSyncNeeded('startup');
@@ -1786,7 +1780,7 @@ export class SyncClient {
1786
1780
  }
1787
1781
 
1788
1782
  /**
1789
- * §7.5: resolve several read-only statements, window coverage, subscription
1783
+ * §7.5: resolve several read-only statements, window coverage, unit
1790
1784
  * catch-up states, and commit deliveries from one SQLite read transaction
1791
1785
  * and one revision. A host that needs those together reads them together;
1792
1786
  * every statement passes the read-only guard and any failure rolls the whole
@@ -1797,10 +1791,9 @@ export class SyncClient {
1797
1791
  return this.#readSnapshot(spec);
1798
1792
  }
1799
1793
 
1800
- /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
1801
- subscriptionCatchup(id: string): SubscriptionCatchup {
1802
- return this.#readSnapshot({ statements: [], subscriptions: [id] })
1803
- .subscriptions[0]!;
1794
+ /** §7.5: one unit's persisted catch-up state (never the owner cache). */
1795
+ unitCatchup(id: string): UnitCatchup {
1796
+ return this.#readSnapshot({ statements: [], units: [id] }).units[0]!;
1804
1797
  }
1805
1798
 
1806
1799
  /** §7.5: one client commit's delivery status: pending, its retained outcome,
@@ -1812,75 +1805,35 @@ export class SyncClient {
1812
1805
 
1813
1806
  /**
1814
1807
  * §7.5: the one atomic read primitive. Every public read (`querySnapshot`,
1815
- * `snapshotRead`, `subscriptionCatchup`, `commitDelivery`) enters here, so
1808
+ * `snapshotRead`, `unitCatchup`, `commitDelivery`) enters here, so
1816
1809
  * the read-only guard, transaction, revision, coverage, catch-up, delivery,
1817
1810
  * and owner-failure observation exist once.
1818
1811
  */
1819
1812
  #readSnapshot(request: SnapshotReadRequest): SnapshotRead {
1820
1813
  this.#requireActive();
1821
1814
  const owner = request.owner;
1822
- const catchupOf = (id: string): SubscriptionCatchup => {
1823
- function corrupt(): never {
1815
+ const catchupOf = (id: string): UnitCatchup => {
1816
+ const unit = getUnit(this.#db, id);
1817
+ if (unit === undefined) return { state: 'unknown', id };
1818
+ const cursor = unit.cursor ?? replicaCursor(this.#db);
1819
+ if (!Number.isSafeInteger(cursor))
1824
1820
  throw new ClientSyncError(
1825
1821
  'sync.local_corrupt',
1826
- 'persisted subscription state is invalid',
1822
+ 'persisted unit state is invalid',
1827
1823
  );
1828
- }
1829
- const row = this.#db.query(
1830
- `SELECT tbl,status,cursor,bootstrap_state,effective_scopes,reason_code FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`,
1831
- [id],
1832
- )[0];
1833
- if (row === undefined) return { state: 'unknown', id };
1834
- const table = row.tbl;
1835
- const status = row.status;
1836
- const cursor = row.cursor;
1837
- if (
1838
- typeof table !== 'string' ||
1839
- (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
1840
- typeof cursor !== 'number' ||
1841
- !Number.isSafeInteger(cursor)
1842
- ) {
1843
- corrupt();
1844
- }
1845
- const token = row.bootstrap_state;
1846
- if (token !== null && typeof token !== 'string') corrupt();
1847
- const rawScopes = row.effective_scopes;
1848
- let effectiveScopes: unknown;
1849
- if (rawScopes !== null) {
1850
- if (typeof rawScopes !== 'string') corrupt();
1851
- try {
1852
- effectiveScopes = JSON.parse(rawScopes);
1853
- if (effectiveScopes === null) effectiveScopes = undefined;
1854
- else if (
1855
- typeof effectiveScopes !== 'object' ||
1856
- Array.isArray(effectiveScopes) ||
1857
- !Object.values(effectiveScopes).every(
1858
- (values) =>
1859
- Array.isArray(values) &&
1860
- values.every((value) => typeof value === 'string'),
1861
- )
1862
- )
1863
- corrupt();
1864
- } catch {
1865
- corrupt();
1866
- }
1867
- }
1868
- const reasonCode = row.reason_code;
1869
- if (reasonCode !== null && typeof reasonCode !== 'string') corrupt();
1870
- const active = status === 'active';
1871
- const hasResumeToken = token !== null;
1872
- return {
1824
+ const active = unit.status === 'active';
1825
+ const pending = bootstrapping(unit);
1826
+ return definedObject({
1873
1827
  state: 'known',
1874
1828
  id,
1875
- table,
1876
- status,
1829
+ status: unit.status,
1830
+ live: unit.cursor === undefined,
1877
1831
  cursor,
1878
- hasResumeToken,
1879
- bootstrapComplete: active && cursor >= 0 && !hasResumeToken,
1880
- knownPendingPages: active && (hasResumeToken || cursor < 0),
1881
- ...(effectiveScopes !== undefined ? { effectiveScopes } : {}),
1882
- ...(reasonCode !== null ? { reasonCode } : {}),
1883
- };
1832
+ hasResumeToken: unit.bootstrapState !== undefined,
1833
+ bootstrapComplete: active && !pending,
1834
+ knownPendingPages: active && pending,
1835
+ reasonCode: unit.reasonCode,
1836
+ });
1884
1837
  };
1885
1838
  const deliveryOf = (id: string): CommitDelivery => {
1886
1839
  const pending =
@@ -1922,7 +1875,7 @@ export class SyncClient {
1922
1875
  pending,
1923
1876
  missing,
1924
1877
  },
1925
- subscriptions: (request.subscriptions ?? []).map(catchupOf),
1878
+ units: (request.units ?? []).map(catchupOf),
1926
1879
  deliveries: (request.commitIds ?? []).map(deliveryOf),
1927
1880
  };
1928
1881
  });
@@ -1992,7 +1945,7 @@ export class SyncClient {
1992
1945
  this.#discardPreviousVersion();
1993
1946
  return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1994
1947
  }
1995
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1948
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1996
1949
  this.#discardPreviousVersion();
1997
1950
  return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1998
1951
  }
@@ -2114,19 +2067,15 @@ export class SyncClient {
2114
2067
  }
2115
2068
 
2116
2069
  /**
2117
- * RFC 0005 D7: the §7.4.5 replacement-coverage predicate — every active
2118
- * subscription has `cursor >= 0` and no resume token. Window units own
2119
- * subscriptions, so their pendency is included. An empty active set is not
2120
- * completion.
2070
+ * RFC 0005 D7: the §7.4.5 replacement-coverage predicate: no active unit
2071
+ * is bootstrapping. Window units are units, so their pendency is included.
2072
+ * An empty active set is not completion.
2121
2073
  */
2122
2074
  #previousVersionCoverageComplete(): boolean {
2123
- const active = loadSubscriptions(this.#db).filter(
2124
- (sub) => sub.status === 'active',
2125
- );
2126
- if (active.length === 0) return false;
2127
- return active.every(
2128
- (sub) => sub.cursor >= 0 && sub.bootstrapState === undefined,
2075
+ const active = loadUnits(this.#db).filter(
2076
+ (unit) => unit.status === 'active',
2129
2077
  );
2078
+ return active.length > 0 && !active.some(bootstrapping);
2130
2079
  }
2131
2080
 
2132
2081
  /**
@@ -2162,7 +2111,7 @@ export class SyncClient {
2162
2111
  }
2163
2112
  const record = this.#readPreviousVersionRecord();
2164
2113
  if (record === undefined) return;
2165
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
2114
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
2166
2115
  this.#discardPreviousVersion();
2167
2116
  return;
2168
2117
  }
@@ -2257,104 +2206,40 @@ export class SyncClient {
2257
2206
  * One atomic support/product-health view. It never returns scope values,
2258
2207
  * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
2259
2208
  */
2260
- diagnosticsSnapshot(
2261
- request: ClientDiagnosticsRequest = {},
2262
- ): ClientDiagnosticsSnapshot {
2209
+ diagnosticsSnapshot(): ClientDiagnosticsSnapshot {
2263
2210
  this.#requireActive();
2264
- const expected = request.expectedSubscriptions ?? [];
2265
- if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
2266
- throw invalidRequest(
2267
- `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`,
2268
- );
2269
- }
2270
- const registered = loadSubscriptions(this.#db);
2271
- const subscriptions = new Map<string, DiagnosticSubscription>();
2272
- for (const sub of registered) {
2273
- const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
2274
- const complete =
2275
- sub.status === 'active' &&
2276
- sub.cursor >= 0 &&
2277
- sub.bootstrapState === undefined;
2278
- subscriptions.set(sub.id, {
2279
- id: sub.id,
2280
- table: sub.table,
2281
- state:
2282
- sub.status === 'revoked'
2283
- ? 'revoked'
2284
- : sub.status === 'failed'
2285
- ? 'failed'
2286
- : reset
2287
- ? 'reset'
2288
- : complete
2289
- ? 'complete'
2290
- : 'bootstrapping',
2291
- complete,
2292
- cursor: sub.cursor,
2293
- ...(sub.reasonCode !== undefined
2294
- ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
2295
- : {}),
2296
- });
2297
- }
2298
- for (const item of expected) {
2299
- if (
2300
- typeof item.id !== 'string' ||
2301
- item.id.length === 0 ||
2302
- typeof item.table !== 'string' ||
2303
- item.table.length === 0
2304
- ) {
2305
- throw invalidRequest(
2306
- 'diagnosticsSnapshot needs subscription id and table',
2307
- );
2308
- }
2309
- const registeredSubscription = subscriptions.get(item.id);
2310
- if (
2311
- registeredSubscription !== undefined &&
2312
- registeredSubscription.table !== item.table
2313
- ) {
2314
- subscriptions.set(item.id, {
2315
- id: item.id,
2316
- table: item.table,
2317
- state: 'failed',
2318
- complete: false,
2319
- reasonCode: 'client.subscription_intent_mismatch',
2320
- });
2321
- } else if (registeredSubscription === undefined) {
2322
- subscriptions.set(item.id, {
2323
- id: item.id,
2324
- table: item.table,
2325
- state: 'unregistered',
2326
- complete: false,
2327
- });
2328
- }
2211
+ const registered = loadUnits(this.#db);
2212
+ const units = {
2213
+ bootstrapping: 0,
2214
+ complete: 0,
2215
+ reset: 0,
2216
+ revoked: 0,
2217
+ failed: 0,
2218
+ };
2219
+ for (const unit of registered) {
2220
+ units[
2221
+ unit.status !== 'active'
2222
+ ? unit.status
2223
+ : !bootstrapping(unit)
2224
+ ? 'complete'
2225
+ : unit.reasonCode === 'sync.cursor_expired'
2226
+ ? 'reset'
2227
+ : 'bootstrapping'
2228
+ ] += 1;
2329
2229
  }
2330
2230
  const capturedAtMs = this.#now();
2331
2231
  const leaseState = this.#diagnosticLease(capturedAtMs);
2232
+ const round = this.#lastRound;
2332
2233
  const connectivity = !this.#transportEnabled
2333
2234
  ? 'offline'
2334
- : this.#lastRound?.status === 'succeeded'
2235
+ : round?.status === 'succeeded'
2335
2236
  ? 'online'
2336
- : this.#lastRound?.status === 'failed' &&
2337
- (this.#lastRound.causeKind === 'network' ||
2338
- this.#lastRound.causeKind === 'connect')
2237
+ : round?.status === 'failed' &&
2238
+ (round.causeKind === 'network' || round.causeKind === 'connect')
2339
2239
  ? 'offline'
2340
- : this.#lastRound?.status === 'failed' &&
2341
- this.#lastRound.httpStatus !== undefined
2240
+ : round?.status === 'failed' && round.httpStatus !== undefined
2342
2241
  ? 'online'
2343
2242
  : 'unknown';
2344
- const expectedOrder = new Map(
2345
- expected.map((item, index) => [item.id, index] as const),
2346
- );
2347
- const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
2348
- const aExpected = expectedOrder.get(a.id);
2349
- const bExpected = expectedOrder.get(b.id);
2350
- if (aExpected !== undefined || bExpected !== undefined) {
2351
- return (
2352
- (aExpected ?? Number.MAX_SAFE_INTEGER) -
2353
- (bExpected ?? Number.MAX_SAFE_INTEGER)
2354
- );
2355
- }
2356
- return a.id.localeCompare(b.id);
2357
- });
2358
2243
  return definedObject({
2359
2244
  version: CLIENT_DIAGNOSTICS_VERSION,
2360
2245
  capturedAtMs,
@@ -2380,12 +2265,20 @@ export class SyncClient {
2380
2265
  pendingOutbox: countOutbox(this.#db),
2381
2266
  },
2382
2267
  lease: leaseState,
2383
- subscriptions: allSubscriptions.slice(
2384
- 0,
2385
- MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
2386
- ),
2387
- subscriptionsTruncated:
2388
- allSubscriptions.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
2268
+ units: {
2269
+ ...units,
2270
+ reasonCodes: [
2271
+ ...new Set(
2272
+ registered.flatMap((unit) =>
2273
+ unit.reasonCode === undefined
2274
+ ? []
2275
+ : [this.#diagnosticCode(unit.reasonCode)],
2276
+ ),
2277
+ ),
2278
+ ].sort(),
2279
+ },
2280
+ activeUnits: registered.filter((unit) => unit.status === 'active').length,
2281
+ replicaCursor: replicaCursor(this.#db),
2389
2282
  lastRound: this.#lastRound,
2390
2283
  lastChange: this.#lastChange,
2391
2284
  storage: this.#diagnosticStorage(),
@@ -2417,13 +2310,10 @@ export class SyncClient {
2417
2310
  const pageSize = Number(
2418
2311
  this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0,
2419
2312
  );
2420
- const outboxBytes = Number(
2421
- this.#db.query(
2422
- `SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`,
2423
- )[0]?.bytes ?? 0,
2424
- );
2425
- const outcome = this.#db.query(
2426
- `SELECT COUNT(*)AS entries,COALESCE(SUM(LENGTH(results)+ COALESCE(LENGTH(operations),0)),0)AS bytes FROM ${OUTCOMES_TABLE}`,
2313
+ // One statement for the outbox and outcome-journal sums keeps the
2314
+ // snapshot at its pre-version-4 statement count.
2315
+ const sums = this.#db.query(
2316
+ `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}`,
2427
2317
  )[0];
2428
2318
  const blobBytes = this.#hasBlobs
2429
2319
  ? Number(
@@ -2438,9 +2328,9 @@ export class SyncClient {
2438
2328
  return {
2439
2329
  status: pressure ? 'pressure' : 'healthy',
2440
2330
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
2441
- pendingOutboxBytesApprox: Math.max(0, outboxBytes),
2442
- retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
2443
- retainedOutcomeEntries: Math.max(0, Number(outcome?.entries ?? 0)),
2331
+ pendingOutboxBytesApprox: Math.max(0, Number(sums?.outbox ?? 0)),
2332
+ retainedOutcomeBytesApprox: Math.max(0, Number(sums?.bytes ?? 0)),
2333
+ retainedOutcomeEntries: Math.max(0, Number(sums?.entries ?? 0)),
2444
2334
  blobCacheBytesApprox: Math.max(0, blobBytes),
2445
2335
  ...(pressure
2446
2336
  ? { pressureReasonCode: 'client.blob_cache_over_limit' as const }
@@ -2544,7 +2434,9 @@ export class SyncClient {
2544
2434
  if (revision !== undefined) {
2545
2435
  const event = batch.finish(revision, status);
2546
2436
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
2547
- const windows = [...new Set(event.windows.map((entry) => entry.table))];
2437
+ const windows = [
2438
+ ...new Set(event.windows.map((entry) => entry.baseKey.split('\0')[0]!)),
2439
+ ];
2548
2440
  this.#lastChange = {
2549
2441
  revision: revision.toString(),
2550
2442
  recordedAtMs: this.#now(),
@@ -2825,7 +2717,13 @@ export class SyncClient {
2825
2717
  grant.urlExpiresAtMs > this.#now()
2826
2718
  ) {
2827
2719
  try {
2828
- await transport.uploadToUrl(grant.url, bytes, mediaType, signal);
2720
+ await transport.uploadToUrl(
2721
+ blobId,
2722
+ grant.url,
2723
+ bytes,
2724
+ mediaType,
2725
+ signal,
2726
+ );
2829
2727
  return;
2830
2728
  } catch {
2831
2729
  // Grant PUT failed — stream through the direct endpoint below.
@@ -2887,11 +2785,11 @@ export class SyncClient {
2887
2785
  await this.#opChain;
2888
2786
  if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2889
2787
  const epoch = this.#transportEpoch;
2890
- const subscriptionEpoch = this.#subscriptionEpoch;
2788
+ const registrationEpoch = this.#registrationEpoch;
2891
2789
  const securityEpoch = this.#securityEpoch;
2892
- let before: SubscriptionRecord[];
2790
+ let before: UnitRecord[];
2893
2791
  try {
2894
- before = loadSubscriptions(this.#db);
2792
+ before = loadUnits(this.#db);
2895
2793
  } catch {
2896
2794
  return { proven: false, reason: 'snapshot_failed' };
2897
2795
  }
@@ -2904,14 +2802,14 @@ export class SyncClient {
2904
2802
  reason:
2905
2803
  !this.#transportEnabled || epoch !== this.#transportEpoch
2906
2804
  ? 'offline'
2907
- : subscriptionEpoch !== this.#subscriptionEpoch
2805
+ : registrationEpoch !== this.#registrationEpoch
2908
2806
  ? 'missing_coverage'
2909
2807
  : 'sync_failed',
2910
2808
  };
2911
2809
  }
2912
2810
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
2913
2811
  return { proven: false, reason: 'offline' };
2914
- if (subscriptionEpoch !== this.#subscriptionEpoch)
2812
+ if (registrationEpoch !== this.#registrationEpoch)
2915
2813
  return { proven: false, reason: 'missing_coverage' };
2916
2814
  if (
2917
2815
  this.#securityLifecycle !== 'active' ||
@@ -2926,7 +2824,7 @@ export class SyncClient {
2926
2824
  return this.#db.transaction(() => {
2927
2825
  const snapshot = this.#readSnapshot({
2928
2826
  statements: [],
2929
- subscriptions: before.map((sub) => sub.id),
2827
+ units: before.map((unit) => unit.id),
2930
2828
  commitIds: [clientCommitId],
2931
2829
  });
2932
2830
  const delivery = snapshot.deliveries[0];
@@ -2938,24 +2836,20 @@ export class SyncClient {
2938
2836
  report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
2939
2837
  };
2940
2838
  const after = new Map(
2941
- loadSubscriptions(this.#db).map((sub) => [sub.id, sub]),
2839
+ loadUnits(this.#db).map((unit) => [unit.id, unit]),
2942
2840
  );
2943
- const states = new Map(
2944
- snapshot.subscriptions.map((sub) => [sub.id, sub]),
2841
+ const complete = new Set(
2842
+ snapshot.units.flatMap((state) =>
2843
+ state.state === 'known' && state.bootstrapComplete
2844
+ ? [state.id]
2845
+ : [],
2846
+ ),
2945
2847
  );
2848
+ // A unit id names one scope map (§4.1), so the same id before and
2849
+ // after the drive is the same registration.
2946
2850
  const candidates = before.flatMap((previous) => {
2947
- const sub = after.get(previous.id);
2948
- const state = states.get(previous.id);
2949
- return sub !== undefined &&
2950
- sub.table === previous.table &&
2951
- sub.params === previous.params &&
2952
- canonicalScopeJson(sub.scopes) ===
2953
- canonicalScopeJson(previous.scopes) &&
2954
- sub.effectiveScopes !== undefined &&
2955
- state?.state === 'known' &&
2956
- state.bootstrapComplete
2957
- ? [{ table: sub.table, scopes: sub.effectiveScopes }]
2958
- : [];
2851
+ const unit = after.get(previous.id);
2852
+ return unit !== undefined && complete.has(unit.id) ? [unit] : [];
2959
2853
  });
2960
2854
  const covered = (
2961
2855
  tableName: string,
@@ -2969,10 +2863,13 @@ export class SyncClient {
2969
2863
  rowValueToJson(value),
2970
2864
  ]),
2971
2865
  );
2972
- return candidates.some((candidate) => {
2866
+ return candidates.some((unit) => {
2867
+ const scopes = covers(table, unit.scopes)
2868
+ ? pairScopes(unit.scopes, tableName, unit.echo)
2869
+ : undefined;
2973
2870
  return (
2974
- candidate.table === tableName &&
2975
- Object.keys(candidate.scopes).every((variable) => {
2871
+ scopes !== undefined &&
2872
+ Object.keys(scopes).every((variable) => {
2976
2873
  const column = table.scopeColumnByVariable.get(variable);
2977
2874
  const value = column === undefined ? undefined : row[column];
2978
2875
  return (
@@ -2981,7 +2878,7 @@ export class SyncClient {
2981
2878
  typeof value === 'boolean'
2982
2879
  );
2983
2880
  }) &&
2984
- matchesLocalScopes(table, candidate.scopes, values)
2881
+ matchesLocalScopes(table, scopes, values)
2985
2882
  );
2986
2883
  });
2987
2884
  };
@@ -3179,14 +3076,15 @@ export class SyncClient {
3179
3076
  );
3180
3077
  }
3181
3078
 
3182
- subscriptions(): SubscriptionRecord[] {
3079
+ /** Every unit in registration order (§4.1), including revoked and failed. */
3080
+ units(): UnitRecord[] {
3183
3081
  this.#requireActive();
3184
- return loadSubscriptions(this.#db);
3082
+ return loadUnits(this.#db);
3185
3083
  }
3186
3084
 
3187
- subscription(id: string): SubscriptionRecord | undefined {
3085
+ unit(id: string): UnitRecord | undefined {
3188
3086
  this.#requireActive();
3189
- return getSubscription(this.#db, id);
3087
+ return getUnit(this.#db, id);
3190
3088
  }
3191
3089
 
3192
3090
  pendingCommits(): OutboxCommit[] {
@@ -3194,94 +3092,106 @@ export class SyncClient {
3194
3092
  return listOutbox(this.#db);
3195
3093
  }
3196
3094
 
3197
- // -- subscriptions ----------------------------------------------------------
3095
+ // -- units (§4.1) -----------------------------------------------------------
3198
3096
 
3199
- subscribe(input: SubscribeInput): void {
3200
- this.subscribeMany([input]);
3097
+ /** Register one unit (§4.1) and return its id. */
3098
+ subscribe(scopes: UnitScopes): string {
3099
+ return this.subscribeMany([scopes])[0]!;
3201
3100
  }
3202
3101
 
3203
3102
  /**
3204
- * Register several subscriptions in one local transaction: the same rules
3205
- * as `subscribe` for each input, and one commit for all of them (on OPFS a
3206
- * commit costs milliseconds, so a cold start with hundreds of
3207
- * registrations pays it once). An error rolls back every registration of
3208
- * the call.
3103
+ * Register several units in one local transaction and return their ids:
3104
+ * one commit for all of them (on OPFS a commit costs milliseconds, so a
3105
+ * cold start with hundreds of units pays it once). An error rolls back every
3106
+ * registration of the call. Registering an active unit again changes
3107
+ * nothing; a revoked unit re-arms (§3.3).
3209
3108
  */
3210
- subscribeMany(inputs: readonly SubscribeInput[]): void {
3109
+ subscribeMany(units: readonly UnitScopes[]): string[] {
3211
3110
  this.#requireActive();
3212
3111
  let registered = false;
3213
- this.#db.transaction(() => {
3214
- for (const input of inputs) {
3215
- if (!this.#schema.tables.has(input.table)) {
3216
- throw new ClientSyncError(
3217
- 'sync.unknown_table',
3218
- `subscribe: unknown local table ${JSON.stringify(input.table)}`,
3219
- );
3220
- }
3221
- const existing = getSubscription(this.#db, input.id);
3222
- if (existing !== undefined) {
3223
- const sameIntent =
3224
- existing.table === input.table &&
3225
- canonicalScopeJson(existing.scopes) ===
3226
- canonicalScopeJson(input.scopes) &&
3227
- existing.params === input.params;
3228
- if (!sameIntent) {
3229
- throw new ClientSyncError(
3230
- 'client.subscription_intent_mismatch',
3231
- 'subscription id already names different table, scopes, or params',
3232
- );
3233
- }
3234
- // §3.3: a revoked registration keeps its id and intent but no
3235
- // progress. Subscribing again with the same intent re-arms it, so
3236
- // the next pull resolves its scopes from scratch. A `failed`
3237
- // registration is a configuration error and stays put.
3238
- if (existing.status !== 'revoked') continue;
3239
- }
3240
- saveSubscription(
3241
- this.#db,
3242
- definedObject({
3243
- id: input.id,
3244
- table: input.table,
3245
- scopes: input.scopes,
3246
- params: input.params,
3247
- cursor: -1,
3248
- status: 'active',
3249
- }),
3250
- );
3251
- registered = true;
3252
- }
3253
- });
3254
- if (!registered) return;
3255
- this.#subscriptionEpoch += 1;
3256
- this.#setSyncNeeded(true);
3257
- this.#emitSyncIntent({ kind: 'interactive' });
3258
- this.#emitDiagnostics();
3112
+ const ids = this.#db.transaction(() =>
3113
+ units.map((scopes) => {
3114
+ const { id, changed } = this.#holdUnit(scopes, true);
3115
+ registered ||= changed;
3116
+ return id;
3117
+ }),
3118
+ );
3119
+ if (registered) {
3120
+ this.#registrationEpoch += 1;
3121
+ this.#setSyncNeeded(true);
3122
+ this.#emitSyncIntent({ kind: 'interactive' });
3123
+ this.#emitDiagnostics();
3124
+ }
3125
+ return ids;
3259
3126
  }
3260
3127
 
3128
+ /**
3129
+ * Release the explicit reference to a unit. The unit leaves the
3130
+ * registration list when no window base holds it (§4.1); its rows stay.
3131
+ */
3261
3132
  unsubscribe(id: string): void {
3262
3133
  this.#requireActive();
3263
- if (getSubscription(this.#db, id) === undefined) return;
3264
- deleteSubscription(this.#db, id);
3265
- this.#subscriptionEpoch += 1;
3134
+ const unit = getUnit(this.#db, id);
3135
+ if (unit === undefined || !unit.explicit) return;
3136
+ if (windowRefs(this.#db, id).length > 0) {
3137
+ saveUnit(this.#db, { ...unit, explicit: false });
3138
+ return;
3139
+ }
3140
+ deleteUnit(this.#db, id);
3141
+ this.#registrationEpoch += 1;
3142
+ if (unit.status !== 'active') return;
3266
3143
  this.#setSyncNeeded(true);
3267
3144
  this.#emitSyncIntent({ kind: 'interactive' });
3268
3145
  this.#emitDiagnostics();
3269
3146
  }
3270
3147
 
3271
- // -- windowed subscriptions (§4.8) ------------------------------------------
3148
+ /**
3149
+ * Take one reference on a unit (§4.1): validate the scope map, register
3150
+ * a new unit catching up with cursor `-1`, re-arm a revoked one (§3.3).
3151
+ * `changed` reports whether the registration list changed.
3152
+ */
3153
+ #holdUnit(
3154
+ scopes: UnitScopes,
3155
+ explicit: boolean,
3156
+ ): { id: string; changed: boolean } {
3157
+ const entries = Object.entries(scopes ?? {});
3158
+ if (
3159
+ entries.length === 0 ||
3160
+ entries.some(([, value]) => typeof value !== 'string' || value === '*') ||
3161
+ ![...this.#schema.tables.values()].some((table) => covers(table, scopes))
3162
+ )
3163
+ throw new ClientSyncError(
3164
+ 'sync.invalid_subscription',
3165
+ 'a unit names one non-wildcard value per variable and covers a table',
3166
+ );
3167
+ const id = unitId(scopes);
3168
+ const existing = getUnit(this.#db, id);
3169
+ if (existing !== undefined && existing.status !== 'revoked') {
3170
+ if (explicit && !existing.explicit)
3171
+ saveUnit(this.#db, { ...existing, explicit });
3172
+ return { id, changed: false };
3173
+ }
3174
+ deletePendingEviction(this.#db, id);
3175
+ saveUnit(this.#db, {
3176
+ id,
3177
+ scopes: Object.fromEntries(entries),
3178
+ explicit: explicit || existing?.explicit === true,
3179
+ status: 'active',
3180
+ cursor: -1,
3181
+ seeded: [],
3182
+ });
3183
+ return { id, changed: true };
3184
+ }
3185
+
3186
+ // -- windows (§4.8) ---------------------------------------------------------
3272
3187
 
3273
3188
  /**
3274
- * Set the live window units for a base (§4.8): a value-sharded family of
3275
- * subscriptions, one per unit. Computes the diff against the registry —
3276
- * added units get fresh subscriptions (image-lane bootstrap on the next
3277
- * sync); removed units are unsubscribed with their first eviction chunk
3278
- * in one local transaction (E1–E4). Idempotent: calling with the same units is a
3279
- * no-op. Re-entry (a unit removed then re-added) cancels any deferred
3280
- * eviction and fresh-bootstraps.
3281
- *
3282
- * The change takes effect on the next `sync()`/socket round — the pull's
3283
- * subscription list (now with the added unit, without the removed one)
3284
- * re-registers realtime at round end (§8.7). No socket cycle needed.
3189
+ * Set the windowed-in values of a base (§4.8): one unit per value. Added
3190
+ * values take a reference on their unit (a new unit bootstraps on the next
3191
+ * sync); removed values release theirs, and a unit no reference holds leaves
3192
+ * the registration list fused with its first eviction chunk (E1–E4).
3193
+ * Idempotent; re-entry cancels a deferred eviction and fresh-bootstraps.
3194
+ * The change reaches the server with the next round's list (§8.7).
3285
3195
  */
3286
3196
  async setWindow(base: WindowBase, units: readonly string[]): Promise<void> {
3287
3197
  await this.setWindowCommand(base, units);
@@ -3293,147 +3203,121 @@ export class SyncClient {
3293
3203
  units: readonly string[],
3294
3204
  ): Promise<CommandResult<void>> {
3295
3205
  this.#requireActive();
3296
- const table = this.#table(base.table);
3297
- if (!table.scopeColumnByVariable.has(base.variable)) {
3298
- throw invalidRequest(
3299
- `${base.table}: unknown scope variable ${base.variable} (§4.8)`,
3300
- );
3301
- }
3302
- // Serialize the whole window edit: it spans an `await deriveSubId` between
3303
- // db transactions, so without the chain a delta apply (or a concurrent
3304
- // setWindow) could interleave its transactions and corrupt the registry.
3305
3206
  let changed = false;
3306
- let widened = false;
3207
+ // Serialize the whole edit: a shrink yields between eviction chunks, so
3208
+ // without the chain a delta apply or another setWindow could interleave.
3307
3209
  await this.#serialize(async () => {
3308
3210
  const baseKey = windowBaseKey(base);
3309
3211
  const wanted = new Set(units);
3310
3212
  const live = loadWindowUnits(this.#db, baseKey);
3311
- const liveByUnit = new Map(live.map((u) => [u.unit, u.subId]));
3312
-
3313
- // Widen: units wanted but not live → fresh subscription + registry row.
3314
- for (const unit of wanted) {
3315
- if (liveByUnit.has(unit)) continue;
3316
- const subId = await deriveSubId(base, unit);
3213
+ const held = new Set(live.map((entry) => entry.value));
3214
+ for (const value of wanted) {
3215
+ if (held.has(value)) continue;
3317
3216
  this.#applyBatch((batch) => {
3318
- this.#db.transaction(() => {
3319
- // Re-entry cancels any deferred eviction for this sub id.
3320
- deletePendingEviction(this.#db, subId);
3321
- insertWindowUnit(this.#db, baseKey, unit, subId);
3322
- saveSubscription(
3323
- this.#db,
3324
- definedObject({
3325
- id: subId,
3326
- table: base.table,
3327
- scopes: unitScopes(base, unit),
3328
- params: base.params,
3329
- cursor: -1,
3330
- status: 'active',
3331
- }),
3332
- );
3333
- });
3334
- this.#needsPull = true;
3335
- batch.window(baseKey, base.table, unit);
3217
+ const { id, changed: registered } = this.#holdUnit(
3218
+ windowUnitScopes(base, value),
3219
+ false,
3220
+ );
3221
+ this.#db.exec(
3222
+ `INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`,
3223
+ [baseKey, value, id],
3224
+ );
3225
+ if (registered) this.#needsPull = true;
3226
+ batch.window(baseKey, value);
3336
3227
  batch.status();
3337
3228
  });
3338
3229
  changed = true;
3339
- widened = true;
3340
- this.#subscriptionEpoch += 1;
3230
+ this.#registrationEpoch += 1;
3341
3231
  }
3342
-
3343
- // Shrink: units live but not wanted → unsubscribe fused with eviction.
3344
- for (const { unit, subId } of live) {
3345
- if (wanted.has(unit)) continue;
3346
- await this.#evictUnit(baseKey, base, unit, subId);
3232
+ for (const { value, unitId: id } of live) {
3233
+ if (wanted.has(value)) continue;
3234
+ await this.#releaseWindowUnit(baseKey, value, id);
3347
3235
  changed = true;
3348
- this.#subscriptionEpoch += 1;
3236
+ this.#registrationEpoch += 1;
3349
3237
  }
3350
3238
  });
3351
3239
  const effects: CommandEffects = {
3352
3240
  sync:
3353
- this.#transportEnabled && (changed || widened)
3241
+ this.#transportEnabled && changed
3354
3242
  ? { kind: 'interactive' }
3355
3243
  : { kind: 'none' },
3356
3244
  };
3357
- if (effects.sync.kind === 'interactive') {
3358
- this.#emitSyncIntent(effects.sync);
3359
- }
3245
+ if (effects.sync.kind === 'interactive') this.#emitSyncIntent(effects.sync);
3360
3246
  return { value: undefined, effects };
3361
3247
  }
3362
3248
 
3363
3249
  /**
3364
- * The completeness oracle (§4.8 I3): which units of a base are windowed-in
3365
- * locally, which of those are still bootstrap-pending, and thereby the
3366
- * per-unit verdict a live query renders "may be partial" from. A query
3367
- * whose scope footprint includes an un-windowed OR still-pending unit is
3368
- * NOT answerable in full — the host widens or shows partial, never
3369
- * silently-complete. Registration alone is not completeness: a unit is
3370
- * pending until its subscription completes a bootstrap round (cursor
3371
- * advances past -1 with no resume token held).
3250
+ * The completeness oracle (§4.8): which values of a base are windowed-in
3251
+ * and which of those are pending. A value is complete once its unit is
3252
+ * active and no longer bootstrapping; registration alone is not
3253
+ * completeness.
3372
3254
  */
3373
3255
  windowState(base: WindowBase): WindowState {
3374
3256
  this.#requireActive();
3375
- const baseKey = windowBaseKey(base);
3376
- const live = loadWindowUnits(this.#db, baseKey);
3377
- const pending: string[] = [];
3378
- for (const { unit, subId } of live) {
3379
- const sub = getSubscription(this.#db, subId);
3380
- if (
3381
- sub === undefined ||
3382
- sub.status !== 'active' ||
3383
- sub.cursor < 0 ||
3384
- sub.bootstrapState !== undefined
3385
- ) {
3386
- pending.push(unit);
3387
- }
3388
- }
3389
- return { units: live.map((u) => u.unit), pending };
3257
+ const live = loadWindowUnits(this.#db, windowBaseKey(base));
3258
+ const pending = live.flatMap(({ value, unitId: id }) => {
3259
+ const unit = getUnit(this.#db, id);
3260
+ return unit === undefined ||
3261
+ unit.status !== 'active' ||
3262
+ bootstrapping(unit)
3263
+ ? [value]
3264
+ : [];
3265
+ });
3266
+ return { units: live.map((entry) => entry.value), pending };
3390
3267
  }
3391
3268
 
3392
3269
  /**
3393
- * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
3394
- * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
3395
- * pending outbox commit (E1); if any pin remains, records a deferred
3396
- * eviction retried on the next outbox drain. Discards the subscription's
3397
- * cursor/resume/effective-echo (E3) and its version state with the rows
3398
- * (E2). Emits the evicted table's invalidation keys (I1). Fail-closed:
3399
- * with no local scope-column mapping, surfaces a configuration error and
3400
- * evicts nothing (§4.8/§3.3).
3270
+ * §4.8: release a window value's reference. When no reference holds the
3271
+ * unit, unregister it fused with its first eviction chunk (E3): delete the
3272
+ * rows of every covered table matching the persisted echo, except rows
3273
+ * pinned by the outbox (E1) or owned by another unit (§3.3), and park the
3274
+ * per-table scopes of what remains in the pending-eviction registry. Fails
3275
+ * closed without a local scope-column mapping.
3401
3276
  */
3402
- async #evictUnit(
3277
+ async #releaseWindowUnit(
3403
3278
  baseKey: string,
3404
- base: WindowBase,
3405
- unit: string,
3406
- subId: string,
3279
+ value: string,
3280
+ id: string,
3407
3281
  ): Promise<void> {
3408
- const table = this.#table(base.table);
3409
- const sub = getSubscription(this.#db, subId);
3410
- // The rows a unit holds live under its LAST effective scopes if it ever
3411
- // synced; before first sync, the requested unit scopes are the match.
3412
- const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
3413
- const pinned = this.#pinnedRowIds(base.table);
3414
3282
  let remaining = false;
3415
3283
  this.#applyBatch((batch) => {
3416
- this.#db.transaction(() => {
3284
+ this.#db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
3285
+ baseKey,
3286
+ value,
3287
+ ]);
3288
+ batch.window(baseKey, value);
3289
+ batch.status();
3290
+ const unit = getUnit(this.#db, id);
3291
+ if (
3292
+ unit === undefined ||
3293
+ unit.explicit ||
3294
+ windowRefs(this.#db, id).length > 0
3295
+ )
3296
+ return;
3297
+ const units = loadUnits(this.#db);
3298
+ deleteUnit(this.#db, id);
3299
+ this.#needsPull = true;
3300
+ for (const table of this.#schema.tables.values()) {
3301
+ const effective = covers(table, unit.scopes)
3302
+ ? pairScopes(unit.scopes, table.name, unit.echo)
3303
+ : undefined;
3304
+ if (unit.echo === undefined || effective === undefined) continue;
3417
3305
  const result = evictScopedRows(
3418
3306
  this.#db,
3419
3307
  table,
3420
3308
  effective,
3421
- this.#scopeOwners(base.table, subId),
3422
- pinned,
3309
+ unitOwners(units, table, id),
3310
+ this.#pinnedRowIds(table.name),
3423
3311
  );
3424
- remaining = result.remaining;
3425
- deleteWindowUnit(this.#db, baseKey, unit);
3426
- deleteSubscription(this.#db, subId);
3427
- if (result.deferred) {
3428
- savePendingEviction(this.#db, subId, base.table, effective);
3429
- } else {
3430
- deletePendingEviction(this.#db, subId);
3431
- }
3432
- });
3433
- batch.scopeMap(table, effective);
3434
- batch.window(baseKey, table.name, unit);
3435
- this.#needsPull = true;
3436
- batch.status();
3312
+ remaining ||= result.remaining;
3313
+ if (result.deferred)
3314
+ savePendingEviction(this.#db, {
3315
+ unitId: id,
3316
+ table: table.name,
3317
+ effective,
3318
+ });
3319
+ batch.scopeMap(table, effective);
3320
+ }
3437
3321
  });
3438
3322
  if (remaining) {
3439
3323
  await yieldToHost();
@@ -3442,28 +3326,26 @@ export class SyncClient {
3442
3326
  }
3443
3327
 
3444
3328
  /**
3445
- * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
3446
- * unit's rows are removed once no pending commit references them; a unit
3447
- * that re-entered the window in the meantime has no pending record left.
3329
+ * §4.8 E1: continue deferred evictions after the outbox drains or between
3330
+ * chunks. A unit that re-entered the window has no pending entry left.
3448
3331
  */
3449
3332
  async #drainPendingEvictions(): Promise<void> {
3450
- const pending = loadPendingEvictions(this.#db);
3451
- if (pending.length === 0) return;
3452
- for (const entry of pending) {
3333
+ for (const entry of loadPendingEvictions(this.#db)) {
3453
3334
  const table = this.#schema.tables.get(entry.table);
3454
3335
  if (table === undefined) {
3455
- deletePendingEviction(this.#db, entry.subId);
3336
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
3456
3337
  continue;
3457
3338
  }
3458
3339
  let remaining: boolean;
3459
3340
  do {
3460
3341
  if (
3461
3342
  !loadPendingEvictions(this.#db).some(
3462
- (item) => item.subId === entry.subId,
3343
+ (item) =>
3344
+ item.unitId === entry.unitId && item.table === entry.table,
3463
3345
  )
3464
3346
  )
3465
3347
  break;
3466
- // Local writes may add pins while the worker yields between chunks.
3348
+ // Local writes may add pins while the host yields between chunks.
3467
3349
  const pinned = this.#pinnedRowIds(entry.table);
3468
3350
  remaining = false;
3469
3351
  this.#applyBatch((batch) => {
@@ -3471,11 +3353,12 @@ export class SyncClient {
3471
3353
  this.#db,
3472
3354
  table,
3473
3355
  entry.effective,
3474
- this.#scopeOwners(entry.table, entry.subId),
3356
+ unitOwners(loadUnits(this.#db), table, entry.unitId),
3475
3357
  pinned,
3476
3358
  );
3477
3359
  remaining = result.remaining;
3478
- if (!result.deferred) deletePendingEviction(this.#db, entry.subId);
3360
+ if (!result.deferred)
3361
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
3479
3362
  batch.scopeMap(table, entry.effective);
3480
3363
  });
3481
3364
  if (remaining) await yieldToHost();
@@ -3483,23 +3366,6 @@ export class SyncClient {
3483
3366
  }
3484
3367
  }
3485
3368
 
3486
- /**
3487
- * §3.3/§4.8/§5.6 row ownership: the effective scopes of every other
3488
- * active subscription on `table` that holds rows (`cursor >= 0`). A
3489
- * scoped delete keeps every row one of them still covers.
3490
- */
3491
- #scopeOwners(table: string, exceptId: string): ScopeMap[] {
3492
- return loadSubscriptions(this.#db).flatMap((sub) =>
3493
- sub.id !== exceptId &&
3494
- sub.table === table &&
3495
- sub.status === 'active' &&
3496
- sub.cursor >= 0 &&
3497
- sub.effectiveScopes !== undefined
3498
- ? [sub.effectiveScopes]
3499
- : [],
3500
- );
3501
- }
3502
-
3503
3369
  /**
3504
3370
  * §4.8 E1: primary keys of `table` referenced by any still-pending outbox
3505
3371
  * commit — rows that MUST NOT be evicted until the commit drains.
@@ -3949,7 +3815,7 @@ export class SyncClient {
3949
3815
  }
3950
3816
 
3951
3817
  const pending = listOutbox(this.#db);
3952
- const resetSubscriptions = loadSubscriptions(this.#db).length;
3818
+ const resetSubscriptions = loadUnits(this.#db).length;
3953
3819
  const priorUpgrading = this.#upgrading;
3954
3820
  const priorNeedsPull = this.#needsPull;
3955
3821
  try {
@@ -3959,7 +3825,7 @@ export class SyncClient {
3959
3825
  batch.status();
3960
3826
  this.#discardAcknowledgedRows();
3961
3827
  dropAndRecreateSyncedTables(this.#db, this.#schema);
3962
- resetSubscriptionsForBump(this.#db);
3828
+ resetUnits(this.#db);
3963
3829
  for (const table of this.#schema.tables.values()) {
3964
3830
  batch.table(table.name);
3965
3831
  }
@@ -4098,7 +3964,7 @@ export class SyncClient {
4098
3964
  const baseBytes =
4099
3965
  byteCap === undefined
4100
3966
  ? 0
4101
- : encodeMessage({
3967
+ : encodeRequest({
4102
3968
  wireVersion: PROTOCOL_WIRE_VERSION,
4103
3969
  msgKind: 'request',
4104
3970
  frames: [header, pull],
@@ -4191,7 +4057,7 @@ export class SyncClient {
4191
4057
  const frame =
4192
4058
  byteCap === undefined
4193
4059
  ? 0
4194
- : encodeMessage({
4060
+ : encodeRequest({
4195
4061
  wireVersion: PROTOCOL_WIRE_VERSION,
4196
4062
  msgKind: 'request',
4197
4063
  frames: [header, pushFrame, pull],
@@ -4314,7 +4180,7 @@ export class SyncClient {
4314
4180
  return this.#sync();
4315
4181
  }
4316
4182
 
4317
- /** `signal` is the `syncUntilIdle` deadline (§7.7); `sync()` has none. */
4183
+ /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
4318
4184
  #sync(signal?: AbortSignal): Promise<SyncSummary> {
4319
4185
  this.#requireActive();
4320
4186
  if (this.#syncOutstanding) {
@@ -4479,13 +4345,18 @@ export class SyncClient {
4479
4345
  clientId: this.#clientId,
4480
4346
  schemaVersion: this.#schema.version,
4481
4347
  logEpoch: logEpoch,
4348
+ outboxId: getMeta(this.#db, 'outboxId'),
4482
4349
  });
4483
- const pull: RequestFrame = {
4350
+ // The registration fields are set after encoding (below).
4351
+ const pull: PullHeaderFrame = {
4484
4352
  type: 'PULL_HEADER',
4485
4353
  limitCommits: limits?.limitCommits ?? 0,
4486
4354
  limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
4487
4355
  maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
4488
4356
  accept: this.#acceptMask(),
4357
+ cursor: -1,
4358
+ registrationDigest: registrationDigest([]),
4359
+ echoDigest: new Uint8Array(),
4489
4360
  };
4490
4361
  const {
4491
4362
  pushFrames,
@@ -4515,9 +4386,19 @@ export class SyncClient {
4515
4386
  // encryption await must not make the final request exceed the byte
4516
4387
  // budget, and the reset epoch must be the one the response apply checks.
4517
4388
  const resetEpoch = this.#localResetEpoch;
4518
- const subs = loadSubscriptions(this.#db).filter(
4519
- (sub) => sub.status === 'active',
4389
+ const registered = loadUnits(this.#db).filter(
4390
+ (unit) => unit.status === 'active',
4391
+ );
4392
+ pull.cursor = replicaCursor(this.#db);
4393
+ pull.registrationDigest = registrationDigest(
4394
+ registered.map((unit) => unit.scopes),
4520
4395
  );
4396
+ pull.echoDigest = hexToBytes(getMeta(this.#db, ECHO_DIGEST_KEY) ?? '');
4397
+ // §4.1: the list travels when it changed since the server stored it,
4398
+ // after `unregistered` and after a reset (both clear the stored digest).
4399
+ const travels =
4400
+ getMeta(this.#db, REGISTERED_DIGEST_KEY) !==
4401
+ bytesToHex(pull.registrationDigest);
4521
4402
  // §1.5: a kept round-failure code rides every request until a round
4522
4403
  // completes, immediately after REQ_HEADER.
4523
4404
  const report = this.#roundFailureCode;
@@ -4527,29 +4408,35 @@ export class SyncClient {
4527
4408
  ? [{ type: 'ROUND_FAILURE' as const, code: report }]
4528
4409
  : []),
4529
4410
  pull,
4530
- ...subs.map(
4531
- (sub): RequestFrame =>
4532
- definedObject({
4533
- type: 'SUBSCRIPTION',
4534
- id: sub.id,
4535
- table: sub.table,
4536
- scopes: sub.scopes,
4537
- params: sub.params,
4538
- cursor: sub.cursor,
4539
- bootstrapState: sub.bootstrapState,
4540
- }),
4411
+ ...(travels
4412
+ ? registered.map(
4413
+ (unit): RequestFrame => ({ type: 'UNIT', scopes: unit.scopes }),
4414
+ )
4415
+ : []),
4416
+ // §4.3: one PROGRESS per catching-up unit, in registration order.
4417
+ ...registered.flatMap((unit): RequestFrame[] =>
4418
+ unit.cursor === undefined
4419
+ ? []
4420
+ : [
4421
+ definedObject({
4422
+ type: 'PROGRESS',
4423
+ id: unit.id,
4424
+ cursor: unit.cursor,
4425
+ bootstrapState: unit.bootstrapState,
4426
+ }),
4427
+ ],
4541
4428
  ),
4542
4429
  ];
4543
4430
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
4544
- // sit between them and the pull/subscription tail (§1.5 ordering).
4431
+ // sit between them and the pull/unit/progress tail (§1.5 ordering).
4545
4432
  const lead = fixedFrames.slice(0, report !== undefined ? 2 : 1);
4546
4433
  let admitted = pushFrames.length;
4547
4434
  let deferred = encodedDeferred;
4548
4435
  if (byteCap !== undefined) {
4549
4436
  // The fixed frames encode as envelope + fixed frames + END; each
4550
4437
  // admitted push frame adds its own (5 + payload). Trimming the tail
4551
- // re-fits the request to the final subscription state.
4552
- const fixedBytes = encodeMessage({
4438
+ // re-fits the request to the final registration state.
4439
+ const fixedBytes = encodeRequest({
4553
4440
  wireVersion: PROTOCOL_WIRE_VERSION,
4554
4441
  msgKind: 'request',
4555
4442
  frames: fixedFrames,
@@ -4579,22 +4466,19 @@ export class SyncClient {
4579
4466
  ...pushFrames,
4580
4467
  ...fixedFrames.slice(lead.length),
4581
4468
  ];
4582
- const requestBytes = encodeMessage({
4469
+ const requestBytes = encodeRequest({
4583
4470
  wireVersion: PROTOCOL_WIRE_VERSION,
4584
4471
  msgKind: 'request',
4585
4472
  frames,
4586
4473
  });
4587
4474
  const responseBytes = await this.#roundTrip(requestBytes, signal);
4588
- const message = decodeMessage(responseBytes);
4589
- if (message.msgKind !== 'response') {
4590
- throw invalidRequest('transport returned a non-response message');
4591
- }
4475
+ const message = decodeResponse(responseBytes);
4592
4476
  // §1.5: a complete, decodable response ends the report obligation.
4593
4477
  this.#roundFailureCode = undefined;
4594
4478
  const summary = await this.#processResponse(
4595
4479
  message,
4596
4480
  outbox,
4597
- subs,
4481
+ bytesToHex(pull.registrationDigest),
4598
4482
  'pull',
4599
4483
  resetEpoch,
4600
4484
  signal,
@@ -4608,8 +4492,8 @@ export class SyncClient {
4608
4492
  : { state: 'complete' },
4609
4493
  );
4610
4494
  this.#retryDelayMs = 250;
4611
- // §4.7: a subscription that still holds a resume token needs another
4612
- // round, also when the drive that started its bootstrap ends early.
4495
+ // §7.1: a unit still catching up needs another round, also when the
4496
+ // drive that started its bootstrap ends early.
4613
4497
  if (summary.bootstrapping.length > 0) this.#setSyncNeeded(true);
4614
4498
  if (deferred > 0) {
4615
4499
  // §6.1 splitBatch remainder: more queued commits than this request
@@ -4623,7 +4507,7 @@ export class SyncClient {
4623
4507
  // failure the server could not see — keep its code for the next request.
4624
4508
  const unseen = this.#unseenRoundFailureCode(caught);
4625
4509
  if (unseen !== undefined) this.#roundFailureCode = unseen;
4626
- // §7.7: a round the drive deadline aborted ends with the deadline's
4510
+ // §7.8: a round the drive deadline aborted ends with the deadline's
4627
4511
  // error, whichever transport call observed the abort.
4628
4512
  const error: unknown = signal?.aborted === true ? signal.reason : caught;
4629
4513
  // §7.3.5: a request-level lease code stops-and-surfaces — record it
@@ -4697,7 +4581,7 @@ export class SyncClient {
4697
4581
  * Callers that arrive during the same drive with the same budget share that
4698
4582
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
4699
4583
  *
4700
- * §7.7: one drive is bounded by a total deadline (`timeoutMs`, default
4584
+ * §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
4701
4585
  * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
4702
4586
  * aborts a socket round in flight; the round budget does not bound elapsed
4703
4587
  * time, and a transport that never answers must not hang the caller.
@@ -4711,7 +4595,7 @@ export class SyncClient {
4711
4595
  typeof options === 'number'
4712
4596
  ? SYNC_IDLE_TIMEOUT_MS
4713
4597
  : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
4714
- // §7.7: an explicit budget is a strict positive round count. Zero,
4598
+ // §7.8: an explicit budget is a strict positive round count. Zero,
4715
4599
  // fractional, and out-of-range values are caller errors.
4716
4600
  requireRoundBudget(maxRounds);
4717
4601
  if (
@@ -4807,10 +4691,7 @@ export class SyncClient {
4807
4691
  // The race already rejected; stop spending rounds on a dead drive.
4808
4692
  if (expired) throw expiredError();
4809
4693
  const before = JSON.stringify(
4810
- loadSubscriptions(this.#db).map((sub) => [
4811
- sub.id,
4812
- sub.bootstrapState,
4813
- ]),
4694
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4814
4695
  );
4815
4696
  const last = await this.#sync(controller.signal);
4816
4697
  // Historical counters accumulate; current readiness (`bootstrapping`,
@@ -4837,10 +4718,7 @@ export class SyncClient {
4837
4718
  last.bootstrapping.length > 0 &&
4838
4719
  before !==
4839
4720
  JSON.stringify(
4840
- loadSubscriptions(this.#db).map((sub) => [
4841
- sub.id,
4842
- sub.bootstrapState,
4843
- ]),
4721
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4844
4722
  )
4845
4723
  )
4846
4724
  round = -1;
@@ -5259,8 +5137,7 @@ export class SyncClient {
5259
5137
  return;
5260
5138
  }
5261
5139
  try {
5262
- const message = decodeMessage(bytes);
5263
- if (message.msgKind !== 'response') return;
5140
+ const message = decodeResponse(bytes);
5264
5141
  // §8.2: deltas apply like pull responses; ack after apply.
5265
5142
  await this.#processResponse(message, [], undefined, 'delta');
5266
5143
  } catch {
@@ -5276,25 +5153,23 @@ export class SyncClient {
5276
5153
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
5277
5154
  }
5278
5155
 
5279
- /** Ack the highest cursor that is contiguously applied for every sub. */
5156
+ /** §8.2: after a pull round, ack the replica cursor while it is `>= 0`. */
5280
5157
  #ackAfterPull(): void {
5281
- if (this.#socket === undefined) return;
5282
- const cursors = loadSubscriptions(this.#db)
5283
- .filter(
5284
- (sub) => sub.status === 'active' && sub.bootstrapState === undefined,
5285
- )
5286
- .map((sub) => sub.cursor)
5287
- .filter((cursor) => cursor >= 0);
5288
- if (cursors.length === 0) return;
5289
- this.#sendAck(Math.min(...cursors));
5158
+ const cursor = replicaCursor(this.#db);
5159
+ if (this.#socket !== undefined && cursor >= 0) this.#sendAck(cursor);
5290
5160
  }
5291
5161
 
5292
5162
  // -- response processing ------------------------------------------------------
5293
5163
 
5164
+ /**
5165
+ * Apply one response (§1.6) or realtime delta (§8.2). `sentDigest` is the
5166
+ * hex registration digest of the pull this response answers; the server
5167
+ * stores that list once the round completes (§4.1).
5168
+ */
5294
5169
  async #processResponse(
5295
5170
  message: ResponseMessage,
5296
5171
  sentCommits: readonly OutboxCommit[],
5297
- sentSubs: readonly SubscriptionRecord[] | undefined,
5172
+ sentDigest: string | undefined,
5298
5173
  mode: 'pull' | 'delta',
5299
5174
  resetEpoch: number = this.#localResetEpoch,
5300
5175
  signal?: AbortSignal,
@@ -5303,9 +5178,6 @@ export class SyncClient {
5303
5178
  const commitsById = new Map(
5304
5179
  sentCommits.map((commit) => [commit.clientCommitId, commit]),
5305
5180
  );
5306
- const subsById = new Map(
5307
- (sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]),
5308
- );
5309
5181
  const rejectionDetailsByCommit = new Map<
5310
5182
  string,
5311
5183
  ReadonlyMap<number, RejectionDetails>
@@ -5330,12 +5202,6 @@ export class SyncClient {
5330
5202
  if (header?.type !== 'RESP_HEADER') {
5331
5203
  throw invalidRequest('missing RESP_HEADER');
5332
5204
  }
5333
- if (message.wireVersion < 2) {
5334
- throw new ClientSyncError(
5335
- 'client.invalid_host_response',
5336
- 'the server response does not carry wire version 2 log-epoch state',
5337
- );
5338
- }
5339
5205
  if (header.requiredSchemaVersion !== undefined) {
5340
5206
  // §1.6 schema floor: nothing else was processed — stop syncing and
5341
5207
  // surface the upgrade requirement. A live-round floor always stops:
@@ -5378,20 +5244,13 @@ export class SyncClient {
5378
5244
 
5379
5245
  let section: OpenSection | undefined;
5380
5246
  let errorFrame: ClientSyncError | undefined;
5247
+ let liveStart: LiveStartFrame | undefined;
5248
+ let liveEnded = false;
5381
5249
  let deltaCursor = -1;
5382
5250
  let deltaDropped = false;
5383
- // §8.2: a delta section applies only to a locally active subscription
5384
- // that holds a cursor and no resume token. A subscription at cursor -1
5385
- // (never synced, reset, or rebootstrapped) bootstraps on its own pull.
5386
- const skipsSection = (sub: SubscriptionRecord | undefined) =>
5387
- sub === undefined ||
5388
- (mode === 'delta' &&
5389
- (sub.status !== 'active' ||
5390
- sub.cursor < 0 ||
5391
- sub.bootstrapState !== undefined));
5392
- const incompleteSubscriptions = new Set(
5393
- mode === 'pull' ? subsById.keys() : [],
5394
- );
5251
+ // §4.5 client application: the units whose persisted echo a live-section
5252
+ // change must match, fixed at LIVE_START after every SUB_END persisted.
5253
+ let receivers: UnitRecord[] = [];
5395
5254
 
5396
5255
  // §5.4/§5.5: queue every segment download of this response, so a paged
5397
5256
  // bootstrap overlaps its page fetches instead of paying one blocking round
@@ -5400,18 +5259,18 @@ export class SyncClient {
5400
5259
  // holds at most four bodies, the one being applied and three ahead. The
5401
5260
  // loop takes each body out of the map before applying it and tops the
5402
5261
  // window up at the next descriptor. Eligibility mirrors the loop: a
5403
- // descriptor outside an applied section, inside a skipped delta section,
5404
- // or from an unconfigured downloader is never queued, and a failure is
5405
- // only observed where the loop awaits it. A promise left over because an
5406
- // earlier frame ended apply is handled at creation, never unhandled.
5407
- const queued: [SegmentRefFrame, SubscriptionRecord][] = [];
5262
+ // descriptor outside an applied section or from an unconfigured
5263
+ // downloader is never queued, and a failure is only observed where the
5264
+ // loop awaits it. A promise left over because an earlier frame ended
5265
+ // apply is handled at creation, never unhandled.
5266
+ const queued: [SegmentRefFrame, UnitScopes][] = [];
5408
5267
  const prefetched = new Map<SegmentRefFrame, Promise<Uint8Array>>();
5409
5268
  const prefetch = () => {
5410
5269
  for (let next; prefetched.size < 4 && (next = queued.shift());) {
5411
- const [frame, sub] = next;
5270
+ const [frame, scopes] = next;
5412
5271
  const pending = this.#downloadSegment(
5413
5272
  frame,
5414
- sub,
5273
+ scopes,
5415
5274
  (bytes) => {
5416
5275
  // Only the descriptor the loop is applying reports bytes; a
5417
5276
  // sibling still in flight would overwrite its progress.
@@ -5425,92 +5284,31 @@ export class SyncClient {
5425
5284
  }
5426
5285
  };
5427
5286
  let reporting: SegmentRefFrame | undefined;
5428
- const deleteKey = (commitSeq: number, table: string, rowId: string) =>
5429
- `${commitSeq}\u0000${table}\u0000${rowId}`;
5430
- {
5431
- let openSub: SubscriptionRecord | undefined;
5287
+ if (mode === 'pull') {
5288
+ let open: UnitRecord | undefined;
5432
5289
  for (const frame of message.frames) {
5433
5290
  if (frame.type === 'SUB_START') {
5434
- const sub = subsById.get(frame.id);
5435
- openSub = skipsSection(sub) ? undefined : sub;
5436
- } else if (frame.type === 'SUB_END') {
5437
- openSub = undefined;
5291
+ const unit = getUnit(this.#db, frame.id);
5292
+ open = unit?.status === 'active' ? unit : undefined;
5293
+ } else if (frame.type === 'SUB_END' || frame.type === 'LIVE_START') {
5294
+ open = undefined;
5438
5295
  } else if (frame.type === 'ERROR') {
5439
5296
  break; // the round fails at this frame: later refs are not fetched
5440
5297
  } else if (
5441
5298
  frame.type === 'SEGMENT_REF' &&
5442
- openSub !== undefined &&
5299
+ open !== undefined &&
5443
5300
  this.#config.segments !== undefined &&
5444
5301
  !(
5445
5302
  frame.mediaType === 'sqlite' &&
5446
5303
  (this.#acceptMask() & ACCEPT_SQLITE) === 0
5447
5304
  )
5448
5305
  ) {
5449
- queued.push([frame, openSub]);
5306
+ queued.push([frame, open.scopes]);
5450
5307
  }
5451
5308
  }
5452
5309
  prefetch();
5453
5310
  }
5454
5311
 
5455
- // §2.2 scope migration: the server emits the delete tagged with the old
5456
- // scope and the upsert tagged with the new one in one commit. A reader
5457
- // that holds both scopes receives them in two subscription sections, so
5458
- // the section order would otherwise decide whether the row survives. One
5459
- // commit's delete and upsert of the same row are one change, and the
5460
- // upsert wins. A frame that carries both itself keeps its own operation
5461
- // order; only a pair split across sections is coalesced.
5462
- const coalescedDeletes = new Set<string>();
5463
- {
5464
- const ops = new Map<
5465
- string,
5466
- { readonly upserts: Set<number>; readonly deletes: Set<number> }
5467
- >();
5468
- const bothInFrame = new Set<string>();
5469
- let openSub: SubscriptionRecord | undefined;
5470
- let frameIndex = -1;
5471
- for (const frame of message.frames) {
5472
- if (frame.type === 'SUB_START') {
5473
- const sub = subsById.get(frame.id);
5474
- openSub = skipsSection(sub) ? undefined : sub;
5475
- } else if (frame.type === 'SUB_END') {
5476
- openSub = undefined;
5477
- } else if (frame.type === 'ERROR') {
5478
- break;
5479
- } else if (frame.type === 'COMMIT' && openSub !== undefined) {
5480
- frameIndex += 1;
5481
- const local = new Map<string, number>();
5482
- for (const change of frame.changes) {
5483
- const table = frame.tables[change.tableIndex];
5484
- if (table === undefined) continue;
5485
- const key = deleteKey(frame.commitSeq, table, change.rowId);
5486
- const entry = ops.get(key) ?? {
5487
- upserts: new Set<number>(),
5488
- deletes: new Set<number>(),
5489
- };
5490
- if (change.op === 'upsert') entry.upserts.add(frameIndex);
5491
- else entry.deletes.add(frameIndex);
5492
- ops.set(key, entry);
5493
- local.set(
5494
- key,
5495
- (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2),
5496
- );
5497
- }
5498
- for (const [key, seen] of local) {
5499
- if (seen === 3) bothInFrame.add(key);
5500
- }
5501
- }
5502
- }
5503
- for (const [key, entry] of ops) {
5504
- if (
5505
- !bothInFrame.has(key) &&
5506
- entry.upserts.size > 0 &&
5507
- entry.deletes.size > 0
5508
- ) {
5509
- coalescedDeletes.add(key);
5510
- }
5511
- }
5512
- }
5513
-
5514
5312
  // Each durable observer transaction emits its own revisioned batch.
5515
5313
  // Async decrypt/download work happens outside SQLite transactions.
5516
5314
  this.#beginDiagnosticsDeferral();
@@ -5593,55 +5391,28 @@ export class SyncClient {
5593
5391
  // Pre-indexed above so companion ordering remains wire-additive.
5594
5392
  break;
5595
5393
  case 'SUB_START': {
5596
- const sub = subsById.get(frame.id);
5597
- const fresh =
5598
- sub !== undefined &&
5599
- sub.cursor < 0 &&
5600
- sub.bootstrapState === undefined &&
5601
- frame.bootstrap;
5602
- // §4.4: a section whose registration was removed mid-round
5603
- // (unsubscribe, eviction) is skipped; it never re-creates it.
5604
- const skip =
5605
- skipsSection(sub) ||
5606
- getSubscription(this.#db, frame.id) === undefined;
5607
- if (skip && mode === 'delta') deltaDropped = true;
5608
- section = { start: frame, sub, fresh, skip, cleared: false };
5394
+ // §4.4: a section of a unit the app released while the round was
5395
+ // in flight is skipped; it never re-creates the unit. A delta
5396
+ // carries no unit section (§8.2).
5397
+ const unit =
5398
+ mode === 'pull' ? getUnit(this.#db, frame.id) : undefined;
5399
+ section =
5400
+ unit?.status === 'active'
5401
+ ? {
5402
+ start: frame,
5403
+ unit,
5404
+ seeded: new Set(
5405
+ unit.bootstrapState === undefined ? [] : unit.seeded,
5406
+ ),
5407
+ skip: false,
5408
+ }
5409
+ : undefined;
5609
5410
  break;
5610
5411
  }
5611
- case 'COMMIT':
5612
- if (
5613
- section !== undefined &&
5614
- !section.skip &&
5615
- section.sub !== undefined
5616
- ) {
5617
- const changes = frame.changes.filter((change) => {
5618
- if (change.op !== 'delete') return true;
5619
- const table = frame.tables[change.tableIndex];
5620
- return (
5621
- table === undefined ||
5622
- !coalescedDeletes.has(
5623
- deleteKey(frame.commitSeq, table, change.rowId),
5624
- )
5625
- );
5626
- });
5627
- if (changes.length > 0) {
5628
- await this.#applyCommit(
5629
- { ...frame, changes },
5630
- summary,
5631
- section.sub.id,
5632
- mode,
5633
- );
5634
- }
5635
- }
5636
- break;
5637
5412
  case 'SEGMENT_INLINE':
5638
5413
  case 'SEGMENT_REF': {
5639
- if (
5640
- section === undefined ||
5641
- section.skip ||
5642
- section.sub === undefined
5643
- )
5644
- break;
5414
+ if (section === undefined || section.skip) break;
5415
+ const unitId = section.unit.id;
5645
5416
  if (
5646
5417
  frame.type === 'SEGMENT_REF' &&
5647
5418
  frame.mediaType === 'sqlite' &&
@@ -5655,7 +5426,7 @@ export class SyncClient {
5655
5426
  if (frame.type === 'SEGMENT_REF') {
5656
5427
  this.#progress.update({
5657
5428
  phase: 'download',
5658
- subscriptionId: section.sub.id,
5429
+ unitId,
5659
5430
  table: frame.table,
5660
5431
  segmentId: frame.segmentId,
5661
5432
  bytesReceived: 0,
@@ -5670,125 +5441,197 @@ export class SyncClient {
5670
5441
  bytes = await (pending ??
5671
5442
  this.#downloadSegment(
5672
5443
  frame,
5673
- section.sub,
5444
+ section.unit.scopes,
5674
5445
  (bytesReceived) => this.#progress.update({ bytesReceived }),
5675
5446
  signal,
5676
5447
  ));
5448
+ this.#progress.update({ phase: 'import' });
5677
5449
  } else {
5678
5450
  bytes = frame.payload;
5679
5451
  }
5680
- if (frame.type === 'SEGMENT_REF')
5681
- this.#progress.update({ phase: 'import' });
5682
- if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
5683
- // Images are whole-table; paged image descriptors are invalid.
5684
- if (
5685
- frame.rowCursor !== undefined ||
5686
- frame.nextRowCursor !== undefined
5687
- ) {
5688
- throw invalidRequest(
5689
- 'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)',
5452
+ const image =
5453
+ frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite'
5454
+ ? frame
5455
+ : undefined;
5456
+ // Images are whole-table; paged image descriptors are invalid.
5457
+ if (
5458
+ image !== undefined &&
5459
+ (image.rowCursor !== undefined ||
5460
+ image.nextRowCursor !== undefined)
5461
+ )
5462
+ throw invalidRequest(
5463
+ 'sqlite segments are whole-table: rowCursor/nextRowCursor must be absent (§5.3)',
5464
+ );
5465
+ const segment =
5466
+ image === undefined ? decodeRowsSegment(bytes) : undefined;
5467
+ if (frame.type === 'SEGMENT_INLINE' && segment !== undefined)
5468
+ this.#progress.update({
5469
+ phase: 'import',
5470
+ unitId,
5471
+ table: segment.table,
5472
+ segmentId: undefined,
5473
+ bytesReceived: bytes.byteLength,
5474
+ bytesTotal: bytes.byteLength,
5475
+ rowsProcessed: 0,
5476
+ rowsTotal: segment.blocks.reduce(
5477
+ (n, block) => n + block.length,
5478
+ 0,
5479
+ ),
5480
+ });
5481
+ await this.#applySegmentOrFail(
5482
+ section,
5483
+ summary,
5484
+ image?.table ?? segment!.table,
5485
+ (table, clearFirst, effective, owners) => {
5486
+ const options = this.#segmentApplyOptions(
5487
+ table,
5488
+ clearFirst,
5489
+ effective,
5490
+ owners,
5491
+ image !== undefined
5492
+ ? image.rowCount > 0
5493
+ : segment!.blocks.some((block) => block.length > 0),
5494
+ resetEpoch,
5690
5495
  );
5691
- }
5692
- await this.#applySegmentOrFail(
5693
- section,
5694
- summary,
5695
- (table, clearFirst, effective, owners) =>
5696
- applySqliteSegment(
5697
- this.#db,
5698
- this.#schema,
5699
- table,
5700
- bytes,
5701
- {
5702
- table: frame.table,
5703
- rowCount: frame.rowCount,
5704
- asOfCommitSeq: frame.asOfCommitSeq,
5705
- scopeDigest: frame.scopeDigest,
5706
- },
5707
- this.#segmentApplyOptions(
5496
+ return image !== undefined
5497
+ ? applySqliteSegment(
5498
+ this.#db,
5499
+ this.#schema,
5708
5500
  table,
5709
- clearFirst,
5710
- effective,
5711
- owners,
5712
- frame.rowCount > 0,
5713
- resetEpoch,
5714
- ),
5715
- ),
5716
- section.fresh && !section.cleared,
5717
- );
5718
- } else {
5719
- const segment = decodeRowsSegment(bytes);
5720
- if (frame.type === 'SEGMENT_INLINE') {
5721
- this.#progress.update({
5722
- phase: 'import',
5723
- subscriptionId: section.sub.id,
5724
- table: section.sub.table,
5725
- segmentId: undefined,
5726
- bytesReceived: bytes.byteLength,
5727
- bytesTotal: bytes.byteLength,
5728
- rowsProcessed: 0,
5729
- rowsTotal: segment.blocks.reduce(
5730
- (n, block) => n + block.length,
5731
- 0,
5732
- ),
5733
- });
5734
- }
5735
- await this.#applySegmentOrFail(
5736
- section,
5737
- summary,
5738
- (table, clearFirst, effective, owners) =>
5739
- applyRowsSegment(
5740
- this.#db,
5741
- this.#schema,
5742
- table,
5743
- segment,
5744
- this.#segmentApplyOptions(
5501
+ bytes,
5502
+ image,
5503
+ options,
5504
+ )
5505
+ : applyRowsSegment(
5506
+ this.#db,
5507
+ this.#schema,
5745
5508
  table,
5746
- clearFirst,
5747
- effective,
5748
- owners,
5749
- segment.blocks.some((block) => block.length > 0),
5750
- resetEpoch,
5751
- ),
5752
- this.#encryption,
5753
- ),
5754
- section.fresh &&
5755
- !section.cleared &&
5756
- (frame.type === 'SEGMENT_INLINE' ||
5757
- frame.rowCursor === undefined),
5758
- );
5759
- }
5509
+ segment!,
5510
+ options,
5511
+ this.#encryption,
5512
+ );
5513
+ },
5514
+ );
5760
5515
  break;
5761
5516
  }
5762
5517
  case 'SUB_END': {
5763
- if (
5764
- section?.sub !== undefined &&
5765
- !section.skip &&
5766
- this.#localResetEpoch === resetEpoch
5767
- ) {
5768
- incompleteSubscriptions.delete(section.sub.id);
5769
- }
5518
+ // Reset fence: a rebootstrap that landed mid-round already rewound
5519
+ // this unit; the captured SUB_END predates the rewind and stays
5520
+ // unpersisted so the next round runs the fresh bootstrap.
5770
5521
  if (
5771
5522
  section !== undefined &&
5772
5523
  !section.skip &&
5773
- section.sub !== undefined &&
5774
- // Reset fence: a rebootstrap that landed mid-round already
5775
- // rewound this subscription's cursor; the captured SUB_END
5776
- // state predates the rewind and must stay unpersisted so the
5777
- // next round runs the fresh bootstrap.
5778
5524
  this.#localResetEpoch === resetEpoch
5779
- ) {
5780
- const applied = this.#finishSection(
5781
- section.sub,
5782
- section.start,
5783
- frame.nextCursor,
5784
- frame.bootstrapState,
5785
- summary,
5525
+ )
5526
+ this.#finishSection(section, frame, summary);
5527
+ section = undefined;
5528
+ break;
5529
+ }
5530
+ case 'LIVE_START': {
5531
+ liveStart = frame;
5532
+ const cursor = replicaCursor(this.#db);
5533
+ if (mode === 'delta') {
5534
+ const end = message.frames.find(
5535
+ (candidate) => candidate.type === 'LIVE_END',
5786
5536
  );
5787
- if (mode === 'delta' && applied) {
5788
- deltaCursor = Math.max(deltaCursor, frame.nextCursor);
5537
+ // §8.2: a delta while no unit is live is a drop; one at or
5538
+ // below the replica cursor is a duplicate and no drop.
5539
+ if (frame.status !== 'active' || cursor < 0) {
5540
+ deltaDropped = true;
5541
+ liveStart = undefined;
5542
+ } else if (end?.type === 'LIVE_END' && end.throughSeq <= cursor)
5543
+ liveStart = undefined;
5544
+ }
5545
+ receivers =
5546
+ liveStart?.status === 'active'
5547
+ ? loadUnits(this.#db).filter(
5548
+ (unit) =>
5549
+ owning(unit) &&
5550
+ (mode === 'pull' || unit.cursor === undefined),
5551
+ )
5552
+ : [];
5553
+ break;
5554
+ }
5555
+ case 'COMMIT': {
5556
+ if (liveStart?.status !== 'active') break;
5557
+ const changes = frame.changes.filter((change) => {
5558
+ const table = this.#schema.tables.get(
5559
+ frame.tables[change.tableIndex] ?? '',
5560
+ );
5561
+ // An unknown table fails loud in the apply below.
5562
+ return (
5563
+ table === undefined ||
5564
+ receivers.some((unit) => {
5565
+ const scopes = covers(table, unit.scopes)
5566
+ ? pairScopes(unit.scopes, table.name, unit.echo)
5567
+ : undefined;
5568
+ return (
5569
+ scopes !== undefined &&
5570
+ Object.entries(scopes).every(([variable, values]) =>
5571
+ values.includes(change.scopes[variable] ?? '\0'),
5572
+ )
5573
+ );
5574
+ })
5575
+ );
5576
+ });
5577
+ if (changes.length > 0)
5578
+ await this.#applyCommit({ ...frame, changes }, summary, mode);
5579
+ break;
5580
+ }
5581
+ case 'LIVE_END': {
5582
+ if (mode === 'delta') {
5583
+ if (liveStart !== undefined) {
5584
+ setMeta(this.#db, REPLICA_CURSOR_KEY, String(frame.throughSeq));
5585
+ deltaCursor = frame.throughSeq;
5789
5586
  }
5587
+ break;
5790
5588
  }
5791
- section = undefined;
5589
+ if (liveStart === undefined || this.#localResetEpoch !== resetEpoch)
5590
+ break;
5591
+ liveEnded = true;
5592
+ const status = liveStart.status;
5593
+ const reasonCode = liveStart.reasonCode;
5594
+ const before = replicaCursor(this.#db);
5595
+ this.#applyBatch((batch) => {
5596
+ let cursor = status === 'unregistered' ? before : -1;
5597
+ const joined = Math.max(before, frame.throughSeq);
5598
+ for (const unit of loadUnits(this.#db)) {
5599
+ if (unit.status !== 'active' || bootstrapping(unit)) continue;
5600
+ if (status === 'reset') {
5601
+ // §4.6 replica reset: every live unit bootstraps again;
5602
+ // post-bootstrap units keep their cursors.
5603
+ if (unit.cursor !== undefined) continue;
5604
+ saveUnit(this.#db, {
5605
+ ...unit,
5606
+ reasonCode,
5607
+ cursor: -1,
5608
+ seeded: [],
5609
+ });
5610
+ summary.resets.push(unit.id);
5611
+ for (const ref of windowRefs(this.#db, unit.id))
5612
+ batch.window(ref.baseKey, ref.value);
5613
+ } else if (status === 'active') {
5614
+ // §4.5 join rule J.
5615
+ const next = Math.max(
5616
+ unit.cursor ?? joined,
5617
+ frame.throughSeq,
5618
+ );
5619
+ if (next >= joined) cursor = joined;
5620
+ if (unit.cursor !== undefined)
5621
+ saveUnit(this.#db, {
5622
+ ...unit,
5623
+ cursor: next >= joined ? undefined : next,
5624
+ });
5625
+ }
5626
+ }
5627
+ setMeta(this.#db, REPLICA_CURSOR_KEY, String(cursor));
5628
+ setMeta(this.#db, ECHO_DIGEST_KEY, bytesToHex(frame.echoDigest));
5629
+ if (status === 'unregistered')
5630
+ this.#db.exec(`DELETE FROM ${META_TABLE} WHERE key=?`, [
5631
+ REGISTERED_DIGEST_KEY,
5632
+ ]);
5633
+ else setMeta(this.#db, REGISTERED_DIGEST_KEY, sentDigest!);
5634
+ });
5792
5635
  break;
5793
5636
  }
5794
5637
  case 'ERROR': {
@@ -5830,14 +5673,9 @@ export class SyncClient {
5830
5673
 
5831
5674
  if (errorFrame !== undefined) throw errorFrame;
5832
5675
 
5833
- if (incompleteSubscriptions.size > 0) {
5834
- this.#setSyncNeeded(true);
5835
- this.#emitSyncIntent({ kind: 'interactive' });
5836
- }
5837
-
5838
5676
  if (mode === 'delta') {
5839
5677
  if (deltaCursor >= 0) this.#sendAck(deltaCursor);
5840
- // §8.2: a skipped delta section is a drop; a pull repairs it.
5678
+ // §8.2: an unapplied delta is a drop; a pull repairs it.
5841
5679
  if (deltaDropped) {
5842
5680
  this.#setSyncNeeded(true);
5843
5681
  this.#emitSyncNeeded('catchup-required');
@@ -5846,19 +5684,28 @@ export class SyncClient {
5846
5684
  this.#ackAfterPull();
5847
5685
  }
5848
5686
 
5849
- const bootstrapping = loadSubscriptions(this.#db)
5850
- .filter(
5851
- (sub) => sub.status === 'active' && sub.bootstrapState !== undefined,
5852
- )
5853
- .map((sub) => sub.id);
5687
+ const catchingUp = loadUnits(this.#db)
5688
+ .filter((unit) => unit.status === 'active' && unit.cursor !== undefined)
5689
+ .map((unit) => unit.id);
5690
+ // §7.1: a response without LIVE_END, one answered `unregistered` or
5691
+ // `reset`, or a unit still catching up leaves sync-needed raised; after
5692
+ // `unregistered` the next round starts at once.
5693
+ if (
5694
+ mode === 'pull' &&
5695
+ (!liveEnded || liveStart?.status !== 'active' || catchingUp.length > 0)
5696
+ ) {
5697
+ this.#setSyncNeeded(true);
5698
+ if (liveStart?.status === 'unregistered')
5699
+ this.#emitSyncIntent({ kind: 'interactive' });
5700
+ }
5854
5701
  // §7.4.5: the reset is over once the first post-reset pull round leaves
5855
- // no subscription mid-bootstrap — the tables are rebuilt and current.
5856
- // The epoch check keeps a round that predates a mid-flight rebootstrap
5857
- // from declaring that reset finished before its bootstrap ran.
5702
+ // no unit catching up: the tables are rebuilt and current. The epoch
5703
+ // check keeps a round that predates a mid-flight rebootstrap from
5704
+ // declaring that reset finished before its bootstrap ran.
5858
5705
  if (
5859
5706
  this.#upgrading &&
5860
5707
  mode === 'pull' &&
5861
- bootstrapping.length === 0 &&
5708
+ catchingUp.length === 0 &&
5862
5709
  this.#localResetEpoch === resetEpoch
5863
5710
  ) {
5864
5711
  this.#setUpgrading(false);
@@ -5866,7 +5713,7 @@ export class SyncClient {
5866
5713
  // RFC 0005 D7: coverage completion, lease end, scope revocation and TTL are
5867
5714
  // evaluated once per round, after the apply.
5868
5715
  this.#previousVersionLifetimeCheck();
5869
- return { ...summary, bootstrapping };
5716
+ return { ...summary, bootstrapping: catchingUp };
5870
5717
  }
5871
5718
 
5872
5719
  #handlePushResult(
@@ -6060,7 +5907,6 @@ export class SyncClient {
6060
5907
  async #applyCommit(
6061
5908
  frame: CommitFrame,
6062
5909
  summary: MutableSummary,
6063
- subscriptionId: string,
6064
5910
  source: 'delta' | 'pull',
6065
5911
  ): Promise<void> {
6066
5912
  await applyCommitFrame(
@@ -6078,7 +5924,6 @@ export class SyncClient {
6078
5924
  )) {
6079
5925
  if (table !== undefined)
6080
5926
  batch.appliedCommit({
6081
- subscriptionId,
6082
5927
  table,
6083
5928
  commitSeq: frame.commitSeq,
6084
5929
  source,
@@ -6179,68 +6024,62 @@ export class SyncClient {
6179
6024
  }
6180
6025
 
6181
6026
  /**
6182
- * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
6183
- * (no local scope-column mapping) marks the subscription `failed` and
6184
- * stops syncing the table without failing the whole request.
6027
+ * Apply a segment (rows or sqlite image) of `tableName` within a unit
6028
+ * section: the first segment of the table in the bootstrap clears the
6029
+ * pair's scope first (§5.6). A fail-closed error (no local scope-column
6030
+ * mapping) marks the unit `failed` without failing the whole response.
6185
6031
  */
6186
6032
  async #applySegmentOrFail(
6187
6033
  section: OpenSection,
6188
6034
  summary: MutableSummary,
6035
+ tableName: string,
6189
6036
  apply: (
6190
6037
  table: CompiledClientTable,
6191
6038
  clearFirst: boolean,
6192
6039
  effective: ScopeMap,
6193
6040
  owners: readonly ScopeMap[],
6194
6041
  ) => number | Promise<number>,
6195
- clearFirst: boolean,
6196
6042
  ): Promise<void> {
6197
- const sub = section.sub;
6198
- if (sub === undefined) return;
6199
- const table = this.#table(sub.table);
6043
+ const { unit } = section;
6044
+ const table = this.#table(tableName);
6045
+ const effective = covers(table, unit.scopes)
6046
+ ? pairScopes(unit.scopes, tableName, section.start.fenced)
6047
+ : undefined;
6048
+ if (effective === undefined)
6049
+ throw invalidRequest('a segment names no active pair of its unit');
6200
6050
  try {
6201
6051
  summary.segmentRowsApplied += await apply(
6202
6052
  table,
6203
- clearFirst,
6204
- section.start.effectiveScopes,
6205
- this.#scopeOwners(sub.table, sub.id),
6053
+ !section.seeded.has(tableName),
6054
+ effective,
6055
+ unitOwners(loadUnits(this.#db), table, unit.id),
6206
6056
  );
6207
- section.cleared = true;
6057
+ section.seeded.add(tableName);
6208
6058
  } catch (error) {
6209
6059
  if (
6210
- error instanceof ClientSyncError &&
6211
- error.code === 'sync.scope_revoked'
6212
- ) {
6213
- section.skip = true;
6214
- if (getSubscription(this.#db, sub.id) === undefined) return;
6215
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6216
- this.#applyBatch((batch) => {
6217
- saveSubscription(
6218
- this.#db,
6219
- definedObject({
6220
- id: sub.id,
6221
- table: sub.table,
6222
- scopes: sub.scopes,
6223
- params: sub.params,
6224
- cursor: sub.cursor,
6225
- effectiveScopes: sub.effectiveScopes,
6226
- status: 'failed',
6227
- reasonCode: 'sync.scope_revoked',
6228
- }),
6229
- );
6230
- if (registered !== undefined) {
6231
- batch.window(registered.baseKey, sub.table, registered.unit);
6232
- }
6060
+ !(error instanceof ClientSyncError) ||
6061
+ error.code !== 'sync.scope_revoked'
6062
+ )
6063
+ throw error;
6064
+ section.skip = true;
6065
+ const current = getUnit(this.#db, unit.id);
6066
+ if (current === undefined) return;
6067
+ this.#applyBatch((batch) => {
6068
+ saveUnit(this.#db, {
6069
+ ...current,
6070
+ status: 'failed',
6071
+ reasonCode: 'sync.scope_revoked',
6233
6072
  });
6234
- summary.failed.push(sub.id);
6235
- return;
6236
- }
6237
- throw error;
6073
+ for (const ref of windowRefs(this.#db, unit.id))
6074
+ batch.window(ref.baseKey, ref.value);
6075
+ });
6076
+ summary.failed.push(unit.id);
6238
6077
  }
6239
6078
  }
6240
6079
 
6241
6080
  async #downloadSegment(
6242
6081
  frame: SegmentRefFrame,
6243
- sub: SubscriptionRecord,
6082
+ scopes: UnitScopes,
6244
6083
  onProgress: (bytesReceived: number) => void,
6245
6084
  signal: AbortSignal | undefined,
6246
6085
  ): Promise<Uint8Array> {
@@ -6281,7 +6120,15 @@ export class SyncClient {
6281
6120
  bytes = await downloader({
6282
6121
  segmentId: frame.segmentId,
6283
6122
  table: frame.table,
6284
- requestedScopesJson: canonicalScopeJson(sub.scopes),
6123
+ // §5.5: the owning unit's scope map, each value a one-element list.
6124
+ requestedScopesJson: canonicalScopeJson(
6125
+ Object.fromEntries(
6126
+ Object.entries(scopes).map(([variable, value]) => [
6127
+ variable,
6128
+ [value],
6129
+ ]),
6130
+ ),
6131
+ ),
6285
6132
  byteLength: frame.byteLength,
6286
6133
  onProgress,
6287
6134
  ...(signal !== undefined ? { signal } : {}),
@@ -6306,205 +6153,207 @@ export class SyncClient {
6306
6153
  }
6307
6154
 
6308
6155
  /** Returns whether SUB_END state was persisted (section applied). */
6156
+ /**
6157
+ * Persist a unit section at its `SUB_END` (§4.4): the cursor, resume token,
6158
+ * seeded tables and echo of an active section; the reset of a `reset`
6159
+ * section (§4.6); the purge of every pair the response revokes (§3.3).
6160
+ */
6309
6161
  #finishSection(
6310
- sub: SubscriptionRecord,
6311
- start: SubStartFrame,
6312
- nextCursor: number,
6313
- bootstrapState: string | undefined,
6162
+ section: OpenSection,
6163
+ end: SubEndFrame,
6314
6164
  summary: MutableSummary,
6315
- ): boolean {
6316
- // §4.4: SUB_END rewrites a live registration only. An unsubscribe or
6317
- // eviction during this round's awaits removed it; persisting now would
6318
- // re-create it. Everything below is synchronous with this check.
6319
- if (getSubscription(this.#db, sub.id) === undefined) return false;
6320
- if (start.status === 'active') {
6321
- // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
6322
- // §3.3: the effective-scope echo is persisted for the purge contract.
6323
- // An absent bootstrapState clears any previous resume token (§4.4:
6324
- // absent = bootstrap complete, or not bootstrapping).
6325
- const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
6326
- const completed =
6327
- wasPending && nextCursor >= 0 && bootstrapState === undefined;
6328
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6329
- this.#applyBatch((batch) => {
6330
- saveSubscription(
6331
- this.#db,
6332
- definedObject({
6333
- id: sub.id,
6334
- table: sub.table,
6335
- scopes: sub.scopes,
6336
- params: sub.params,
6337
- cursor: nextCursor,
6338
- bootstrapState: bootstrapState,
6339
- effectiveScopes: start.effectiveScopes,
6340
- status: 'active',
6341
- }),
6342
- );
6343
- if (completed) {
6344
- const table = this.#table(sub.table);
6345
- const effective = start.effectiveScopes;
6346
- const covered = this.#db
6347
- .query(
6348
- `SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`,
6349
- [sub.table, nextCursor],
6350
- )
6351
- .filter((row) =>
6352
- [row.intent, row.base].some((json) => {
6353
- if (json === null) return false;
6354
- const values: Record<string, JsonRowValue> = JSON.parse(
6355
- String(json),
6356
- );
6357
- return matchesLocalScopes(table, effective, values);
6358
- }),
6359
- );
6360
- if (covered.length) {
6361
- const scope = covered.map((row) =>
6362
- JSON.stringify([sub.table, String(row.id)]),
6363
- );
6364
- restoreFailedBases(this.#db, this.#schema, scope);
6365
- for (const row of covered)
6366
- this.#db.exec(
6367
- `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
6368
- [sub.table, String(row.id), nextCursor],
6369
- );
6370
- batch.table(sub.table);
6371
- this.#replayOutbox(scope, false);
6372
- }
6373
- }
6374
- if (completed && registered !== undefined) {
6375
- // A zero-row bootstrap is a window-domain transition, not a fake
6376
- // row/table change (SPEC §4.8 / §7.5).
6377
- batch.window(registered.baseKey, sub.table, registered.unit);
6378
- }
6379
- });
6380
- return true;
6381
- }
6382
-
6383
- if (start.status === 'reset') {
6384
- // §4.6: discard cursor + resume token, keep local rows, re-bootstrap
6385
- // with cursor = -1 on the next pull. Staleness, not a purge.
6386
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6387
- this.#applyBatch((batch) => {
6388
- saveSubscription(
6389
- this.#db,
6390
- definedObject({
6391
- id: sub.id,
6392
- table: sub.table,
6393
- scopes: sub.scopes,
6394
- params: sub.params,
6395
- cursor: -1,
6396
- effectiveScopes: sub.effectiveScopes,
6397
- status: 'active',
6398
- reasonCode: start.reasonCode,
6399
- }),
6400
- );
6401
- if (registered !== undefined) {
6402
- batch.window(registered.baseKey, sub.table, registered.unit);
6403
- }
6404
- });
6405
- summary.resets.push(sub.id);
6406
- return false;
6407
- }
6408
-
6409
- // revoked (§3.3): purge rows matching the LAST-echoed effective scopes
6410
- // (never the requested map), drop doomed outbox commits, stop pulling.
6411
- const table = this.#table(sub.table);
6412
- const lastEffective = sub.effectiveScopes;
6413
- const owners = this.#scopeOwners(sub.table, sub.id);
6414
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6415
- let failed = false;
6165
+ ): void {
6166
+ const { start } = section;
6167
+ // §4.4: SUB_END writes only into a unit that is still registered. An
6168
+ // unsubscribe during this round's awaits removed it.
6169
+ const unit = getUnit(this.#db, start.id);
6170
+ if (unit?.status !== 'active') return;
6171
+ const refs = windowRefs(this.#db, unit.id);
6416
6172
  this.#applyBatch((batch) => {
6417
- if (
6418
- lastEffective !== undefined &&
6419
- Object.keys(lastEffective).length > 0
6420
- ) {
6421
- try {
6422
- const scope = [
6423
- JSON.stringify([table.name]),
6424
- ...this.#dropRetainedRows(
6425
- batch,
6426
- (name, values) =>
6427
- name === table.name &&
6428
- ownsLocalRow(table, lastEffective, owners, values),
6429
- ),
6430
- ];
6431
- deleteScopedRows(this.#db, table, lastEffective, owners);
6432
- batch.scopeMap(table, lastEffective);
6433
- // §3.3: a whole pending commit leaves when one of its upserts
6434
- // provably lands in the revoked scopes and no other owner covers it.
6435
- const doomed = listOutbox(this.#db).filter((commit) =>
6436
- commit.operations.some(
6437
- (op) =>
6438
- op.table === table.name &&
6439
- op.values !== undefined &&
6440
- ownsLocalRow(table, lastEffective, owners, op.values),
6441
- ),
6173
+ for (const ref of refs) batch.window(ref.baseKey, ref.value);
6174
+ if (start.status === 'reset') {
6175
+ // §4.6: discard cursor and resume token; the rows stay until the
6176
+ // bootstrap replaces them. Staleness, not a purge.
6177
+ saveUnit(this.#db, {
6178
+ ...unit,
6179
+ reasonCode: start.reasonCode,
6180
+ cursor: -1,
6181
+ bootstrapState: undefined,
6182
+ seeded: [],
6183
+ });
6184
+ summary.resets.push(unit.id);
6185
+ return;
6186
+ }
6187
+ const revoked = start.status === 'revoked';
6188
+ const units = loadUnits(this.#db);
6189
+ let failed = false;
6190
+ let rearmed = false;
6191
+ for (const table of this.#schema.tables.values()) {
6192
+ if (!covers(table, unit.scopes)) continue;
6193
+ const last =
6194
+ unit.echo === undefined
6195
+ ? undefined
6196
+ : pairScopes(unit.scopes, table.name, unit.echo);
6197
+ const next = revoked
6198
+ ? undefined
6199
+ : pairScopes(unit.scopes, table.name, start.fenced);
6200
+ // §3.3: a revoked fenced record that turns active again re-bootstraps.
6201
+ if (unit.echo !== undefined && last === undefined && next !== undefined)
6202
+ rearmed = true;
6203
+ // §3.3: purge a pair the response revokes, keyed on the echo the
6204
+ // client persisted while the pair was active.
6205
+ if (last !== undefined && next === undefined)
6206
+ failed ||= !this.#purgePair(
6207
+ batch,
6208
+ table,
6209
+ last,
6210
+ unitOwners(units, table, unit.id),
6442
6211
  );
6443
- if (doomed.length > 0) {
6444
- for (const commit of doomed) {
6445
- const { clientCommitId } = commit;
6446
- deleteOutboxCommit(this.#db, clientCommitId);
6447
- const results: CommitOperationOutcome[] = commit.operations.map(
6448
- (operation, opIndex) => {
6449
- const rejection: RejectionRecord = {
6450
- clientCommitId,
6451
- opIndex,
6452
- code: 'sync.scope_revoked',
6453
- message:
6454
- 'the commit was dropped because its effective scope was revoked',
6455
- retryable: false,
6456
- operation,
6457
- };
6458
- this.#rejections.push(rejection);
6459
- return { status: 'error', rejection };
6460
- },
6461
- );
6462
- recordCommitOutcome(this.#db, {
6463
- clientCommitId,
6464
- status: 'rejected',
6465
- recordedAtMs: this.#now(),
6466
- results,
6467
- operations: commit.operations,
6468
- });
6469
- }
6470
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
6471
- batch.status();
6472
- batch.rejections();
6473
- batch.outcomes();
6474
- }
6475
- this.#replayOutbox(scope);
6476
- this.#deleteUnreferencedBlobs();
6477
- } catch (error) {
6478
- if (
6479
- error instanceof ClientSyncError &&
6480
- error.code === 'sync.scope_revoked'
6481
- ) {
6482
- failed = true;
6483
- } else {
6484
- throw error;
6485
- }
6486
- }
6487
6212
  }
6488
- saveSubscription(
6489
- this.#db,
6490
- definedObject({
6491
- id: sub.id,
6492
- table: sub.table,
6493
- scopes: sub.scopes,
6494
- params: sub.params,
6495
- cursor: nextCursor,
6496
- effectiveScopes: lastEffective,
6213
+ if (revoked || failed) {
6214
+ saveUnit(this.#db, {
6215
+ ...unit,
6497
6216
  status: failed ? 'failed' : 'revoked',
6498
- reasonCode: start.reasonCode,
6499
- }),
6500
- );
6501
- if (registered !== undefined) {
6502
- batch.window(registered.baseKey, sub.table, registered.unit);
6217
+ reasonCode: failed ? 'sync.scope_revoked' : start.reasonCode,
6218
+ cursor: -1,
6219
+ bootstrapState: undefined,
6220
+ seeded: [],
6221
+ echo: undefined,
6222
+ });
6223
+ if (revoked) summary.revoked.push(unit.id);
6224
+ if (failed) summary.failed.push(unit.id);
6225
+ batch.status();
6226
+ return;
6227
+ }
6228
+ const fresh = rearmed || start.bootstrap;
6229
+ saveUnit(this.#db, {
6230
+ ...unit,
6231
+ reasonCode: undefined,
6232
+ echo: start.fenced,
6233
+ ...(rearmed
6234
+ ? { cursor: -1, bootstrapState: undefined, seeded: [] }
6235
+ : start.bootstrap
6236
+ ? {
6237
+ cursor: end.nextCursor,
6238
+ bootstrapState: end.bootstrapState,
6239
+ seeded:
6240
+ end.bootstrapState === undefined ? [] : [...section.seeded],
6241
+ }
6242
+ : {}),
6243
+ });
6244
+ if (!fresh || rearmed || end.bootstrapState !== undefined) return;
6245
+ // §7.1: a completed bootstrap covers acknowledged intent of its pairs
6246
+ // at or below its pin.
6247
+ for (const table of this.#schema.tables.values()) {
6248
+ const effective = covers(table, unit.scopes)
6249
+ ? pairScopes(unit.scopes, table.name, start.fenced)
6250
+ : undefined;
6251
+ if (effective === undefined) continue;
6252
+ const covered = this.#db
6253
+ .query(
6254
+ `SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`,
6255
+ [table.name, end.nextCursor],
6256
+ )
6257
+ .filter((row) =>
6258
+ [row.intent, row.base].some(
6259
+ (json) =>
6260
+ json !== null &&
6261
+ matchesLocalScopes(table, effective, JSON.parse(String(json))),
6262
+ ),
6263
+ );
6264
+ if (covered.length === 0) continue;
6265
+ const scope = covered.map((row) =>
6266
+ JSON.stringify([table.name, String(row.id)]),
6267
+ );
6268
+ restoreFailedBases(this.#db, this.#schema, scope);
6269
+ for (const row of covered)
6270
+ this.#db.exec(
6271
+ `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
6272
+ [table.name, String(row.id), end.nextCursor],
6273
+ );
6274
+ batch.table(table.name);
6275
+ this.#replayOutbox(scope, false);
6503
6276
  }
6504
6277
  });
6505
- summary.revoked.push(sub.id);
6506
- if (failed) summary.failed.push(sub.id);
6507
- return false;
6278
+ }
6279
+
6280
+ /**
6281
+ * §3.3: purge one revoked pair: delete the rows matching its last effective
6282
+ * scopes that no owner holds, drop every pending commit that provably
6283
+ * writes into them, and rebuild the overlay. Returns false when the table
6284
+ * has no local scope-column mapping (fail closed: nothing deleted).
6285
+ */
6286
+ #purgePair(
6287
+ batch: ChangeAccumulator,
6288
+ table: CompiledClientTable,
6289
+ lastEffective: ScopeMap,
6290
+ owners: readonly ScopeMap[],
6291
+ ): boolean {
6292
+ try {
6293
+ const scope = [
6294
+ JSON.stringify([table.name]),
6295
+ ...this.#dropRetainedRows(
6296
+ batch,
6297
+ (name, values) =>
6298
+ name === table.name &&
6299
+ ownsLocalRow(table, lastEffective, owners, values),
6300
+ ),
6301
+ ];
6302
+ deleteScopedRows(this.#db, table, lastEffective, owners);
6303
+ batch.scopeMap(table, lastEffective);
6304
+ // §3.3: a whole pending commit leaves when one of its upserts
6305
+ // provably lands in the revoked scopes and no other owner covers it.
6306
+ const doomed = listOutbox(this.#db).filter((commit) =>
6307
+ commit.operations.some(
6308
+ (op) =>
6309
+ op.table === table.name &&
6310
+ op.values !== undefined &&
6311
+ ownsLocalRow(table, lastEffective, owners, op.values),
6312
+ ),
6313
+ );
6314
+ for (const commit of doomed) {
6315
+ const { clientCommitId } = commit;
6316
+ deleteOutboxCommit(this.#db, clientCommitId);
6317
+ const results: CommitOperationOutcome[] = commit.operations.map(
6318
+ (operation, opIndex) => {
6319
+ const rejection: RejectionRecord = {
6320
+ clientCommitId,
6321
+ opIndex,
6322
+ code: 'sync.scope_revoked',
6323
+ message:
6324
+ 'the commit was dropped because its effective scope was revoked',
6325
+ retryable: false,
6326
+ operation,
6327
+ };
6328
+ this.#rejections.push(rejection);
6329
+ return { status: 'error', rejection };
6330
+ },
6331
+ );
6332
+ recordCommitOutcome(this.#db, {
6333
+ clientCommitId,
6334
+ status: 'rejected',
6335
+ recordedAtMs: this.#now(),
6336
+ results,
6337
+ operations: commit.operations,
6338
+ });
6339
+ }
6340
+ if (doomed.length > 0) {
6341
+ pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
6342
+ batch.status();
6343
+ batch.rejections();
6344
+ batch.outcomes();
6345
+ }
6346
+ this.#replayOutbox(scope);
6347
+ this.#deleteUnreferencedBlobs();
6348
+ return true;
6349
+ } catch (error) {
6350
+ if (
6351
+ error instanceof ClientSyncError &&
6352
+ error.code === 'sync.scope_revoked'
6353
+ )
6354
+ return false;
6355
+ throw error;
6356
+ }
6508
6357
  }
6509
6358
 
6510
6359
  // -- optimistic state ----------------------------------------------------------