@syncular/client 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
package/src/client.ts CHANGED
@@ -29,20 +29,22 @@ 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,
40
40
  isRoundFailureCode,
41
41
  MessageStreamScanner,
42
42
  PROTOCOL_WIRE_VERSION,
43
- type PresenceKind,
43
+ type PresenceErrorCode,
44
44
  type PushResultFrame,
45
+ parseJsonDocument,
45
46
  parseRealtimeServerEvent,
47
+ type RealtimePresenceEvent,
46
48
  REALTIME_TAG_DELTA,
47
49
  REALTIME_TAG_ROUND,
48
50
  type RejectionDetails,
@@ -50,9 +52,15 @@ import {
50
52
  type ResponseMessage,
51
53
  type RowColumn,
52
54
  type RowValue,
55
+ type LiveStartFrame,
56
+ type PullHeaderFrame,
57
+ registrationDigest,
53
58
  type ScopeMap,
54
59
  type SegmentRefFrame,
60
+ type SubEndFrame,
55
61
  type SubStartFrame,
62
+ unitId,
63
+ type UnitScopes,
56
64
  type WakeReason,
57
65
  } from '@syncular/core';
58
66
  import { EncryptError } from '@syncular/core';
@@ -64,6 +72,7 @@ import {
64
72
  deleteLocalRow,
65
73
  deleteScopedRows,
66
74
  localScopePredicate,
75
+ ownsLocalRow,
67
76
  evictScopedRows,
68
77
  yieldToHost,
69
78
  upsertLocalRow,
@@ -91,16 +100,13 @@ import {
91
100
  CLIENT_DIAGNOSTICS_VERSION,
92
101
  ClientDiagnosticsEmitter,
93
102
  type ClientDiagnosticsListener,
94
- type ClientDiagnosticsRequest,
95
103
  type ClientDiagnosticsSnapshot,
96
104
  type ClientDiagnosticsStorage,
97
105
  type DiagnosticLastChange,
98
106
  type DiagnosticLastRound,
99
107
  type DiagnosticQueryFailure,
100
108
  type DiagnosticRoundCounters,
101
- type DiagnosticSubscription,
102
109
  MAX_DIAGNOSTIC_DOMAINS,
103
- MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
104
110
  MAX_DIAGNOSTIC_QUERY_FAILURES,
105
111
  type RealtimePolicy,
106
112
  type RealtimeState,
@@ -113,6 +119,7 @@ import {
113
119
  classifySqliteFailure,
114
120
  REALTIME_LOST_CODE,
115
121
  RealtimeUnavailableError,
122
+ transportFailed,
116
123
  } from './errors';
117
124
  import {
118
125
  ChangeAccumulator,
@@ -154,7 +161,6 @@ import {
154
161
  import {
155
162
  appendOutboxCommit,
156
163
  deleteOutboxCommit,
157
- dropOutboxCommitsInScope,
158
164
  encodeOutboxCommit,
159
165
  listOutbox,
160
166
  iterateOutbox,
@@ -183,7 +189,6 @@ import {
183
189
  commitOutcome as readCommitOutcome,
184
190
  recordCommitOutcome,
185
191
  } from './outcomes';
186
- import { assertReadOnlyQuery } from './query-guard';
187
192
  import {
188
193
  buildPreviousVersionAudit,
189
194
  capturePreviousVersion,
@@ -209,10 +214,12 @@ import {
209
214
  writePreviousVersionRefusal,
210
215
  } from './previous-version';
211
216
  import {
217
+ bytesToHex,
212
218
  type ClientSchema,
213
219
  type CompiledClientSchema,
214
220
  type CompiledClientTable,
215
221
  compileClientSchema,
222
+ hexToBytes,
216
223
  matchesLocalScopes,
217
224
  dropAndRecreateSyncedTables,
218
225
  ensureLocalBookkeepingSchema,
@@ -232,19 +239,28 @@ import {
232
239
  stripSyncColumns,
233
240
  } from './schema';
234
241
  import {
242
+ bootstrapping,
235
243
  bumpLocalRevision,
236
- deleteSubscription,
244
+ covers,
245
+ deleteUnit,
246
+ ECHO_DIGEST_KEY,
237
247
  getLocalRevision,
238
248
  getMeta,
239
- getSubscription,
240
- loadSubscriptions,
241
- pruneUnknownSubscriptions,
242
- saveSubscriptionScopeSchema,
243
- resetSubscriptionsForBump,
244
- type SubscriptionRecord,
245
- 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,
246
261
  setMeta,
247
- SUBSCRIPTIONS_TABLE,
262
+ type UnitRecord,
263
+ unitOwners,
248
264
  } from './state';
249
265
  import type {
250
266
  RealtimeConnector,
@@ -254,16 +270,14 @@ import type {
254
270
  } from './transport';
255
271
  import {
256
272
  deletePendingEviction,
257
- deleteWindowUnit,
258
- deriveSubId,
259
- getWindowUnitBySubId,
260
- insertWindowUnit,
261
273
  loadPendingEvictions,
262
274
  loadWindowUnits,
263
275
  savePendingEviction,
264
- unitScopes,
265
276
  type WindowBase,
266
277
  windowBaseKey,
278
+ windowRefs,
279
+ WINDOWS_TABLE,
280
+ windowUnitScopes,
267
281
  } from './window';
268
282
 
269
283
  // ---------------------------------------------------------------------------
@@ -330,14 +344,14 @@ export interface SyncSummary {
330
344
  readonly commitsApplied: number;
331
345
  /** Snapshot rows applied from segments. */
332
346
  readonly segmentRowsApplied: number;
333
- /** Subscriptions still mid-bootstrap (resume token pending). */
347
+ /** Ids of the units still catching up after the round (§4.1). */
334
348
  readonly bootstrapping: readonly string[];
335
- /** Subscriptions reset via `sync.cursor_expired` (re-pull needed). */
349
+ /** Units reset via `sync.cursor_expired` (§4.6). */
336
350
  readonly resets: readonly string[];
337
- /** Subscriptions revoked this round (§3.3 purge ran). */
351
+ /** Units revoked this round (§3.3 purge ran). */
338
352
  readonly revoked: readonly string[];
339
- /** Subscriptions stopped by a fatal configuration error (§3.3/§5.6
340
- * 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). */
341
355
  readonly failed: readonly string[];
342
356
  /** Present when the server declared a schema floor — syncing stopped. */
343
357
  readonly schemaFloor?: SchemaFloor;
@@ -357,7 +371,7 @@ export interface SyncIdleResult extends SyncSummary {
357
371
  }
358
372
 
359
373
  export interface SyncIdleOptions {
360
- /** §7.7: a strict positive round count. Default: 20. */
374
+ /** §7.8: a strict positive round count. Default: 20. */
361
375
  readonly maxRounds?: number;
362
376
  /**
363
377
  * Total wall-clock budget for one drive, across every round. When it
@@ -389,7 +403,7 @@ export interface SyncClientLimits {
389
403
  /**
390
404
  * §4.2 accept bitmask; defaults to inline + external rows (0b0011)
391
405
  * plus SQLite images and signed URLs when supported. Both image chunks
392
- * and rows blocks commit before yielding to local reads (§7.7).
406
+ * and rows blocks commit before yielding to local reads (§7.8).
393
407
  */
394
408
  readonly accept?: number;
395
409
  /**
@@ -408,7 +422,8 @@ export interface SyncClientLimits {
408
422
  readonly maxPushOperationsPerRequest?: number;
409
423
  /**
410
424
  * §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
411
- * envelope, request header, push commits, pull header, subscriptions,
425
+ * envelope, request header, push commits, pull header, unit and progress
426
+ * frames,
412
427
  * framing, and any §5.11 ciphertext). Default: unbounded. A request whose
413
428
  * fixed frames alone exceed it, or whose first commit alone does not fit,
414
429
  * raises `client.push_request_too_large` and stays queued.
@@ -446,6 +461,15 @@ export interface SyncClientConfig {
446
461
  * `required` without a `realtime` connector is refused at construction.
447
462
  */
448
463
  readonly realtimePolicy?: RealtimePolicy;
464
+ /**
465
+ * SPEC §8.5: the server's heartbeat interval in ms, default 30,000. The
466
+ * socket's first `heartbeat` event arms a watchdog; once armed, twice the
467
+ * interval without an inbound frame loses the socket with
468
+ * `transport.timeout` (`causeKind` `heartbeat`).
469
+ */
470
+ readonly realtimeHeartbeatMs?: number;
471
+ /** Timer seam for the heartbeat watchdog; defaults to `setTimeout`. */
472
+ readonly schedule?: (callback: () => void, delayMs: number) => () => void;
449
473
  /** Stable per-device id (§1.5); defaults to a persisted random UUID. */
450
474
  readonly clientId?: string;
451
475
  readonly leaderLock?: LeaderLock;
@@ -467,9 +491,11 @@ export interface SyncClientConfig {
467
491
  /**
468
492
  * §8.6 presence: a scope-mate's presence on a key this client holds
469
493
  * changed (join/update/leave). Fired after the local presence map is
470
- * updated — the app's cue to re-render who's-online.
494
+ * updated — the app's cue to re-render who's-online. `error` is set when
495
+ * the server refused this client's own publish on `scopeKey` (§8.6.2);
496
+ * the map is unchanged then.
471
497
  */
472
- readonly onPresence?: (scopeKey: string) => void;
498
+ readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
473
499
  /**
474
500
  * §5.11 client-side encryption. Supplies the key material (`keyProvider`)
475
501
  * and key selection (`keyIdFor`) for columns the generated schema marks
@@ -536,13 +562,6 @@ export interface PresencePeer {
536
562
  readonly doc: Record<string, unknown>;
537
563
  }
538
564
 
539
- export interface SubscribeInput {
540
- readonly id: string;
541
- readonly table: string;
542
- readonly scopes: ScopeMap;
543
- readonly params?: string;
544
- }
545
-
546
565
  /**
547
566
  * The live state of a window base (§4.8) — the completeness oracle (I3),
548
567
  * as plain serializable data so it crosses the worker/follower boundary
@@ -555,11 +574,10 @@ export interface WindowState {
555
574
  /** Windowed-in units for this base, ordered by value. */
556
575
  readonly units: readonly string[];
557
576
  /**
558
- * Registered units whose bootstrap has not yet completed (§4.8): the
559
- * unit's subscription still has `cursor: -1` (never synced) or holds a
560
- * resume token (mid-bootstrap). Between `setWindow` and the bootstrap
561
- * landing, the local replica for a pending unit may be empty or partial —
562
- * 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.
563
581
  */
564
582
  readonly pending: readonly string[];
565
583
  }
@@ -611,25 +629,24 @@ export interface SnapshotStatement {
611
629
  }
612
630
 
613
631
  /**
614
- * §7.5: the catch-up state of one subscription as persisted in the snapshot,
615
- * never the mutable owner cache. `unknown` means the client does not currently
616
- * hold the subscription (never registered, forgotten, or removed) and carries
617
- * 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).
618
635
  */
619
- export type SubscriptionCatchup =
636
+ export type UnitCatchup =
620
637
  | { readonly state: 'unknown'; readonly id: string }
621
638
  | {
622
639
  readonly state: 'known';
623
640
  readonly id: string;
624
- readonly table: string;
625
641
  readonly status: 'active' | 'revoked' | 'failed';
642
+ readonly live: boolean;
643
+ /** The unit's cursor while it catches up, the replica cursor while live. */
626
644
  readonly cursor: number;
627
645
  readonly hasResumeToken: boolean;
628
- /** True only for `active` with `cursor >= 0` and no resume token. */
646
+ /** True only for an `active` unit that is live or post-bootstrap. */
629
647
  readonly bootstrapComplete: boolean;
630
- /** 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. */
631
649
  readonly knownPendingPages: boolean;
632
- readonly effectiveScopes?: unknown;
633
650
  readonly reasonCode?: string;
634
651
  };
635
652
 
@@ -652,7 +669,8 @@ export type CommitDelivery =
652
669
  export interface SnapshotReadRequest {
653
670
  readonly statements: readonly SnapshotStatement[];
654
671
  readonly coverage?: readonly WindowCoverage[];
655
- readonly subscriptions?: readonly string[];
672
+ /** Unit ids whose catch-up state the read reports. */
673
+ readonly units?: readonly string[];
656
674
  readonly commitIds?: readonly string[];
657
675
  /** §7.5 owner: a failed owned read is reported in `queryFailures`. */
658
676
  readonly owner?: QueryOwner;
@@ -664,7 +682,7 @@ export interface SnapshotRead<Row = SqlRow> {
664
682
  readonly revision: LocalRevision;
665
683
  readonly queries: readonly (readonly Row[])[];
666
684
  readonly coverage: CoverageSnapshot;
667
- readonly subscriptions: readonly SubscriptionCatchup[];
685
+ readonly units: readonly UnitCatchup[];
668
686
  readonly deliveries: readonly CommitDelivery[];
669
687
  }
670
688
 
@@ -715,12 +733,11 @@ async function sha256Hex(bytes: Uint8Array): Promise<string> {
715
733
 
716
734
  interface OpenSection {
717
735
  readonly start: SubStartFrame;
718
- readonly sub: SubscriptionRecord | undefined;
719
- /** Fresh bootstrap (§5.6): request had cursor < 0 and no resume token. */
720
- readonly fresh: boolean;
721
- /** 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. */
722
740
  skip: boolean;
723
- cleared: boolean;
724
741
  }
725
742
 
726
743
  /** §8.7 client side: one in-flight socket round's response assembly. */
@@ -760,7 +777,7 @@ function emptySummary(pushed: number): MutableSummary {
760
777
 
761
778
  const LOG_EPOCH_META_KEY = 'logEpoch';
762
779
 
763
- /** §7.7: one `syncUntilIdle` drive's default total deadline. */
780
+ /** §7.8: one `syncUntilIdle` drive's default total deadline. */
764
781
  const SYNC_IDLE_TIMEOUT_MS = 60_000;
765
782
 
766
783
  /** RFC 0005 defaults (D2/A4/D7). */
@@ -770,6 +787,15 @@ const PREVIOUS_VERSION_DEFAULT_MAX_TABLES = 32;
770
787
  const PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES = 1024 * 1024;
771
788
  const PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
772
789
 
790
+ /** §7.8: an explicit round budget is a strict positive u32 count. */
791
+ function requireRoundBudget(maxRounds: number | undefined): void {
792
+ if (
793
+ maxRounds !== undefined &&
794
+ (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
795
+ )
796
+ throw invalidRequest('maxRounds must be a positive integer');
797
+ }
798
+
773
799
  function boundedBudget(
774
800
  value: number | undefined,
775
801
  fallback: number,
@@ -896,7 +922,7 @@ export class SyncClient {
896
922
  #securityEpoch = 0;
897
923
  #transportEnabled: boolean;
898
924
  #transportEpoch = 0;
899
- #subscriptionEpoch = 0;
925
+ #registrationEpoch = 0;
900
926
  readonly #now: () => number;
901
927
  readonly #outcomeRetentionMaxEntries: number;
902
928
  readonly #retainFailedCommits: boolean;
@@ -918,6 +944,10 @@ export class SyncClient {
918
944
  #realtimeRetryDelayMs: number | undefined;
919
945
  #realtimeConnectPromise: Promise<void> | undefined;
920
946
  #realtimeGeneration = 0;
947
+ readonly #heartbeatMs: number;
948
+ readonly #schedule: NonNullable<SyncClientConfig['schedule']>;
949
+ /** SPEC §8.5: cancels the armed heartbeat watchdog; unset while unarmed. */
950
+ #watchdog: (() => void) | undefined;
921
951
  #pendingRound: PendingRound | undefined;
922
952
  #needsPull = false;
923
953
  readonly #progress = new ProgressEmitter();
@@ -964,7 +994,9 @@ export class SyncClient {
964
994
  /** Compatibility projection from exact batches; never bridge-inferred. */
965
995
  readonly #invalidation = new InvalidationEmitter();
966
996
  /** §8.6: subscribable presence-change listeners (twin of onPresence). */
967
- readonly #presenceListeners = new Set<(scopeKey: string) => void>();
997
+ readonly #presenceListeners = new Set<
998
+ (scopeKey: string, error?: PresenceErrorCode) => void
999
+ >();
968
1000
  readonly #syncNeededListeners = new Set<
969
1001
  (reason: 'startup' | 'hello' | WakeReason) => void
970
1002
  >();
@@ -1052,6 +1084,23 @@ export class SyncClient {
1052
1084
  "realtimePolicy 'required' needs a realtime connector",
1053
1085
  );
1054
1086
  }
1087
+ // Twice the interval must stay within the 2^31 - 1 ms timer range.
1088
+ const heartbeatMs = config.realtimeHeartbeatMs ?? 30_000;
1089
+ if (
1090
+ !Number.isInteger(heartbeatMs) ||
1091
+ heartbeatMs < 1 ||
1092
+ heartbeatMs > 2 ** 30
1093
+ )
1094
+ throw invalidRequest(
1095
+ 'realtimeHeartbeatMs must be an integer in 1..=2^30',
1096
+ );
1097
+ this.#heartbeatMs = heartbeatMs;
1098
+ this.#schedule =
1099
+ config.schedule ??
1100
+ ((callback, delayMs) => {
1101
+ const timer = setTimeout(callback, delayMs);
1102
+ return () => clearTimeout(timer);
1103
+ });
1055
1104
  this.#config = config;
1056
1105
  this.#realtimePolicy = realtimePolicy;
1057
1106
  this.#realtimeState =
@@ -1103,7 +1152,6 @@ export class SyncClient {
1103
1152
  // BUSY/BUSY_SNAPSHOT), and one upgraded before the read refuses with
1104
1153
  // `client.schema_downgrade`. The batch emits its change event only after
1105
1154
  // the commit. The onUpgrading callback still reports reset intent.
1106
- let subscriptions!: ReturnType<typeof pruneUnknownSubscriptions>;
1107
1155
  try {
1108
1156
  this.#applyBatch(() => {
1109
1157
  // §7.4.1/§7.4.2: this is the transaction's first read, so it pins the
@@ -1219,11 +1267,7 @@ export class SyncClient {
1219
1267
  this.#reconcilePreviousVersionAtBoot();
1220
1268
  // A registration remains app intent only while its table exists in the
1221
1269
  // running schema. Removed-table registrations would poison every pull.
1222
- subscriptions = pruneUnknownSubscriptions(
1223
- this.#db,
1224
- loadSubscriptions(this.#db),
1225
- this.#schema,
1226
- );
1270
+ pruneUnknownUnits(this.#db, this.#schema);
1227
1271
  });
1228
1272
  } catch (error) {
1229
1273
  await this.#lease.release();
@@ -1244,7 +1288,7 @@ export class SyncClient {
1244
1288
  `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
1245
1289
  ).length > 0 ||
1246
1290
  loadPendingEvictions(this.#db).length > 0 ||
1247
- subscriptions.some((sub) => sub.status === 'active'));
1291
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
1248
1292
  if (startupWork && this.#securityLifecycle === 'active') {
1249
1293
  this.#needsPull = true;
1250
1294
  this.#emitSyncNeeded('startup');
@@ -1257,7 +1301,7 @@ export class SyncClient {
1257
1301
  clientId: () => this.#clientId,
1258
1302
  role: () => 'direct',
1259
1303
  outbox: async () => this.pendingCommits().length,
1260
- subscriptions: async () => this.subscriptions(),
1304
+ units: async () => this.units(),
1261
1305
  conflicts: async () => this.conflicts().length,
1262
1306
  rejections: async () => this.rejections().length,
1263
1307
  syncNeeded: async () => this.statusSnapshot().syncNeeded,
@@ -1286,7 +1330,7 @@ export class SyncClient {
1286
1330
  String(this.#schema.version),
1287
1331
  );
1288
1332
  setLocalSchemaDescriptor(this.#db, this.#schema);
1289
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1333
+ saveUnitScopeSchema(this.#db, this.#schema);
1290
1334
  });
1291
1335
  return;
1292
1336
  }
@@ -1297,7 +1341,7 @@ export class SyncClient {
1297
1341
  this.#db.transaction(() => {
1298
1342
  ensureLocalSyncedSchema(this.#db, this.#schema);
1299
1343
  setLocalSchemaDescriptor(this.#db, this.#schema);
1300
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1344
+ saveUnitScopeSchema(this.#db, this.#schema);
1301
1345
  });
1302
1346
  return;
1303
1347
  }
@@ -1337,15 +1381,10 @@ export class SyncClient {
1337
1381
  ),
1338
1382
  );
1339
1383
  }
1340
- pruneUnknownSubscriptions(
1341
- this.#db,
1342
- loadSubscriptions(this.#db),
1343
- this.#schema,
1344
- true,
1345
- );
1384
+ pruneUnknownUnits(this.#db, this.#schema, true);
1346
1385
  this.#discardAcknowledgedRows();
1347
1386
  dropAndRecreateSyncedTables(this.#db, this.#schema);
1348
- resetSubscriptionsForBump(this.#db);
1387
+ resetUnits(this.#db);
1349
1388
  this.#replayOutbox();
1350
1389
  setMeta(
1351
1390
  this.#db,
@@ -1353,7 +1392,7 @@ export class SyncClient {
1353
1392
  String(this.#schema.version),
1354
1393
  );
1355
1394
  setLocalSchemaDescriptor(this.#db, this.#schema);
1356
- saveSubscriptionScopeSchema(this.#db, this.#schema);
1395
+ saveUnitScopeSchema(this.#db, this.#schema);
1357
1396
  });
1358
1397
  // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
1359
1398
  for (const table of this.#schema.tables.values()) batch.table(table.name);
@@ -1443,7 +1482,7 @@ export class SyncClient {
1443
1482
  this.#emitSyncIntent({ kind: 'interactive' });
1444
1483
  return [];
1445
1484
  }
1446
- const subscriptions = loadSubscriptions(this.#db);
1485
+ const units = loadUnits(this.#db);
1447
1486
  this.#setUpgrading(true);
1448
1487
  // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
1449
1488
  // orphan sweep but captures no new shadow.
@@ -1454,7 +1493,7 @@ export class SyncClient {
1454
1493
  this.#db.transaction(() => {
1455
1494
  this.#discardAcknowledgedRows();
1456
1495
  dropAndRecreateSyncedTables(this.#db, this.#schema);
1457
- resetSubscriptionsForBump(this.#db);
1496
+ resetUnits(this.#db);
1458
1497
  setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
1459
1498
  // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
1460
1499
  // transaction before they replay, so the reset boundary never fails on
@@ -1480,7 +1519,7 @@ export class SyncClient {
1480
1519
  this.#setSyncNeeded(true);
1481
1520
  this.#emitSyncNeeded('startup');
1482
1521
  this.#emitSyncIntent({ kind: 'interactive' });
1483
- return subscriptions.map((subscription) => subscription.id);
1522
+ return units.map((unit) => unit.id);
1484
1523
  }
1485
1524
 
1486
1525
  #setUpgrading(upgrading: boolean): void {
@@ -1563,6 +1602,7 @@ export class SyncClient {
1563
1602
  if (this.#transportEnabled === enabled) return;
1564
1603
  this.#transportEnabled = enabled;
1565
1604
  this.#transportEpoch += 1;
1605
+ this.#disarm();
1566
1606
  if (!enabled && !this.#syncOutstanding) this.disconnectRealtime();
1567
1607
  this.#emitSyncIntent(
1568
1608
  enabled && this.#securityLifecycle === 'active'
@@ -1635,7 +1675,7 @@ export class SyncClient {
1635
1675
  `SELECT 1 FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL LIMIT 1`,
1636
1676
  ).length > 0 ||
1637
1677
  loadPendingEvictions(this.#db).length > 0 ||
1638
- loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
1678
+ loadUnits(this.#db).some((unit) => unit.status === 'active'));
1639
1679
  if (startupWork) {
1640
1680
  this.#setSyncNeeded(true);
1641
1681
  this.#emitSyncNeeded('startup');
@@ -1673,8 +1713,8 @@ export class SyncClient {
1673
1713
  }
1674
1714
 
1675
1715
  /**
1676
- * The raw-SQL read tier. Guarded (query-guard.ts): a single read-only
1677
- * statement only — writes must go through `mutate()` so they hit the
1716
+ * The raw-SQL read tier. Guarded (query-guard.ts): a single statement
1717
+ * SQLite reports read-only — writes must go through `mutate()` so they hit the
1678
1718
  * outbox (SPEC §7.1). Reserved `_sync_*` columns are stripped from the
1679
1719
  * result, so a `SELECT *` row is safe to feed back into `mutate()`
1680
1720
  * values; alias explicitly (`_sync_version AS v`) to read one. Engine
@@ -1682,11 +1722,10 @@ export class SyncClient {
1682
1722
  */
1683
1723
  query(sql: string, params?: readonly SqlValue[]): SqlRow[] {
1684
1724
  this.#requireActive();
1685
- assertReadOnlyQuery(sql);
1686
1725
  // RFC 0005's container lives in a separate database file, so this
1687
1726
  // connection cannot see it and there is no table-access guard to run.
1688
1727
  try {
1689
- return stripSyncColumns(this.#db.query(sql, params));
1728
+ return stripSyncColumns(this.#db.queryReadOnly(sql, params));
1690
1729
  } catch (error) {
1691
1730
  throw classifySqliteFailure(error).error;
1692
1731
  }
@@ -1741,7 +1780,7 @@ export class SyncClient {
1741
1780
  }
1742
1781
 
1743
1782
  /**
1744
- * §7.5: resolve several read-only statements, window coverage, subscription
1783
+ * §7.5: resolve several read-only statements, window coverage, unit
1745
1784
  * catch-up states, and commit deliveries from one SQLite read transaction
1746
1785
  * and one revision. A host that needs those together reads them together;
1747
1786
  * every statement passes the read-only guard and any failure rolls the whole
@@ -1752,10 +1791,9 @@ export class SyncClient {
1752
1791
  return this.#readSnapshot(spec);
1753
1792
  }
1754
1793
 
1755
- /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
1756
- subscriptionCatchup(id: string): SubscriptionCatchup {
1757
- return this.#readSnapshot({ statements: [], subscriptions: [id] })
1758
- .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]!;
1759
1797
  }
1760
1798
 
1761
1799
  /** §7.5: one client commit's delivery status: pending, its retained outcome,
@@ -1767,75 +1805,35 @@ export class SyncClient {
1767
1805
 
1768
1806
  /**
1769
1807
  * §7.5: the one atomic read primitive. Every public read (`querySnapshot`,
1770
- * `snapshotRead`, `subscriptionCatchup`, `commitDelivery`) enters here, so
1808
+ * `snapshotRead`, `unitCatchup`, `commitDelivery`) enters here, so
1771
1809
  * the read-only guard, transaction, revision, coverage, catch-up, delivery,
1772
1810
  * and owner-failure observation exist once.
1773
1811
  */
1774
1812
  #readSnapshot(request: SnapshotReadRequest): SnapshotRead {
1775
1813
  this.#requireActive();
1776
1814
  const owner = request.owner;
1777
- const catchupOf = (id: string): SubscriptionCatchup => {
1778
- 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))
1779
1820
  throw new ClientSyncError(
1780
1821
  'sync.local_corrupt',
1781
- 'persisted subscription state is invalid',
1822
+ 'persisted unit state is invalid',
1782
1823
  );
1783
- }
1784
- const row = this.#db.query(
1785
- `SELECT tbl,status,cursor,bootstrap_state,effective_scopes,reason_code FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`,
1786
- [id],
1787
- )[0];
1788
- if (row === undefined) return { state: 'unknown', id };
1789
- const table = row.tbl;
1790
- const status = row.status;
1791
- const cursor = row.cursor;
1792
- if (
1793
- typeof table !== 'string' ||
1794
- (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
1795
- typeof cursor !== 'number' ||
1796
- !Number.isSafeInteger(cursor)
1797
- ) {
1798
- corrupt();
1799
- }
1800
- const token = row.bootstrap_state;
1801
- if (token !== null && typeof token !== 'string') corrupt();
1802
- const rawScopes = row.effective_scopes;
1803
- let effectiveScopes: unknown;
1804
- if (rawScopes !== null) {
1805
- if (typeof rawScopes !== 'string') corrupt();
1806
- try {
1807
- effectiveScopes = JSON.parse(rawScopes);
1808
- if (effectiveScopes === null) effectiveScopes = undefined;
1809
- else if (
1810
- typeof effectiveScopes !== 'object' ||
1811
- Array.isArray(effectiveScopes) ||
1812
- !Object.values(effectiveScopes).every(
1813
- (values) =>
1814
- Array.isArray(values) &&
1815
- values.every((value) => typeof value === 'string'),
1816
- )
1817
- )
1818
- corrupt();
1819
- } catch {
1820
- corrupt();
1821
- }
1822
- }
1823
- const reasonCode = row.reason_code;
1824
- if (reasonCode !== null && typeof reasonCode !== 'string') corrupt();
1825
- const active = status === 'active';
1826
- const hasResumeToken = token !== null;
1827
- return {
1824
+ const active = unit.status === 'active';
1825
+ const pending = bootstrapping(unit);
1826
+ return definedObject({
1828
1827
  state: 'known',
1829
1828
  id,
1830
- table,
1831
- status,
1829
+ status: unit.status,
1830
+ live: unit.cursor === undefined,
1832
1831
  cursor,
1833
- hasResumeToken,
1834
- bootstrapComplete: active && cursor >= 0 && !hasResumeToken,
1835
- knownPendingPages: active && (hasResumeToken || cursor < 0),
1836
- ...(effectiveScopes !== undefined ? { effectiveScopes } : {}),
1837
- ...(reasonCode !== null ? { reasonCode } : {}),
1838
- };
1832
+ hasResumeToken: unit.bootstrapState !== undefined,
1833
+ bootstrapComplete: active && !pending,
1834
+ knownPendingPages: active && pending,
1835
+ reasonCode: unit.reasonCode,
1836
+ });
1839
1837
  };
1840
1838
  const deliveryOf = (id: string): CommitDelivery => {
1841
1839
  const pending =
@@ -1851,13 +1849,12 @@ export class SyncClient {
1851
1849
  };
1852
1850
  let read: SnapshotRead;
1853
1851
  try {
1854
- for (const statement of request.statements) {
1855
- assertReadOnlyQuery(statement.sql);
1856
- }
1857
1852
  read = this.#db.transaction(() => {
1858
1853
  const revision = getLocalRevision(this.#db);
1859
1854
  const queries = request.statements.map((statement) =>
1860
- stripSyncColumns(this.#db.query(statement.sql, statement.params)),
1855
+ stripSyncColumns(
1856
+ this.#db.queryReadOnly(statement.sql, statement.params),
1857
+ ),
1861
1858
  );
1862
1859
  const pending: WindowUnitRef[] = [];
1863
1860
  const missing: WindowUnitRef[] = [];
@@ -1878,7 +1875,7 @@ export class SyncClient {
1878
1875
  pending,
1879
1876
  missing,
1880
1877
  },
1881
- subscriptions: (request.subscriptions ?? []).map(catchupOf),
1878
+ units: (request.units ?? []).map(catchupOf),
1882
1879
  deliveries: (request.commitIds ?? []).map(deliveryOf),
1883
1880
  };
1884
1881
  });
@@ -1948,7 +1945,7 @@ export class SyncClient {
1948
1945
  this.#discardPreviousVersion();
1949
1946
  return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1950
1947
  }
1951
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
1948
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1952
1949
  this.#discardPreviousVersion();
1953
1950
  return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1954
1951
  }
@@ -2070,19 +2067,15 @@ export class SyncClient {
2070
2067
  }
2071
2068
 
2072
2069
  /**
2073
- * RFC 0005 D7: the §7.4.5 replacement-coverage predicate — every active
2074
- * subscription has `cursor >= 0` and no resume token. Window units own
2075
- * subscriptions, so their pendency is included. An empty active set is not
2076
- * 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.
2077
2073
  */
2078
2074
  #previousVersionCoverageComplete(): boolean {
2079
- const active = loadSubscriptions(this.#db).filter(
2080
- (sub) => sub.status === 'active',
2081
- );
2082
- if (active.length === 0) return false;
2083
- return active.every(
2084
- (sub) => sub.cursor >= 0 && sub.bootstrapState === undefined,
2075
+ const active = loadUnits(this.#db).filter(
2076
+ (unit) => unit.status === 'active',
2085
2077
  );
2078
+ return active.length > 0 && !active.some(bootstrapping);
2086
2079
  }
2087
2080
 
2088
2081
  /**
@@ -2118,7 +2111,7 @@ export class SyncClient {
2118
2111
  }
2119
2112
  const record = this.#readPreviousVersionRecord();
2120
2113
  if (record === undefined) return;
2121
- if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
2114
+ if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
2122
2115
  this.#discardPreviousVersion();
2123
2116
  return;
2124
2117
  }
@@ -2213,104 +2206,40 @@ export class SyncClient {
2213
2206
  * One atomic support/product-health view. It never returns scope values,
2214
2207
  * rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
2215
2208
  */
2216
- diagnosticsSnapshot(
2217
- request: ClientDiagnosticsRequest = {},
2218
- ): ClientDiagnosticsSnapshot {
2209
+ diagnosticsSnapshot(): ClientDiagnosticsSnapshot {
2219
2210
  this.#requireActive();
2220
- const expected = request.expectedSubscriptions ?? [];
2221
- if (expected.length > MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS) {
2222
- throw invalidRequest(
2223
- `diagnosticsSnapshot accepts at most ${MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS} expected subscriptions`,
2224
- );
2225
- }
2226
- const registered = loadSubscriptions(this.#db);
2227
- const subscriptions = new Map<string, DiagnosticSubscription>();
2228
- for (const sub of registered) {
2229
- const reset = sub.cursor < 0 && sub.reasonCode === 'sync.cursor_expired';
2230
- const complete =
2231
- sub.status === 'active' &&
2232
- sub.cursor >= 0 &&
2233
- sub.bootstrapState === undefined;
2234
- subscriptions.set(sub.id, {
2235
- id: sub.id,
2236
- table: sub.table,
2237
- state:
2238
- sub.status === 'revoked'
2239
- ? 'revoked'
2240
- : sub.status === 'failed'
2241
- ? 'failed'
2242
- : reset
2243
- ? 'reset'
2244
- : complete
2245
- ? 'complete'
2246
- : 'bootstrapping',
2247
- complete,
2248
- cursor: sub.cursor,
2249
- ...(sub.reasonCode !== undefined
2250
- ? { reasonCode: this.#diagnosticCode(sub.reasonCode) }
2251
- : {}),
2252
- });
2253
- }
2254
- for (const item of expected) {
2255
- if (
2256
- typeof item.id !== 'string' ||
2257
- item.id.length === 0 ||
2258
- typeof item.table !== 'string' ||
2259
- item.table.length === 0
2260
- ) {
2261
- throw invalidRequest(
2262
- 'diagnosticsSnapshot needs subscription id and table',
2263
- );
2264
- }
2265
- const registeredSubscription = subscriptions.get(item.id);
2266
- if (
2267
- registeredSubscription !== undefined &&
2268
- registeredSubscription.table !== item.table
2269
- ) {
2270
- subscriptions.set(item.id, {
2271
- id: item.id,
2272
- table: item.table,
2273
- state: 'failed',
2274
- complete: false,
2275
- reasonCode: 'client.subscription_intent_mismatch',
2276
- });
2277
- } else if (registeredSubscription === undefined) {
2278
- subscriptions.set(item.id, {
2279
- id: item.id,
2280
- table: item.table,
2281
- state: 'unregistered',
2282
- complete: false,
2283
- });
2284
- }
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;
2285
2229
  }
2286
2230
  const capturedAtMs = this.#now();
2287
2231
  const leaseState = this.#diagnosticLease(capturedAtMs);
2232
+ const round = this.#lastRound;
2288
2233
  const connectivity = !this.#transportEnabled
2289
2234
  ? 'offline'
2290
- : this.#lastRound?.status === 'succeeded'
2235
+ : round?.status === 'succeeded'
2291
2236
  ? 'online'
2292
- : this.#lastRound?.status === 'failed' &&
2293
- (this.#lastRound.causeKind === 'network' ||
2294
- this.#lastRound.causeKind === 'connect')
2237
+ : round?.status === 'failed' &&
2238
+ (round.causeKind === 'network' || round.causeKind === 'connect')
2295
2239
  ? 'offline'
2296
- : this.#lastRound?.status === 'failed' &&
2297
- this.#lastRound.httpStatus !== undefined
2240
+ : round?.status === 'failed' && round.httpStatus !== undefined
2298
2241
  ? 'online'
2299
2242
  : 'unknown';
2300
- const expectedOrder = new Map(
2301
- expected.map((item, index) => [item.id, index] as const),
2302
- );
2303
- const allSubscriptions = [...subscriptions.values()].sort((a, b) => {
2304
- const aExpected = expectedOrder.get(a.id);
2305
- const bExpected = expectedOrder.get(b.id);
2306
- if (aExpected !== undefined || bExpected !== undefined) {
2307
- return (
2308
- (aExpected ?? Number.MAX_SAFE_INTEGER) -
2309
- (bExpected ?? Number.MAX_SAFE_INTEGER)
2310
- );
2311
- }
2312
- return a.id.localeCompare(b.id);
2313
- });
2314
2243
  return definedObject({
2315
2244
  version: CLIENT_DIAGNOSTICS_VERSION,
2316
2245
  capturedAtMs,
@@ -2336,12 +2265,20 @@ export class SyncClient {
2336
2265
  pendingOutbox: countOutbox(this.#db),
2337
2266
  },
2338
2267
  lease: leaseState,
2339
- subscriptions: allSubscriptions.slice(
2340
- 0,
2341
- MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
2342
- ),
2343
- subscriptionsTruncated:
2344
- 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),
2345
2282
  lastRound: this.#lastRound,
2346
2283
  lastChange: this.#lastChange,
2347
2284
  storage: this.#diagnosticStorage(),
@@ -2373,13 +2310,10 @@ export class SyncClient {
2373
2310
  const pageSize = Number(
2374
2311
  this.#db.query('PRAGMA page_size')[0]?.page_size ?? 0,
2375
2312
  );
2376
- const outboxBytes = Number(
2377
- this.#db.query(
2378
- `SELECT COALESCE(SUM(LENGTH(operations)),0)AS bytes FROM ${OUTBOX_TABLE}`,
2379
- )[0]?.bytes ?? 0,
2380
- );
2381
- const outcome = this.#db.query(
2382
- `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}`,
2383
2317
  )[0];
2384
2318
  const blobBytes = this.#hasBlobs
2385
2319
  ? Number(
@@ -2394,9 +2328,9 @@ export class SyncClient {
2394
2328
  return {
2395
2329
  status: pressure ? 'pressure' : 'healthy',
2396
2330
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
2397
- pendingOutboxBytesApprox: Math.max(0, outboxBytes),
2398
- retainedOutcomeBytesApprox: Math.max(0, Number(outcome?.bytes ?? 0)),
2399
- 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)),
2400
2334
  blobCacheBytesApprox: Math.max(0, blobBytes),
2401
2335
  ...(pressure
2402
2336
  ? { pressureReasonCode: 'client.blob_cache_over_limit' as const }
@@ -2500,7 +2434,9 @@ export class SyncClient {
2500
2434
  if (revision !== undefined) {
2501
2435
  const event = batch.finish(revision, status);
2502
2436
  const tables = [...new Set(event.tables.map((entry) => entry.table))];
2503
- 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
+ ];
2504
2440
  this.#lastChange = {
2505
2441
  revision: revision.toString(),
2506
2442
  recordedAtMs: this.#now(),
@@ -2576,9 +2512,7 @@ export class SyncClient {
2576
2512
  options?: { readonly mediaType?: string; readonly name?: string },
2577
2513
  ): Promise<BlobRef> {
2578
2514
  if (this.#config.blobs === undefined) {
2579
- throw invalidRequest(
2580
- 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)',
2581
- );
2515
+ throw invalidRequest('uploadBlob requires a blob transport');
2582
2516
  }
2583
2517
  const blobId = await computeBlobId(bytes);
2584
2518
  const nowMs = this.#now();
@@ -2611,29 +2545,28 @@ export class SyncClient {
2611
2545
  }
2612
2546
 
2613
2547
  async #fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
2614
- const blobId = blobIdOrRef.startsWith('sha256:')
2615
- ? blobIdOrRef
2616
- : parseBlobRef(blobIdOrRef).blobId;
2548
+ // A BlobRef declares the size that caps the download (§5.9.5); a bare
2549
+ // blobId declares none.
2550
+ const ref = blobIdOrRef.startsWith('sha256:')
2551
+ ? undefined
2552
+ : parseBlobRef(blobIdOrRef);
2553
+ const blobId = ref?.blobId ?? blobIdOrRef;
2617
2554
  const cached = getCachedBlob(this.#db, blobId);
2618
2555
  if (cached !== undefined) return cached;
2619
2556
  const transport = this.#config.blobs;
2620
2557
  if (transport === undefined) {
2621
- throw invalidRequest(
2622
- 'fetchBlob requires a blob transport (SyncClientConfig.blobs, §5.9)',
2623
- );
2558
+ throw invalidRequest('fetchBlob requires a blob transport');
2624
2559
  }
2625
2560
  // §5.9.5: the authorized endpoint serves bytes inline OR (always-issue,
2626
2561
  // presign configured) a signed url the client fetches directly. On a url
2627
2562
  // arm the client MUST NOT attach host auth and MUST NOT fall through:
2628
2563
  // failure => re-request, the caller's next fetchBlob mints a fresh url.
2629
2564
  this.#requireTransport();
2630
- const response = await transport.download(blobId);
2565
+ const response = await transport.download(blobId, ref?.byteLength);
2631
2566
  let bytes: Uint8Array;
2632
2567
  if (response.kind === 'url') {
2633
2568
  if (transport.fetchUrl === undefined) {
2634
- throw invalidRequest(
2635
- 'blob download returned a url but the transport cannot fetch urls (§5.9.5)',
2636
- );
2569
+ throw invalidRequest('blob transport cannot fetch urls');
2637
2570
  }
2638
2571
  if (
2639
2572
  response.urlExpiresAtMs !== undefined &&
@@ -2642,22 +2575,22 @@ export class SyncClient {
2642
2575
  // §5.9.5: MUST NOT start a fetch at/past expiry — re-request recovers.
2643
2576
  throw new ClientSyncError(
2644
2577
  'sync.segment_expired',
2645
- `blob url for ${blobId} expired before fetch — re-request mints a fresh url (§5.9.5)`,
2578
+ 'blob url expired before fetch',
2646
2579
  true,
2647
2580
  );
2648
2581
  }
2649
- bytes = await transport.fetchUrl(response.url);
2582
+ bytes = await transport.fetchUrl(response.url, ref?.byteLength);
2650
2583
  } else {
2651
2584
  bytes = response.bytes;
2652
2585
  }
2653
- const computed = await computeBlobId(bytes);
2654
- if (computed !== blobId) {
2655
- // §5.9.5 inherits §5.1: verify the content address, reject on mismatch.
2656
- // On the url path this invalidates the fetch (no fall-through) — the
2657
- // next fetchBlob re-requests the authorized endpoint (§5.9.5 recovery).
2658
- throw invalidRequest(
2659
- `blob content address mismatch for ${blobId} (§5.9.5)`,
2660
- );
2586
+ // §5.9.5 inherits §5.1: the declared size caps the body and the content
2587
+ // address must match. On the url path either failure invalidates the
2588
+ // fetch (no fall-through); the next fetchBlob re-requests the endpoint.
2589
+ if (bytes.byteLength > (ref?.byteLength ?? bytes.byteLength)) {
2590
+ throw invalidRequest('blob exceeds its byteLength');
2591
+ }
2592
+ if ((await computeBlobId(bytes)) !== blobId) {
2593
+ throw invalidRequest('blob content address mismatch');
2661
2594
  }
2662
2595
  putCachedBlob(this.#db, blobId, bytes, this.#now());
2663
2596
  this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
@@ -2676,15 +2609,25 @@ export class SyncClient {
2676
2609
  enforceBlobCacheCap(this.#db, this.#schema, cap);
2677
2610
  }
2678
2611
 
2679
- /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
2612
+ /**
2613
+ * Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. It
2614
+ * runs on the round's operation chain because a refused upload drops
2615
+ * outbox commits a round may have captured.
2616
+ */
2680
2617
  flushBlobUploads(): Promise<void> {
2681
2618
  this.#requireTransport();
2682
- return this.#runProtectedAsync(() => this.#flushBlobUploads());
2619
+ return this.#runProtectedAsync(async () => {
2620
+ await this.#serialize(() => this.#flushBlobUploads(undefined));
2621
+ });
2683
2622
  }
2684
2623
 
2685
- async #flushBlobUploads(): Promise<void> {
2624
+ /** Returns the ids of the commits a refused upload dropped (§5.9.7). */
2625
+ async #flushBlobUploads(
2626
+ signal: AbortSignal | undefined,
2627
+ ): Promise<ReadonlySet<string>> {
2628
+ const refused = new Set<string>();
2686
2629
  const transport = this.#config.blobs;
2687
- if (transport === undefined || !this.#hasBlobs) return;
2630
+ if (transport === undefined || !this.#hasBlobs) return refused;
2688
2631
  for (const pending of listPendingUploads(this.#db)) {
2689
2632
  const cached = getCachedBlob(this.#db, pending.blobId);
2690
2633
  if (
@@ -2699,14 +2642,47 @@ export class SyncClient {
2699
2642
  'Pending blob upload body is missing or corrupt',
2700
2643
  );
2701
2644
  }
2702
- await this.#uploadOne(
2703
- transport,
2704
- pending.blobId,
2705
- cached.bytes,
2706
- pending.mediaType,
2707
- );
2645
+ try {
2646
+ await this.#uploadOne(
2647
+ transport,
2648
+ pending.blobId,
2649
+ cached.bytes,
2650
+ pending.mediaType,
2651
+ signal,
2652
+ );
2653
+ } catch (error) {
2654
+ // §5.9.7: a non-retryable server refusal is this body's final
2655
+ // outcome. Retryable refusals and transport failures fail the round.
2656
+ // A failure without a server code (`sync.transport_failed`: no
2657
+ // response, or a response without a JSON error body) is not one.
2658
+ if (
2659
+ !(error instanceof Error) ||
2660
+ !('code' in error) ||
2661
+ typeof error.code !== 'string' ||
2662
+ error.code === 'sync.transport_failed' ||
2663
+ !('retryable' in error) ||
2664
+ error.retryable !== false
2665
+ )
2666
+ throw error;
2667
+ clearPendingUpload(this.#db, pending.blobId);
2668
+ const referencing = new Set(
2669
+ this.#db
2670
+ .query(
2671
+ `SELECT commit_id FROM ${BLOB_COMMIT_REFS} WHERE blob_id=?`,
2672
+ [pending.blobId],
2673
+ )
2674
+ .map((row) => row.commit_id),
2675
+ );
2676
+ for (const commit of listOutbox(this.#db)) {
2677
+ if (!referencing.has(commit.clientCommitId)) continue;
2678
+ this.#dropIncompatibleCommit(commit, error.message, error.code);
2679
+ refused.add(commit.clientCommitId);
2680
+ }
2681
+ continue;
2682
+ }
2708
2683
  clearPendingUpload(this.#db, pending.blobId);
2709
2684
  }
2685
+ return refused;
2710
2686
  }
2711
2687
 
2712
2688
  /**
@@ -2721,7 +2697,8 @@ export class SyncClient {
2721
2697
  transport: BlobTransport,
2722
2698
  blobId: string,
2723
2699
  bytes: Uint8Array,
2724
- mediaType?: string,
2700
+ mediaType: string | undefined,
2701
+ signal: AbortSignal | undefined,
2725
2702
  ): Promise<void> {
2726
2703
  if (
2727
2704
  transport.uploadGrant !== undefined &&
@@ -2731,6 +2708,7 @@ export class SyncClient {
2731
2708
  blobId,
2732
2709
  bytes.length,
2733
2710
  mediaType,
2711
+ signal,
2734
2712
  );
2735
2713
  if (grant.kind === 'present') return; // idempotent §5.9.3 — no PUT needed
2736
2714
  if (grant.kind === 'url') {
@@ -2739,7 +2717,13 @@ export class SyncClient {
2739
2717
  grant.urlExpiresAtMs > this.#now()
2740
2718
  ) {
2741
2719
  try {
2742
- await transport.uploadToUrl(grant.url, bytes, mediaType);
2720
+ await transport.uploadToUrl(
2721
+ blobId,
2722
+ grant.url,
2723
+ bytes,
2724
+ mediaType,
2725
+ signal,
2726
+ );
2743
2727
  return;
2744
2728
  } catch {
2745
2729
  // Grant PUT failed — stream through the direct endpoint below.
@@ -2749,7 +2733,7 @@ export class SyncClient {
2749
2733
  // grant.kind === 'none' (no presign store) or a failed/expired grant:
2750
2734
  // stream through the direct host-authenticated endpoint.
2751
2735
  }
2752
- await transport.upload(blobId, bytes, mediaType);
2736
+ await transport.upload(blobId, bytes, mediaType, signal);
2753
2737
  }
2754
2738
 
2755
2739
  conflicts(): readonly ConflictRecord[] {
@@ -2774,11 +2758,7 @@ export class SyncClient {
2774
2758
  maxRounds?: number,
2775
2759
  ): Promise<CurrentBaseProof> {
2776
2760
  this.#requireActive();
2777
- if (
2778
- maxRounds !== undefined &&
2779
- (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
2780
- )
2781
- throw invalidRequest('maxRounds must be a positive integer');
2761
+ requireRoundBudget(maxRounds);
2782
2762
  const { clientCommitId, sequence } = outcome;
2783
2763
  const provable = (
2784
2764
  candidate: CommitOutcome | undefined,
@@ -2805,11 +2785,11 @@ export class SyncClient {
2805
2785
  await this.#opChain;
2806
2786
  if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2807
2787
  const epoch = this.#transportEpoch;
2808
- const subscriptionEpoch = this.#subscriptionEpoch;
2788
+ const registrationEpoch = this.#registrationEpoch;
2809
2789
  const securityEpoch = this.#securityEpoch;
2810
- let before: SubscriptionRecord[];
2790
+ let before: UnitRecord[];
2811
2791
  try {
2812
- before = loadSubscriptions(this.#db);
2792
+ before = loadUnits(this.#db);
2813
2793
  } catch {
2814
2794
  return { proven: false, reason: 'snapshot_failed' };
2815
2795
  }
@@ -2822,14 +2802,14 @@ export class SyncClient {
2822
2802
  reason:
2823
2803
  !this.#transportEnabled || epoch !== this.#transportEpoch
2824
2804
  ? 'offline'
2825
- : subscriptionEpoch !== this.#subscriptionEpoch
2805
+ : registrationEpoch !== this.#registrationEpoch
2826
2806
  ? 'missing_coverage'
2827
2807
  : 'sync_failed',
2828
2808
  };
2829
2809
  }
2830
2810
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
2831
2811
  return { proven: false, reason: 'offline' };
2832
- if (subscriptionEpoch !== this.#subscriptionEpoch)
2812
+ if (registrationEpoch !== this.#registrationEpoch)
2833
2813
  return { proven: false, reason: 'missing_coverage' };
2834
2814
  if (
2835
2815
  this.#securityLifecycle !== 'active' ||
@@ -2844,7 +2824,7 @@ export class SyncClient {
2844
2824
  return this.#db.transaction(() => {
2845
2825
  const snapshot = this.#readSnapshot({
2846
2826
  statements: [],
2847
- subscriptions: before.map((sub) => sub.id),
2827
+ units: before.map((unit) => unit.id),
2848
2828
  commitIds: [clientCommitId],
2849
2829
  });
2850
2830
  const delivery = snapshot.deliveries[0];
@@ -2856,24 +2836,20 @@ export class SyncClient {
2856
2836
  report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
2857
2837
  };
2858
2838
  const after = new Map(
2859
- loadSubscriptions(this.#db).map((sub) => [sub.id, sub]),
2839
+ loadUnits(this.#db).map((unit) => [unit.id, unit]),
2860
2840
  );
2861
- const states = new Map(
2862
- 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
+ ),
2863
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.
2864
2850
  const candidates = before.flatMap((previous) => {
2865
- const sub = after.get(previous.id);
2866
- const state = states.get(previous.id);
2867
- return sub !== undefined &&
2868
- sub.table === previous.table &&
2869
- sub.params === previous.params &&
2870
- canonicalScopeJson(sub.scopes) ===
2871
- canonicalScopeJson(previous.scopes) &&
2872
- sub.effectiveScopes !== undefined &&
2873
- state?.state === 'known' &&
2874
- state.bootstrapComplete
2875
- ? [{ table: sub.table, scopes: sub.effectiveScopes }]
2876
- : [];
2851
+ const unit = after.get(previous.id);
2852
+ return unit !== undefined && complete.has(unit.id) ? [unit] : [];
2877
2853
  });
2878
2854
  const covered = (
2879
2855
  tableName: string,
@@ -2887,10 +2863,13 @@ export class SyncClient {
2887
2863
  rowValueToJson(value),
2888
2864
  ]),
2889
2865
  );
2890
- 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;
2891
2870
  return (
2892
- candidate.table === tableName &&
2893
- Object.keys(candidate.scopes).every((variable) => {
2871
+ scopes !== undefined &&
2872
+ Object.keys(scopes).every((variable) => {
2894
2873
  const column = table.scopeColumnByVariable.get(variable);
2895
2874
  const value = column === undefined ? undefined : row[column];
2896
2875
  return (
@@ -2899,7 +2878,7 @@ export class SyncClient {
2899
2878
  typeof value === 'boolean'
2900
2879
  );
2901
2880
  }) &&
2902
- matchesLocalScopes(table, candidate.scopes, values)
2881
+ matchesLocalScopes(table, scopes, values)
2903
2882
  );
2904
2883
  });
2905
2884
  };
@@ -3047,12 +3026,16 @@ export class SyncClient {
3047
3026
  }
3048
3027
 
3049
3028
  /**
3050
- * §8.6: subscribe to presence changes (join/update/leave on any held key).
3051
- * The subscribable twin of the `onPresence` config callback — React's
3052
- * `usePresence` targets this so many components can watch one client.
3029
+ * §8.6: subscribe to presence changes (join/update/leave on any held key)
3030
+ * and to the server's refusal of this client's own publish (`error`,
3031
+ * §8.6.2). The subscribable twin of the `onPresence` config callback —
3032
+ * React's `usePresence` targets this so many components can watch one
3033
+ * client.
3053
3034
  * Returns an unsubscribe function.
3054
3035
  */
3055
- onPresence(listener: (scopeKey: string) => void): () => void {
3036
+ onPresence(
3037
+ listener: (scopeKey: string, error?: PresenceErrorCode) => void,
3038
+ ): () => void {
3056
3039
  this.#presenceListeners.add(listener);
3057
3040
  return () => {
3058
3041
  this.#presenceListeners.delete(listener);
@@ -3093,14 +3076,15 @@ export class SyncClient {
3093
3076
  );
3094
3077
  }
3095
3078
 
3096
- subscriptions(): SubscriptionRecord[] {
3079
+ /** Every unit in registration order (§4.1), including revoked and failed. */
3080
+ units(): UnitRecord[] {
3097
3081
  this.#requireActive();
3098
- return loadSubscriptions(this.#db);
3082
+ return loadUnits(this.#db);
3099
3083
  }
3100
3084
 
3101
- subscription(id: string): SubscriptionRecord | undefined {
3085
+ unit(id: string): UnitRecord | undefined {
3102
3086
  this.#requireActive();
3103
- return getSubscription(this.#db, id);
3087
+ return getUnit(this.#db, id);
3104
3088
  }
3105
3089
 
3106
3090
  pendingCommits(): OutboxCommit[] {
@@ -3108,94 +3092,106 @@ export class SyncClient {
3108
3092
  return listOutbox(this.#db);
3109
3093
  }
3110
3094
 
3111
- // -- subscriptions ----------------------------------------------------------
3095
+ // -- units (§4.1) -----------------------------------------------------------
3112
3096
 
3113
- subscribe(input: SubscribeInput): void {
3114
- this.subscribeMany([input]);
3097
+ /** Register one unit (§4.1) and return its id. */
3098
+ subscribe(scopes: UnitScopes): string {
3099
+ return this.subscribeMany([scopes])[0]!;
3115
3100
  }
3116
3101
 
3117
3102
  /**
3118
- * Register several subscriptions in one local transaction: the same rules
3119
- * as `subscribe` for each input, and one commit for all of them (on OPFS a
3120
- * commit costs milliseconds, so a cold start with hundreds of
3121
- * registrations pays it once). An error rolls back every registration of
3122
- * 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).
3123
3108
  */
3124
- subscribeMany(inputs: readonly SubscribeInput[]): void {
3109
+ subscribeMany(units: readonly UnitScopes[]): string[] {
3125
3110
  this.#requireActive();
3126
3111
  let registered = false;
3127
- this.#db.transaction(() => {
3128
- for (const input of inputs) {
3129
- if (!this.#schema.tables.has(input.table)) {
3130
- throw new ClientSyncError(
3131
- 'sync.unknown_table',
3132
- `subscribe: unknown local table ${JSON.stringify(input.table)}`,
3133
- );
3134
- }
3135
- const existing = getSubscription(this.#db, input.id);
3136
- if (existing !== undefined) {
3137
- const sameIntent =
3138
- existing.table === input.table &&
3139
- canonicalScopeJson(existing.scopes) ===
3140
- canonicalScopeJson(input.scopes) &&
3141
- existing.params === input.params;
3142
- if (!sameIntent) {
3143
- throw new ClientSyncError(
3144
- 'client.subscription_intent_mismatch',
3145
- 'subscription id already names different table, scopes, or params',
3146
- );
3147
- }
3148
- // §3.3: a revoked registration keeps its id and intent but no
3149
- // progress. Subscribing again with the same intent re-arms it, so
3150
- // the next pull resolves its scopes from scratch. A `failed`
3151
- // registration is a configuration error and stays put.
3152
- if (existing.status !== 'revoked') continue;
3153
- }
3154
- saveSubscription(
3155
- this.#db,
3156
- definedObject({
3157
- id: input.id,
3158
- table: input.table,
3159
- scopes: input.scopes,
3160
- params: input.params,
3161
- cursor: -1,
3162
- status: 'active',
3163
- }),
3164
- );
3165
- registered = true;
3166
- }
3167
- });
3168
- if (!registered) return;
3169
- this.#subscriptionEpoch += 1;
3170
- this.#setSyncNeeded(true);
3171
- this.#emitSyncIntent({ kind: 'interactive' });
3172
- 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;
3173
3126
  }
3174
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
+ */
3175
3132
  unsubscribe(id: string): void {
3176
3133
  this.#requireActive();
3177
- if (getSubscription(this.#db, id) === undefined) return;
3178
- deleteSubscription(this.#db, id);
3179
- 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;
3180
3143
  this.#setSyncNeeded(true);
3181
3144
  this.#emitSyncIntent({ kind: 'interactive' });
3182
3145
  this.#emitDiagnostics();
3183
3146
  }
3184
3147
 
3185
- // -- 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) ---------------------------------------------------------
3186
3187
 
3187
3188
  /**
3188
- * Set the live window units for a base (§4.8): a value-sharded family of
3189
- * subscriptions, one per unit. Computes the diff against the registry —
3190
- * added units get fresh subscriptions (image-lane bootstrap on the next
3191
- * sync); removed units are unsubscribed with their first eviction chunk
3192
- * in one local transaction (E1–E4). Idempotent: calling with the same units is a
3193
- * no-op. Re-entry (a unit removed then re-added) cancels any deferred
3194
- * eviction and fresh-bootstraps.
3195
- *
3196
- * The change takes effect on the next `sync()`/socket round — the pull's
3197
- * subscription list (now with the added unit, without the removed one)
3198
- * 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).
3199
3195
  */
3200
3196
  async setWindow(base: WindowBase, units: readonly string[]): Promise<void> {
3201
3197
  await this.setWindowCommand(base, units);
@@ -3207,141 +3203,121 @@ export class SyncClient {
3207
3203
  units: readonly string[],
3208
3204
  ): Promise<CommandResult<void>> {
3209
3205
  this.#requireActive();
3210
- const table = this.#table(base.table);
3211
- if (!table.scopeColumnByVariable.has(base.variable)) {
3212
- throw invalidRequest(
3213
- `${base.table}: unknown scope variable ${base.variable} (§4.8)`,
3214
- );
3215
- }
3216
- // Serialize the whole window edit: it spans an `await deriveSubId` between
3217
- // db transactions, so without the chain a delta apply (or a concurrent
3218
- // setWindow) could interleave its transactions and corrupt the registry.
3219
3206
  let changed = false;
3220
- 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.
3221
3209
  await this.#serialize(async () => {
3222
3210
  const baseKey = windowBaseKey(base);
3223
3211
  const wanted = new Set(units);
3224
3212
  const live = loadWindowUnits(this.#db, baseKey);
3225
- const liveByUnit = new Map(live.map((u) => [u.unit, u.subId]));
3226
-
3227
- // Widen: units wanted but not live → fresh subscription + registry row.
3228
- for (const unit of wanted) {
3229
- if (liveByUnit.has(unit)) continue;
3230
- 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;
3231
3216
  this.#applyBatch((batch) => {
3232
- this.#db.transaction(() => {
3233
- // Re-entry cancels any deferred eviction for this sub id.
3234
- deletePendingEviction(this.#db, subId);
3235
- insertWindowUnit(this.#db, baseKey, unit, subId);
3236
- saveSubscription(
3237
- this.#db,
3238
- definedObject({
3239
- id: subId,
3240
- table: base.table,
3241
- scopes: unitScopes(base, unit),
3242
- params: base.params,
3243
- cursor: -1,
3244
- status: 'active',
3245
- }),
3246
- );
3247
- });
3248
- this.#needsPull = true;
3249
- 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);
3250
3227
  batch.status();
3251
3228
  });
3252
3229
  changed = true;
3253
- widened = true;
3254
- this.#subscriptionEpoch += 1;
3230
+ this.#registrationEpoch += 1;
3255
3231
  }
3256
-
3257
- // Shrink: units live but not wanted → unsubscribe fused with eviction.
3258
- for (const { unit, subId } of live) {
3259
- if (wanted.has(unit)) continue;
3260
- 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);
3261
3235
  changed = true;
3262
- this.#subscriptionEpoch += 1;
3236
+ this.#registrationEpoch += 1;
3263
3237
  }
3264
3238
  });
3265
3239
  const effects: CommandEffects = {
3266
3240
  sync:
3267
- this.#transportEnabled && (changed || widened)
3241
+ this.#transportEnabled && changed
3268
3242
  ? { kind: 'interactive' }
3269
3243
  : { kind: 'none' },
3270
3244
  };
3271
- if (effects.sync.kind === 'interactive') {
3272
- this.#emitSyncIntent(effects.sync);
3273
- }
3245
+ if (effects.sync.kind === 'interactive') this.#emitSyncIntent(effects.sync);
3274
3246
  return { value: undefined, effects };
3275
3247
  }
3276
3248
 
3277
3249
  /**
3278
- * The completeness oracle (§4.8 I3): which units of a base are windowed-in
3279
- * locally, which of those are still bootstrap-pending, and thereby the
3280
- * per-unit verdict a live query renders "may be partial" from. A query
3281
- * whose scope footprint includes an un-windowed OR still-pending unit is
3282
- * NOT answerable in full — the host widens or shows partial, never
3283
- * silently-complete. Registration alone is not completeness: a unit is
3284
- * pending until its subscription completes a bootstrap round (cursor
3285
- * 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.
3286
3254
  */
3287
3255
  windowState(base: WindowBase): WindowState {
3288
3256
  this.#requireActive();
3289
- const baseKey = windowBaseKey(base);
3290
- const live = loadWindowUnits(this.#db, baseKey);
3291
- const pending: string[] = [];
3292
- for (const { unit, subId } of live) {
3293
- const sub = getSubscription(this.#db, subId);
3294
- if (
3295
- sub === undefined ||
3296
- sub.status !== 'active' ||
3297
- sub.cursor < 0 ||
3298
- sub.bootstrapState !== undefined
3299
- ) {
3300
- pending.push(unit);
3301
- }
3302
- }
3303
- 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 };
3304
3267
  }
3305
3268
 
3306
3269
  /**
3307
- * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
3308
- * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
3309
- * pending outbox commit (E1); if any pin remains, records a deferred
3310
- * eviction retried on the next outbox drain. Discards the subscription's
3311
- * cursor/resume/effective-echo (E3) and its version state with the rows
3312
- * (E2). Emits the evicted table's invalidation keys (I1). Fail-closed:
3313
- * with no local scope-column mapping, surfaces a configuration error and
3314
- * 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.
3315
3276
  */
3316
- async #evictUnit(
3277
+ async #releaseWindowUnit(
3317
3278
  baseKey: string,
3318
- base: WindowBase,
3319
- unit: string,
3320
- subId: string,
3279
+ value: string,
3280
+ id: string,
3321
3281
  ): Promise<void> {
3322
- const table = this.#table(base.table);
3323
- const sub = getSubscription(this.#db, subId);
3324
- // The rows a unit holds live under its LAST effective scopes if it ever
3325
- // synced; before first sync, the requested unit scopes are the match.
3326
- const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
3327
- const pinned = this.#pinnedRowIds(base.table);
3328
3282
  let remaining = false;
3329
3283
  this.#applyBatch((batch) => {
3330
- this.#db.transaction(() => {
3331
- const result = evictScopedRows(this.#db, table, effective, pinned);
3332
- remaining = result.remaining;
3333
- deleteWindowUnit(this.#db, baseKey, unit);
3334
- deleteSubscription(this.#db, subId);
3335
- if (result.deferred) {
3336
- savePendingEviction(this.#db, subId, base.table, effective);
3337
- } else {
3338
- deletePendingEviction(this.#db, subId);
3339
- }
3340
- });
3341
- batch.scopeMap(table, effective);
3342
- batch.window(baseKey, table.name, unit);
3343
- this.#needsPull = true;
3284
+ this.#db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
3285
+ baseKey,
3286
+ value,
3287
+ ]);
3288
+ batch.window(baseKey, value);
3344
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;
3305
+ const result = evictScopedRows(
3306
+ this.#db,
3307
+ table,
3308
+ effective,
3309
+ unitOwners(units, table, id),
3310
+ this.#pinnedRowIds(table.name),
3311
+ );
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
+ }
3345
3321
  });
3346
3322
  if (remaining) {
3347
3323
  await yieldToHost();
@@ -3350,28 +3326,26 @@ export class SyncClient {
3350
3326
  }
3351
3327
 
3352
3328
  /**
3353
- * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
3354
- * unit's rows are removed once no pending commit references them; a unit
3355
- * 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.
3356
3331
  */
3357
3332
  async #drainPendingEvictions(): Promise<void> {
3358
- const pending = loadPendingEvictions(this.#db);
3359
- if (pending.length === 0) return;
3360
- for (const entry of pending) {
3333
+ for (const entry of loadPendingEvictions(this.#db)) {
3361
3334
  const table = this.#schema.tables.get(entry.table);
3362
3335
  if (table === undefined) {
3363
- deletePendingEviction(this.#db, entry.subId);
3336
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
3364
3337
  continue;
3365
3338
  }
3366
3339
  let remaining: boolean;
3367
3340
  do {
3368
3341
  if (
3369
3342
  !loadPendingEvictions(this.#db).some(
3370
- (item) => item.subId === entry.subId,
3343
+ (item) =>
3344
+ item.unitId === entry.unitId && item.table === entry.table,
3371
3345
  )
3372
3346
  )
3373
3347
  break;
3374
- // Local writes may add pins while the worker yields between chunks.
3348
+ // Local writes may add pins while the host yields between chunks.
3375
3349
  const pinned = this.#pinnedRowIds(entry.table);
3376
3350
  remaining = false;
3377
3351
  this.#applyBatch((batch) => {
@@ -3379,10 +3353,12 @@ export class SyncClient {
3379
3353
  this.#db,
3380
3354
  table,
3381
3355
  entry.effective,
3356
+ unitOwners(loadUnits(this.#db), table, entry.unitId),
3382
3357
  pinned,
3383
3358
  );
3384
3359
  remaining = result.remaining;
3385
- if (!result.deferred) deletePendingEviction(this.#db, entry.subId);
3360
+ if (!result.deferred)
3361
+ deletePendingEviction(this.#db, entry.unitId, entry.table);
3386
3362
  batch.scopeMap(table, entry.effective);
3387
3363
  });
3388
3364
  if (remaining) await yieldToHost();
@@ -3424,6 +3400,9 @@ export class SyncClient {
3424
3400
  const operations: OutboxOperation[] = mutations.map((mutation) => {
3425
3401
  const table = this.#table(mutation.table);
3426
3402
  if (mutation.op === 'delete') {
3403
+ // §2.4: the server rejects a rowId holding U+0000.
3404
+ if (mutation.rowId.includes('\u0000'))
3405
+ throw invalidRequest('rowId holds U+0000');
3427
3406
  return definedObject({
3428
3407
  table: mutation.table,
3429
3408
  rowId: mutation.rowId,
@@ -3836,7 +3815,7 @@ export class SyncClient {
3836
3815
  }
3837
3816
 
3838
3817
  const pending = listOutbox(this.#db);
3839
- const resetSubscriptions = loadSubscriptions(this.#db).length;
3818
+ const resetSubscriptions = loadUnits(this.#db).length;
3840
3819
  const priorUpgrading = this.#upgrading;
3841
3820
  const priorNeedsPull = this.#needsPull;
3842
3821
  try {
@@ -3846,7 +3825,7 @@ export class SyncClient {
3846
3825
  batch.status();
3847
3826
  this.#discardAcknowledgedRows();
3848
3827
  dropAndRecreateSyncedTables(this.#db, this.#schema);
3849
- resetSubscriptionsForBump(this.#db);
3828
+ resetUnits(this.#db);
3850
3829
  for (const table of this.#schema.tables.values()) {
3851
3830
  batch.table(table.name);
3852
3831
  }
@@ -3985,7 +3964,7 @@ export class SyncClient {
3985
3964
  const baseBytes =
3986
3965
  byteCap === undefined
3987
3966
  ? 0
3988
- : encodeMessage({
3967
+ : encodeRequest({
3989
3968
  wireVersion: PROTOCOL_WIRE_VERSION,
3990
3969
  msgKind: 'request',
3991
3970
  frames: [header, pull],
@@ -4078,7 +4057,7 @@ export class SyncClient {
4078
4057
  const frame =
4079
4058
  byteCap === undefined
4080
4059
  ? 0
4081
- : encodeMessage({
4060
+ : encodeRequest({
4082
4061
  wireVersion: PROTOCOL_WIRE_VERSION,
4083
4062
  msgKind: 'request',
4084
4063
  frames: [header, pushFrame, pull],
@@ -4198,6 +4177,11 @@ export class SyncClient {
4198
4177
  * `setWindow` at an await point.
4199
4178
  */
4200
4179
  sync(): Promise<SyncSummary> {
4180
+ return this.#sync();
4181
+ }
4182
+
4183
+ /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
4184
+ #sync(signal?: AbortSignal): Promise<SyncSummary> {
4201
4185
  this.#requireActive();
4202
4186
  if (this.#syncOutstanding) {
4203
4187
  return Promise.reject(
@@ -4207,7 +4191,7 @@ export class SyncClient {
4207
4191
  this.#syncOutstanding = true;
4208
4192
  this.#beginDiagnosticsDeferral();
4209
4193
  const startedAtMs = this.#now();
4210
- return this.#serialize(() => this.#runSync())
4194
+ return this.#serialize(() => this.#runSync(signal))
4211
4195
  .then(
4212
4196
  (summary) => {
4213
4197
  const completedAtMs = this.#now();
@@ -4326,7 +4310,7 @@ export class SyncClient {
4326
4310
  : 'client.unknown_failure';
4327
4311
  }
4328
4312
 
4329
- async #runSync(): Promise<SyncSummary> {
4313
+ async #runSync(signal: AbortSignal | undefined): Promise<SyncSummary> {
4330
4314
  this.#requireTransport();
4331
4315
  this.#roundRetryDelayMs = undefined;
4332
4316
  this.#progress.emit({
@@ -4361,13 +4345,18 @@ export class SyncClient {
4361
4345
  clientId: this.#clientId,
4362
4346
  schemaVersion: this.#schema.version,
4363
4347
  logEpoch: logEpoch,
4348
+ outboxId: getMeta(this.#db, 'outboxId'),
4364
4349
  });
4365
- const pull: RequestFrame = {
4350
+ // The registration fields are set after encoding (below).
4351
+ const pull: PullHeaderFrame = {
4366
4352
  type: 'PULL_HEADER',
4367
4353
  limitCommits: limits?.limitCommits ?? 0,
4368
4354
  limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
4369
4355
  maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
4370
4356
  accept: this.#acceptMask(),
4357
+ cursor: -1,
4358
+ registrationDigest: registrationDigest([]),
4359
+ echoDigest: new Uint8Array(),
4371
4360
  };
4372
4361
  const {
4373
4362
  pushFrames,
@@ -4384,15 +4373,32 @@ export class SyncClient {
4384
4373
  this.#hasBlobs &&
4385
4374
  this.#config.blobs !== undefined
4386
4375
  ) {
4387
- await this.#flushBlobUploads();
4376
+ const refused = await this.#flushBlobUploads(signal);
4377
+ // §5.9.7: a commit whose blob the server refused left the outbox.
4378
+ for (let index = outbox.length - 1; index >= 0; index--) {
4379
+ if (!refused.has(outbox[index]!.clientCommitId)) continue;
4380
+ outbox.splice(index, 1);
4381
+ pushFrames.splice(index, 1);
4382
+ frameBytes.splice(index, 1);
4383
+ }
4388
4384
  }
4389
4385
  // Captured after encoding: a subscribe/unsubscribe during the
4390
4386
  // encryption await must not make the final request exceed the byte
4391
4387
  // budget, and the reset epoch must be the one the response apply checks.
4392
4388
  const resetEpoch = this.#localResetEpoch;
4393
- const subs = loadSubscriptions(this.#db).filter(
4394
- (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),
4395
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);
4396
4402
  // §1.5: a kept round-failure code rides every request until a round
4397
4403
  // completes, immediately after REQ_HEADER.
4398
4404
  const report = this.#roundFailureCode;
@@ -4402,29 +4408,35 @@ export class SyncClient {
4402
4408
  ? [{ type: 'ROUND_FAILURE' as const, code: report }]
4403
4409
  : []),
4404
4410
  pull,
4405
- ...subs.map(
4406
- (sub): RequestFrame =>
4407
- definedObject({
4408
- type: 'SUBSCRIPTION',
4409
- id: sub.id,
4410
- table: sub.table,
4411
- scopes: sub.scopes,
4412
- params: sub.params,
4413
- cursor: sub.cursor,
4414
- bootstrapState: sub.bootstrapState,
4415
- }),
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
+ ],
4416
4428
  ),
4417
4429
  ];
4418
4430
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
4419
- // sit between them and the pull/subscription tail (§1.5 ordering).
4431
+ // sit between them and the pull/unit/progress tail (§1.5 ordering).
4420
4432
  const lead = fixedFrames.slice(0, report !== undefined ? 2 : 1);
4421
4433
  let admitted = pushFrames.length;
4422
4434
  let deferred = encodedDeferred;
4423
4435
  if (byteCap !== undefined) {
4424
4436
  // The fixed frames encode as envelope + fixed frames + END; each
4425
4437
  // admitted push frame adds its own (5 + payload). Trimming the tail
4426
- // re-fits the request to the final subscription state.
4427
- const fixedBytes = encodeMessage({
4438
+ // re-fits the request to the final registration state.
4439
+ const fixedBytes = encodeRequest({
4428
4440
  wireVersion: PROTOCOL_WIRE_VERSION,
4429
4441
  msgKind: 'request',
4430
4442
  frames: fixedFrames,
@@ -4454,24 +4466,22 @@ export class SyncClient {
4454
4466
  ...pushFrames,
4455
4467
  ...fixedFrames.slice(lead.length),
4456
4468
  ];
4457
- const requestBytes = encodeMessage({
4469
+ const requestBytes = encodeRequest({
4458
4470
  wireVersion: PROTOCOL_WIRE_VERSION,
4459
4471
  msgKind: 'request',
4460
4472
  frames,
4461
4473
  });
4462
- const responseBytes = await this.#roundTrip(requestBytes);
4463
- const message = decodeMessage(responseBytes);
4464
- if (message.msgKind !== 'response') {
4465
- throw invalidRequest('transport returned a non-response message');
4466
- }
4474
+ const responseBytes = await this.#roundTrip(requestBytes, signal);
4475
+ const message = decodeResponse(responseBytes);
4467
4476
  // §1.5: a complete, decodable response ends the report obligation.
4468
4477
  this.#roundFailureCode = undefined;
4469
4478
  const summary = await this.#processResponse(
4470
4479
  message,
4471
4480
  outbox,
4472
- subs,
4481
+ bytesToHex(pull.registrationDigest),
4473
4482
  'pull',
4474
4483
  resetEpoch,
4484
+ signal,
4475
4485
  );
4476
4486
  // §4.8 E1: the push half may have drained commits that pinned rows of
4477
4487
  // a shrunk window unit — retry any deferred evictions now.
@@ -4482,6 +4492,9 @@ export class SyncClient {
4482
4492
  : { state: 'complete' },
4483
4493
  );
4484
4494
  this.#retryDelayMs = 250;
4495
+ // §7.1: a unit still catching up needs another round, also when the
4496
+ // drive that started its bootstrap ends early.
4497
+ if (summary.bootstrapping.length > 0) this.#setSyncNeeded(true);
4485
4498
  if (deferred > 0) {
4486
4499
  // §6.1 splitBatch remainder: more queued commits than this request
4487
4500
  // could carry — keep the sync-needed signal raised for the host.
@@ -4489,11 +4502,14 @@ export class SyncClient {
4489
4502
  return { ...summary, deferredCommits: deferred };
4490
4503
  }
4491
4504
  return summary;
4492
- } catch (error) {
4505
+ } catch (caught) {
4493
4506
  // §1.5: a round that ended without a complete, decodable response is a
4494
4507
  // failure the server could not see — keep its code for the next request.
4495
- const unseen = this.#unseenRoundFailureCode(error);
4508
+ const unseen = this.#unseenRoundFailureCode(caught);
4496
4509
  if (unseen !== undefined) this.#roundFailureCode = unseen;
4510
+ // §7.8: a round the drive deadline aborted ends with the deadline's
4511
+ // error, whichever transport call observed the abort.
4512
+ const error: unknown = signal?.aborted === true ? signal.reason : caught;
4497
4513
  // §7.3.5: a request-level lease code stops-and-surfaces — record it
4498
4514
  // in leaseState (no local-data purge, §7.3.4) and re-throw. Not a
4499
4515
  // silent retry: the app drives recovery to a live resolver. The
@@ -4527,6 +4543,8 @@ export class SyncClient {
4527
4543
  ? details.causeKind
4528
4544
  : undefined;
4529
4545
  const unreachable = causeKind === 'connect' || causeKind === 'network';
4546
+ // The round's work is still owed; the host's connectivity resume runs it.
4547
+ if (unreachable) this.#setSyncNeeded(true);
4530
4548
  if (retryable && !unreachable) {
4531
4549
  const realtimeUnavailable = error instanceof RealtimeUnavailableError;
4532
4550
  const delay = realtimeUnavailable
@@ -4563,7 +4581,7 @@ export class SyncClient {
4563
4581
  * Callers that arrive during the same drive with the same budget share that
4564
4582
  * single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
4565
4583
  *
4566
- * §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
4567
4585
  * 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
4568
4586
  * aborts a socket round in flight; the round budget does not bound elapsed
4569
4587
  * time, and a transport that never answers must not hang the caller.
@@ -4577,13 +4595,9 @@ export class SyncClient {
4577
4595
  typeof options === 'number'
4578
4596
  ? SYNC_IDLE_TIMEOUT_MS
4579
4597
  : (options?.timeoutMs ?? SYNC_IDLE_TIMEOUT_MS);
4580
- // §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,
4581
4599
  // fractional, and out-of-range values are caller errors.
4582
- if (
4583
- maxRounds !== undefined &&
4584
- (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
4585
- )
4586
- throw invalidRequest('maxRounds must be a positive integer');
4600
+ requireRoundBudget(maxRounds);
4587
4601
  if (
4588
4602
  timeoutMs !== Number.POSITIVE_INFINITY &&
4589
4603
  !(Number.isFinite(timeoutMs) && timeoutMs > 0)
@@ -4621,17 +4635,8 @@ export class SyncClient {
4621
4635
  ): Promise<SyncIdleResult> {
4622
4636
  const budget = maxRounds ?? 20;
4623
4637
  const aggregate = {
4624
- pushed: 0,
4625
- applied: [] as string[],
4626
- rejected: [] as string[],
4627
- retryable: [] as string[],
4628
- conflicts: [] as ConflictRecord[],
4629
- commitsApplied: 0,
4630
- segmentRowsApplied: 0,
4638
+ ...emptySummary(0),
4631
4639
  bootstrapping: [] as string[],
4632
- resets: [] as string[],
4633
- revoked: [] as string[],
4634
- failed: [] as string[],
4635
4640
  deferredCommits: 0,
4636
4641
  schemaFloor: undefined as SchemaFloor | undefined,
4637
4642
  };
@@ -4658,42 +4663,37 @@ export class SyncClient {
4658
4663
  let round = 0;
4659
4664
  let expired = false;
4660
4665
  let timer: ReturnType<typeof setTimeout> | undefined;
4666
+ // One signal reaches every transport call of the drive's rounds.
4667
+ const controller = new AbortController();
4668
+ const expiredError = () =>
4669
+ new ClientSyncError(
4670
+ 'sync.idle_timeout',
4671
+ 'syncUntilIdle exceeded its deadline',
4672
+ true,
4673
+ { timeoutMs, rounds: round },
4674
+ );
4661
4675
  const deadline =
4662
4676
  timeoutMs === Number.POSITIVE_INFINITY
4663
4677
  ? undefined
4664
4678
  : new Promise<never>((_, reject) => {
4665
4679
  timer = setTimeout(() => {
4666
4680
  expired = true;
4681
+ const error = expiredError();
4667
4682
  // The transport may never answer; release the round so the
4668
4683
  // client can run another one after the caller sees the error.
4684
+ controller.abort(error);
4669
4685
  this.#abortPendingRound('syncUntilIdle deadline exceeded');
4670
- reject(
4671
- new ClientSyncError(
4672
- 'sync.idle_timeout',
4673
- 'syncUntilIdle exceeded its deadline',
4674
- true,
4675
- { timeoutMs, rounds: round },
4676
- ),
4677
- );
4686
+ reject(error);
4678
4687
  }, timeoutMs);
4679
4688
  });
4680
4689
  const drive = (async (): Promise<SyncIdleResult> => {
4681
4690
  for (; round < budget; round++) {
4682
4691
  // The race already rejected; stop spending rounds on a dead drive.
4683
- if (expired)
4684
- throw new ClientSyncError(
4685
- 'sync.idle_timeout',
4686
- 'syncUntilIdle exceeded its deadline',
4687
- true,
4688
- { timeoutMs, rounds: round },
4689
- );
4692
+ if (expired) throw expiredError();
4690
4693
  const before = JSON.stringify(
4691
- loadSubscriptions(this.#db).map((sub) => [
4692
- sub.id,
4693
- sub.bootstrapState,
4694
- ]),
4694
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4695
4695
  );
4696
- const last = await this.sync();
4696
+ const last = await this.#sync(controller.signal);
4697
4697
  // Historical counters accumulate; current readiness (`bootstrapping`,
4698
4698
  // `deferredCommits`, `schemaFloor`) describes the latest round.
4699
4699
  aggregate.pushed += last.pushed;
@@ -4718,10 +4718,7 @@ export class SyncClient {
4718
4718
  last.bootstrapping.length > 0 &&
4719
4719
  before !==
4720
4720
  JSON.stringify(
4721
- loadSubscriptions(this.#db).map((sub) => [
4722
- sub.id,
4723
- sub.bootstrapState,
4724
- ]),
4721
+ loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
4725
4722
  )
4726
4723
  )
4727
4724
  round = -1;
@@ -4756,7 +4753,10 @@ export class SyncClient {
4756
4753
  * refuses the round with `RealtimeUnavailableError` instead of using the
4757
4754
  * seam (SPEC §8.8).
4758
4755
  */
4759
- #roundTrip(request: Uint8Array): Promise<Uint8Array> {
4756
+ #roundTrip(
4757
+ request: Uint8Array,
4758
+ signal: AbortSignal | undefined,
4759
+ ): Promise<Uint8Array> {
4760
4760
  const socket = this.#socket;
4761
4761
  if (socket !== undefined && this.#realtimePolicy !== 'off') {
4762
4762
  return new Promise<Uint8Array>((resolve, reject) => {
@@ -4777,12 +4777,9 @@ export class SyncClient {
4777
4777
  // Rust core records when its realtime round call fails (§8.8).
4778
4778
  this.#setRealtimeState('lost', 'sync.transport_failed');
4779
4779
  reject(
4780
- new ClientSyncError(
4781
- 'sync.transport_failed',
4782
- 'socket round send failed',
4783
- true,
4784
- { causeKind: 'unknown' },
4785
- ),
4780
+ transportFailed('socket round send failed', {
4781
+ causeKind: 'unknown',
4782
+ }),
4786
4783
  );
4787
4784
  }
4788
4785
  });
@@ -4793,7 +4790,7 @@ export class SyncClient {
4793
4790
  throw this.#realtimeUnavailableError();
4794
4791
  }
4795
4792
  return Promise.resolve()
4796
- .then(() => this.#config.transport(request))
4793
+ .then(() => this.#config.transport(request, signal))
4797
4794
  .catch((error: unknown) => {
4798
4795
  if (
4799
4796
  error instanceof ClientSyncError ||
@@ -4801,12 +4798,9 @@ export class SyncClient {
4801
4798
  ) {
4802
4799
  throw error;
4803
4800
  }
4804
- throw new ClientSyncError(
4805
- 'sync.transport_failed',
4806
- 'transport round failed',
4807
- true,
4808
- { causeKind: 'unknown' },
4809
- );
4801
+ throw transportFailed('transport round failed', {
4802
+ causeKind: 'unknown',
4803
+ });
4810
4804
  });
4811
4805
  }
4812
4806
 
@@ -4832,11 +4826,11 @@ export class SyncClient {
4832
4826
  }
4833
4827
 
4834
4828
  /** Abort the in-flight socket round (socket closed or disconnected). */
4835
- #abortPendingRound(reason: string): void {
4829
+ #abortPendingRound(reason: string | ClientSyncError): void {
4836
4830
  const round = this.#pendingRound;
4837
4831
  if (round === undefined) return;
4838
4832
  this.#pendingRound = undefined;
4839
- round.reject(new ClientSyncError('sync.transport_failed', reason, true));
4833
+ round.reject(typeof reason === 'string' ? transportFailed(reason) : reason);
4840
4834
  }
4841
4835
 
4842
4836
  // -- realtime (§8 client side) ----------------------------------------------
@@ -4898,27 +4892,34 @@ export class SyncClient {
4898
4892
  }
4899
4893
  let openedSocket: RealtimeSocket | undefined;
4900
4894
  try {
4901
- const socket = await connector({
4902
- onText: (text) => {
4903
- if (generation !== this.#realtimeGeneration || !this.#started) return;
4904
- this.#handleRealtimeText(text);
4905
- },
4906
- onBinary: (bytes) => {
4907
- if (generation !== this.#realtimeGeneration || !this.#started) return;
4908
- this.#routeRealtimeBinary(bytes);
4909
- },
4910
- onClose: () => {
4911
- if (openedSocket === undefined || this.#socket !== openedSocket)
4912
- return;
4913
- this.#socket = undefined;
4914
- this.#presence.clear(); // §8.6.1: presence is per-connection
4915
- // §8.8: an undesired close is a visible lost state, not a silent
4916
- // downgrade to HTTP rounds.
4917
- this.#setRealtimeState('lost', REALTIME_LOST_CODE);
4918
- this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
4919
- this.#emitDiagnostics();
4895
+ const socket = await connector(
4896
+ {
4897
+ onText: (text) => {
4898
+ if (generation !== this.#realtimeGeneration || !this.#started)
4899
+ return;
4900
+ this.#heard(this.#handleRealtimeText(text));
4901
+ },
4902
+ onBinary: (bytes) => {
4903
+ if (generation !== this.#realtimeGeneration || !this.#started)
4904
+ return;
4905
+ this.#heard();
4906
+ this.#routeRealtimeBinary(bytes);
4907
+ },
4908
+ onClose: () => {
4909
+ if (openedSocket === undefined || this.#socket !== openedSocket)
4910
+ return;
4911
+ this.#socket = undefined;
4912
+ this.#disarm();
4913
+ this.#presence.clear(); // §8.6.1: presence is per-connection
4914
+ // §8.8: an undesired close is a visible lost state, not a silent
4915
+ // downgrade to HTTP rounds.
4916
+ this.#setRealtimeState('lost', REALTIME_LOST_CODE);
4917
+ this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
4918
+ this.#emitDiagnostics();
4919
+ },
4920
4920
  },
4921
- });
4921
+ this.#clientId,
4922
+ );
4922
4923
  openedSocket = socket;
4923
4924
  if (!this.#transportEnabled) {
4924
4925
  socket.close();
@@ -4952,6 +4953,7 @@ export class SyncClient {
4952
4953
  this.#realtimeConnectPromise = undefined;
4953
4954
  this.#socket?.close();
4954
4955
  this.#socket = undefined;
4956
+ this.#disarm();
4955
4957
  this.#presence.clear(); // §8.6.1: presence is per-connection
4956
4958
  this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
4957
4959
  this.#setRealtimeState(
@@ -4969,15 +4971,49 @@ export class SyncClient {
4969
4971
  * Close the socket and record the loss; later rounds use the configured
4970
4972
  * transport until the supervisor reconnects.
4971
4973
  */
4972
- #loseSocket(): void {
4974
+ #loseSocket(code = REALTIME_LOST_CODE): void {
4973
4975
  const socket = this.#socket;
4974
4976
  this.#socket = undefined;
4977
+ this.#disarm();
4975
4978
  this.#presence.clear(); // §8.6.1: presence is per-connection
4976
- this.#setRealtimeState('lost', REALTIME_LOST_CODE);
4979
+ this.#setRealtimeState('lost', code);
4977
4980
  socket?.close();
4978
4981
  this.#emitDiagnostics();
4979
4982
  }
4980
4983
 
4984
+ /**
4985
+ * SPEC §8.5 watchdog: the connection's first `heartbeat` arms it; once
4986
+ * armed, every inbound frame restarts it, and twice the interval of
4987
+ * silence loses the socket. A server that sends no heartbeats never arms it.
4988
+ */
4989
+ #heard(heartbeat?: boolean): void {
4990
+ if (
4991
+ this.#socket === undefined ||
4992
+ !this.#transportEnabled ||
4993
+ (this.#watchdog === undefined && heartbeat !== true)
4994
+ )
4995
+ return;
4996
+ this.#watchdog?.();
4997
+ this.#watchdog = this.#schedule(() => {
4998
+ this.#loseSocket('transport.timeout');
4999
+ this.#abortPendingRound(
5000
+ new ClientSyncError(
5001
+ 'transport.timeout',
5002
+ 'realtime heartbeat missed',
5003
+ true,
5004
+ {
5005
+ causeKind: 'heartbeat',
5006
+ },
5007
+ ),
5008
+ );
5009
+ }, 2 * this.#heartbeatMs);
5010
+ }
5011
+
5012
+ #disarm(): void {
5013
+ this.#watchdog?.();
5014
+ this.#watchdog = undefined;
5015
+ }
5016
+
4981
5017
  /**
4982
5018
  * §8.7 channel-tag routing (synchronous, so chunk order is preserved):
4983
5019
  * `0x01` chunks feed the in-flight round's assembler; `0x00` messages
@@ -5017,7 +5053,8 @@ export class SyncClient {
5017
5053
  // Unknown tag: tolerated and ignored (§8.7 closed registry).
5018
5054
  }
5019
5055
 
5020
- #handleRealtimeText(text: string): void {
5056
+ /** Returns whether the text was a §8.5 `heartbeat`. */
5057
+ #handleRealtimeText(text: string): boolean | undefined {
5021
5058
  let parsed: ReturnType<typeof parseRealtimeServerEvent>;
5022
5059
  try {
5023
5060
  parsed = parseRealtimeServerEvent(text);
@@ -5039,47 +5076,38 @@ export class SyncClient {
5039
5076
  this.#emitSyncNeeded(event.data.reason);
5040
5077
  return;
5041
5078
  }
5042
- if (event.event === 'presence') {
5043
- this.#applyPresence(event.data);
5044
- }
5045
- }
5046
-
5047
- /** §8.6 apply an inbound presence fanout to the local map. */
5048
- #applyPresence(data: {
5049
- scopeKey: string;
5050
- kind?: PresenceKind;
5051
- actorId?: string;
5052
- clientId?: string;
5053
- doc?: Record<string, unknown> | null;
5054
- error?: string;
5055
- }): void {
5056
- // The publisher-directed error variant (§8.6.2) surfaces via the
5057
- // sync-needed reason channel is inappropriate; it is an out-of-band
5058
- // presence rejection — record nothing to the peer map, just ignore
5059
- // here (setPresence callers observe it through the callback if wired).
5060
- if (data.error !== undefined || data.kind === undefined) return;
5061
- const { scopeKey, kind, actorId, clientId } = data;
5062
- if (actorId === undefined || clientId === undefined) return;
5063
- const peerKey = `${actorId} ${clientId}`;
5064
- let peers = this.#presence.get(scopeKey);
5065
- if (kind === 'leave') {
5066
- peers?.delete(peerKey);
5067
- if (peers !== undefined && peers.size === 0) {
5068
- this.#presence.delete(scopeKey);
5069
- }
5070
- } else {
5071
- const doc = data.doc;
5072
- if (doc === null || doc === undefined) return;
5073
- if (peers === undefined) {
5074
- peers = new Map();
5075
- this.#presence.set(scopeKey, peers);
5079
+ if (event.event === 'presence') this.#applyPresence(event.data);
5080
+ return event.event === 'heartbeat';
5081
+ }
5082
+
5083
+ /**
5084
+ * §8.6 apply an inbound presence fanout to the local map, or hand a
5085
+ * publisher-directed rejection (§8.6.2) to the listeners unchanged.
5086
+ */
5087
+ #applyPresence(data: RealtimePresenceEvent['data']): void {
5088
+ const { scopeKey, kind, actorId, clientId, doc, error } = data;
5089
+ if (error === undefined) {
5090
+ // No `kind` is the client→server shape. The parser pins both ids and a
5091
+ // join/update doc on a fanout (§8.6.2); these checks narrow types.
5092
+ if (kind === undefined || actorId === undefined || clientId === undefined)
5093
+ return;
5094
+ const peerKey = `${actorId} ${clientId}`;
5095
+ let peers = this.#presence.get(scopeKey);
5096
+ if (kind === 'leave') {
5097
+ peers?.delete(peerKey);
5098
+ if (peers?.size === 0) this.#presence.delete(scopeKey);
5099
+ } else if (doc) {
5100
+ if (peers === undefined) {
5101
+ peers = new Map();
5102
+ this.#presence.set(scopeKey, peers);
5103
+ }
5104
+ peers.set(peerKey, { actorId, clientId, doc });
5076
5105
  }
5077
- peers.set(peerKey, { actorId, clientId, doc });
5078
5106
  }
5079
- this.#config.onPresence?.(scopeKey);
5107
+ this.#config.onPresence?.(scopeKey, error);
5080
5108
  for (const listener of this.#presenceListeners) {
5081
5109
  try {
5082
- listener(scopeKey);
5110
+ listener(scopeKey, error);
5083
5111
  } catch {
5084
5112
  // A UI listener must never break presence application.
5085
5113
  }
@@ -5109,8 +5137,7 @@ export class SyncClient {
5109
5137
  return;
5110
5138
  }
5111
5139
  try {
5112
- const message = decodeMessage(bytes);
5113
- if (message.msgKind !== 'response') return;
5140
+ const message = decodeResponse(bytes);
5114
5141
  // §8.2: deltas apply like pull responses; ack after apply.
5115
5142
  await this.#processResponse(message, [], undefined, 'delta');
5116
5143
  } catch {
@@ -5126,35 +5153,31 @@ export class SyncClient {
5126
5153
  this.#socket?.send(JSON.stringify({ type: 'ack', cursor }));
5127
5154
  }
5128
5155
 
5129
- /** 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`. */
5130
5157
  #ackAfterPull(): void {
5131
- if (this.#socket === undefined) return;
5132
- const cursors = loadSubscriptions(this.#db)
5133
- .filter(
5134
- (sub) => sub.status === 'active' && sub.bootstrapState === undefined,
5135
- )
5136
- .map((sub) => sub.cursor)
5137
- .filter((cursor) => cursor >= 0);
5138
- if (cursors.length === 0) return;
5139
- this.#sendAck(Math.min(...cursors));
5158
+ const cursor = replicaCursor(this.#db);
5159
+ if (this.#socket !== undefined && cursor >= 0) this.#sendAck(cursor);
5140
5160
  }
5141
5161
 
5142
5162
  // -- response processing ------------------------------------------------------
5143
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
+ */
5144
5169
  async #processResponse(
5145
5170
  message: ResponseMessage,
5146
5171
  sentCommits: readonly OutboxCommit[],
5147
- sentSubs: readonly SubscriptionRecord[] | undefined,
5172
+ sentDigest: string | undefined,
5148
5173
  mode: 'pull' | 'delta',
5149
5174
  resetEpoch: number = this.#localResetEpoch,
5175
+ signal?: AbortSignal,
5150
5176
  ): Promise<SyncSummary> {
5151
5177
  const summary = emptySummary(sentCommits.length);
5152
5178
  const commitsById = new Map(
5153
5179
  sentCommits.map((commit) => [commit.clientCommitId, commit]),
5154
5180
  );
5155
- const subsById = new Map(
5156
- (sentSubs ?? loadSubscriptions(this.#db)).map((sub) => [sub.id, sub]),
5157
- );
5158
5181
  const rejectionDetailsByCommit = new Map<
5159
5182
  string,
5160
5183
  ReadonlyMap<number, RejectionDetails>
@@ -5179,16 +5202,6 @@ export class SyncClient {
5179
5202
  if (header?.type !== 'RESP_HEADER') {
5180
5203
  throw invalidRequest('missing RESP_HEADER');
5181
5204
  }
5182
- if (
5183
- message.wireVersion < 2 ||
5184
- header.logEpoch === undefined ||
5185
- header.resetRequired === undefined
5186
- ) {
5187
- throw new ClientSyncError(
5188
- 'client.invalid_host_response',
5189
- 'the server response does not carry wire version 2 log-epoch state',
5190
- );
5191
- }
5192
5205
  if (header.requiredSchemaVersion !== undefined) {
5193
5206
  // §1.6 schema floor: nothing else was processed — stop syncing and
5194
5207
  // surface the upgrade requirement. A live-round floor always stops:
@@ -5231,121 +5244,69 @@ export class SyncClient {
5231
5244
 
5232
5245
  let section: OpenSection | undefined;
5233
5246
  let errorFrame: ClientSyncError | undefined;
5247
+ let liveStart: LiveStartFrame | undefined;
5248
+ let liveEnded = false;
5234
5249
  let deltaCursor = -1;
5235
- const incompleteSubscriptions = new Set(
5236
- mode === 'pull' ? subsById.keys() : [],
5237
- );
5238
-
5239
- // §5.4/§5.5: issue every segment download of this response before the
5240
- // apply loop reaches the first one, so a paged bootstrap overlaps its page
5241
- // fetches instead of paying one blocking round trip per page. Eligibility
5242
- // mirrors the loop: a descriptor outside an applied section, inside a
5243
- // skipped delta section, or from an unconfigured downloader is never
5244
- // fetched, and a prefetched failure is only observed where the loop awaits
5245
- // it. A promise left over because an earlier frame ended apply is handled
5246
- // at creation, never unhandled.
5250
+ let deltaDropped = false;
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[] = [];
5254
+
5255
+ // §5.4/§5.5: queue every segment download of this response, so a paged
5256
+ // bootstrap overlaps its page fetches instead of paying one blocking round
5257
+ // trip per page. At most four downloads run at once, the Rust native
5258
+ // transport's pool size: enough to overlap round trips, while the client
5259
+ // holds at most four bodies, the one being applied and three ahead. The
5260
+ // loop takes each body out of the map before applying it and tops the
5261
+ // window up at the next descriptor. Eligibility mirrors the loop: a
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][] = [];
5247
5267
  const prefetched = new Map<SegmentRefFrame, Promise<Uint8Array>>();
5268
+ const prefetch = () => {
5269
+ for (let next; prefetched.size < 4 && (next = queued.shift());) {
5270
+ const [frame, scopes] = next;
5271
+ const pending = this.#downloadSegment(
5272
+ frame,
5273
+ scopes,
5274
+ (bytes) => {
5275
+ // Only the descriptor the loop is applying reports bytes; a
5276
+ // sibling still in flight would overwrite its progress.
5277
+ if (reporting === frame)
5278
+ this.#progress.update({ bytesReceived: bytes });
5279
+ },
5280
+ signal,
5281
+ );
5282
+ pending.catch(() => {});
5283
+ prefetched.set(frame, pending);
5284
+ }
5285
+ };
5248
5286
  let reporting: SegmentRefFrame | undefined;
5249
- const deleteKey = (commitSeq: number, table: string, rowId: string) =>
5250
- `${commitSeq}\u0000${table}\u0000${rowId}`;
5251
- {
5252
- let openSub: SubscriptionRecord | undefined;
5287
+ if (mode === 'pull') {
5288
+ let open: UnitRecord | undefined;
5253
5289
  for (const frame of message.frames) {
5254
5290
  if (frame.type === 'SUB_START') {
5255
- const sub = subsById.get(frame.id);
5256
- openSub =
5257
- sub === undefined ||
5258
- (mode === 'delta' &&
5259
- (sub.status !== 'active' || sub.bootstrapState !== undefined))
5260
- ? undefined
5261
- : sub;
5262
- } else if (frame.type === 'SUB_END') {
5263
- 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;
5264
5295
  } else if (frame.type === 'ERROR') {
5265
5296
  break; // the round fails at this frame: later refs are not fetched
5266
5297
  } else if (
5267
5298
  frame.type === 'SEGMENT_REF' &&
5268
- openSub !== undefined &&
5299
+ open !== undefined &&
5269
5300
  this.#config.segments !== undefined &&
5270
5301
  !(
5271
5302
  frame.mediaType === 'sqlite' &&
5272
5303
  (this.#acceptMask() & ACCEPT_SQLITE) === 0
5273
5304
  )
5274
5305
  ) {
5275
- const pending = this.#downloadSegment(frame, openSub, (bytes) => {
5276
- // Only the descriptor the loop is applying reports bytes; a
5277
- // sibling still in flight would overwrite its progress.
5278
- if (reporting === frame)
5279
- this.#progress.update({ bytesReceived: bytes });
5280
- });
5281
- pending.catch(() => {});
5282
- prefetched.set(frame, pending);
5283
- }
5284
- }
5285
- }
5286
-
5287
- // §2.2 scope migration: the server emits the delete tagged with the old
5288
- // scope and the upsert tagged with the new one in one commit. A reader
5289
- // that holds both scopes receives them in two subscription sections, so
5290
- // the section order would otherwise decide whether the row survives. One
5291
- // commit's delete and upsert of the same row are one change, and the
5292
- // upsert wins. A frame that carries both itself keeps its own operation
5293
- // order; only a pair split across sections is coalesced.
5294
- const coalescedDeletes = new Set<string>();
5295
- {
5296
- const ops = new Map<
5297
- string,
5298
- { readonly upserts: Set<number>; readonly deletes: Set<number> }
5299
- >();
5300
- const bothInFrame = new Set<string>();
5301
- let openSub: SubscriptionRecord | undefined;
5302
- let frameIndex = -1;
5303
- for (const frame of message.frames) {
5304
- if (frame.type === 'SUB_START') {
5305
- const sub = subsById.get(frame.id);
5306
- openSub =
5307
- sub === undefined ||
5308
- (mode === 'delta' &&
5309
- (sub.status !== 'active' || sub.bootstrapState !== undefined))
5310
- ? undefined
5311
- : sub;
5312
- } else if (frame.type === 'SUB_END') {
5313
- openSub = undefined;
5314
- } else if (frame.type === 'ERROR') {
5315
- break;
5316
- } else if (frame.type === 'COMMIT' && openSub !== undefined) {
5317
- frameIndex += 1;
5318
- const local = new Map<string, number>();
5319
- for (const change of frame.changes) {
5320
- const table = frame.tables[change.tableIndex];
5321
- if (table === undefined) continue;
5322
- const key = deleteKey(frame.commitSeq, table, change.rowId);
5323
- const entry = ops.get(key) ?? {
5324
- upserts: new Set<number>(),
5325
- deletes: new Set<number>(),
5326
- };
5327
- if (change.op === 'upsert') entry.upserts.add(frameIndex);
5328
- else entry.deletes.add(frameIndex);
5329
- ops.set(key, entry);
5330
- local.set(
5331
- key,
5332
- (local.get(key) ?? 0) | (change.op === 'upsert' ? 1 : 2),
5333
- );
5334
- }
5335
- for (const [key, seen] of local) {
5336
- if (seen === 3) bothInFrame.add(key);
5337
- }
5338
- }
5339
- }
5340
- for (const [key, entry] of ops) {
5341
- if (
5342
- !bothInFrame.has(key) &&
5343
- entry.upserts.size > 0 &&
5344
- entry.deletes.size > 0
5345
- ) {
5346
- coalescedDeletes.add(key);
5306
+ queued.push([frame, open.scopes]);
5347
5307
  }
5348
5308
  }
5309
+ prefetch();
5349
5310
  }
5350
5311
 
5351
5312
  // Each durable observer transaction emits its own revisioned batch.
@@ -5430,53 +5391,28 @@ export class SyncClient {
5430
5391
  // Pre-indexed above so companion ordering remains wire-additive.
5431
5392
  break;
5432
5393
  case 'SUB_START': {
5433
- const sub = subsById.get(frame.id);
5434
- const fresh =
5435
- sub !== undefined &&
5436
- sub.cursor < 0 &&
5437
- sub.bootstrapState === undefined &&
5438
- frame.bootstrap;
5439
- const skip =
5440
- sub === undefined ||
5441
- (mode === 'delta' &&
5442
- (sub.status !== 'active' || sub.bootstrapState !== undefined));
5443
- 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;
5444
5410
  break;
5445
5411
  }
5446
- case 'COMMIT':
5447
- if (
5448
- section !== undefined &&
5449
- !section.skip &&
5450
- section.sub !== undefined
5451
- ) {
5452
- const changes = frame.changes.filter((change) => {
5453
- if (change.op !== 'delete') return true;
5454
- const table = frame.tables[change.tableIndex];
5455
- return (
5456
- table === undefined ||
5457
- !coalescedDeletes.has(
5458
- deleteKey(frame.commitSeq, table, change.rowId),
5459
- )
5460
- );
5461
- });
5462
- if (changes.length > 0) {
5463
- await this.#applyCommit(
5464
- { ...frame, changes },
5465
- summary,
5466
- section.sub.id,
5467
- mode,
5468
- );
5469
- }
5470
- }
5471
- break;
5472
5412
  case 'SEGMENT_INLINE':
5473
5413
  case 'SEGMENT_REF': {
5474
- if (
5475
- section === undefined ||
5476
- section.skip ||
5477
- section.sub === undefined
5478
- )
5479
- break;
5414
+ if (section === undefined || section.skip) break;
5415
+ const unitId = section.unit.id;
5480
5416
  if (
5481
5417
  frame.type === 'SEGMENT_REF' &&
5482
5418
  frame.mediaType === 'sqlite' &&
@@ -5490,7 +5426,7 @@ export class SyncClient {
5490
5426
  if (frame.type === 'SEGMENT_REF') {
5491
5427
  this.#progress.update({
5492
5428
  phase: 'download',
5493
- subscriptionId: section.sub.id,
5429
+ unitId,
5494
5430
  table: frame.table,
5495
5431
  segmentId: frame.segmentId,
5496
5432
  bytesReceived: 0,
@@ -5498,125 +5434,204 @@ export class SyncClient {
5498
5434
  rowsProcessed: 0,
5499
5435
  rowsTotal: frame.rowCount,
5500
5436
  });
5501
- const prefetch = prefetched.get(frame);
5502
- if (prefetch !== undefined) reporting = frame;
5503
- bytes = await (prefetch ??
5504
- this.#downloadSegment(frame, section.sub, (bytesReceived) =>
5505
- this.#progress.update({ bytesReceived }),
5437
+ prefetch();
5438
+ const pending = prefetched.get(frame);
5439
+ prefetched.delete(frame);
5440
+ if (pending !== undefined) reporting = frame;
5441
+ bytes = await (pending ??
5442
+ this.#downloadSegment(
5443
+ frame,
5444
+ section.unit.scopes,
5445
+ (bytesReceived) => this.#progress.update({ bytesReceived }),
5446
+ signal,
5506
5447
  ));
5448
+ this.#progress.update({ phase: 'import' });
5507
5449
  } else {
5508
5450
  bytes = frame.payload;
5509
5451
  }
5510
- if (frame.type === 'SEGMENT_REF')
5511
- this.#progress.update({ phase: 'import' });
5512
- if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
5513
- // Images are whole-table; paged image descriptors are invalid.
5514
- if (
5515
- frame.rowCursor !== undefined ||
5516
- frame.nextRowCursor !== undefined
5517
- ) {
5518
- throw invalidRequest(
5519
- '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,
5520
5495
  );
5521
- }
5522
- await this.#applySegmentOrFail(
5523
- section,
5524
- summary,
5525
- (table, clearFirst, effective) =>
5526
- applySqliteSegment(
5527
- this.#db,
5528
- this.#schema,
5529
- table,
5530
- bytes,
5531
- {
5532
- table: frame.table,
5533
- rowCount: frame.rowCount,
5534
- asOfCommitSeq: frame.asOfCommitSeq,
5535
- scopeDigest: frame.scopeDigest,
5536
- },
5537
- this.#segmentApplyOptions(
5496
+ return image !== undefined
5497
+ ? applySqliteSegment(
5498
+ this.#db,
5499
+ this.#schema,
5538
5500
  table,
5539
- clearFirst,
5540
- effective,
5541
- frame.rowCount > 0,
5542
- resetEpoch,
5543
- ),
5544
- ),
5545
- section.fresh && !section.cleared,
5546
- );
5547
- } else {
5548
- const segment = decodeRowsSegment(bytes);
5549
- if (frame.type === 'SEGMENT_INLINE') {
5550
- this.#progress.update({
5551
- phase: 'import',
5552
- subscriptionId: section.sub.id,
5553
- table: section.sub.table,
5554
- segmentId: undefined,
5555
- bytesReceived: bytes.byteLength,
5556
- bytesTotal: bytes.byteLength,
5557
- rowsProcessed: 0,
5558
- rowsTotal: segment.blocks.reduce(
5559
- (n, block) => n + block.length,
5560
- 0,
5561
- ),
5562
- });
5563
- }
5564
- await this.#applySegmentOrFail(
5565
- section,
5566
- summary,
5567
- (table, clearFirst, effective) =>
5568
- applyRowsSegment(
5569
- this.#db,
5570
- this.#schema,
5571
- table,
5572
- segment,
5573
- this.#segmentApplyOptions(
5501
+ bytes,
5502
+ image,
5503
+ options,
5504
+ )
5505
+ : applyRowsSegment(
5506
+ this.#db,
5507
+ this.#schema,
5574
5508
  table,
5575
- clearFirst,
5576
- effective,
5577
- segment.blocks.some((block) => block.length > 0),
5578
- resetEpoch,
5579
- ),
5580
- this.#encryption,
5581
- ),
5582
- section.fresh &&
5583
- !section.cleared &&
5584
- (frame.type === 'SEGMENT_INLINE' ||
5585
- frame.rowCursor === undefined),
5586
- );
5587
- }
5509
+ segment!,
5510
+ options,
5511
+ this.#encryption,
5512
+ );
5513
+ },
5514
+ );
5588
5515
  break;
5589
5516
  }
5590
5517
  case 'SUB_END': {
5591
- if (
5592
- section?.sub !== undefined &&
5593
- !section.skip &&
5594
- this.#localResetEpoch === resetEpoch
5595
- ) {
5596
- incompleteSubscriptions.delete(section.sub.id);
5597
- }
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.
5598
5521
  if (
5599
5522
  section !== undefined &&
5600
5523
  !section.skip &&
5601
- section.sub !== undefined &&
5602
- // Reset fence: a rebootstrap that landed mid-round already
5603
- // rewound this subscription's cursor; the captured SUB_END
5604
- // state predates the rewind and must stay unpersisted so the
5605
- // next round runs the fresh bootstrap.
5606
5524
  this.#localResetEpoch === resetEpoch
5607
- ) {
5608
- const applied = this.#finishSection(
5609
- section.sub,
5610
- section.start,
5611
- frame.nextCursor,
5612
- frame.bootstrapState,
5613
- 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',
5536
+ );
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] ?? '',
5614
5560
  );
5615
- if (mode === 'delta' && applied) {
5616
- deltaCursor = Math.max(deltaCursor, frame.nextCursor);
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;
5617
5586
  }
5587
+ break;
5618
5588
  }
5619
- 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
+ });
5620
5635
  break;
5621
5636
  }
5622
5637
  case 'ERROR': {
@@ -5658,30 +5673,39 @@ export class SyncClient {
5658
5673
 
5659
5674
  if (errorFrame !== undefined) throw errorFrame;
5660
5675
 
5661
- if (incompleteSubscriptions.size > 0) {
5662
- this.#setSyncNeeded(true);
5663
- this.#emitSyncIntent({ kind: 'interactive' });
5664
- }
5665
-
5666
5676
  if (mode === 'delta') {
5667
5677
  if (deltaCursor >= 0) this.#sendAck(deltaCursor);
5678
+ // §8.2: an unapplied delta is a drop; a pull repairs it.
5679
+ if (deltaDropped) {
5680
+ this.#setSyncNeeded(true);
5681
+ this.#emitSyncNeeded('catchup-required');
5682
+ }
5668
5683
  } else {
5669
5684
  this.#ackAfterPull();
5670
5685
  }
5671
5686
 
5672
- const bootstrapping = loadSubscriptions(this.#db)
5673
- .filter(
5674
- (sub) => sub.status === 'active' && sub.bootstrapState !== undefined,
5675
- )
5676
- .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
+ }
5677
5701
  // §7.4.5: the reset is over once the first post-reset pull round leaves
5678
- // no subscription mid-bootstrap — the tables are rebuilt and current.
5679
- // The epoch check keeps a round that predates a mid-flight rebootstrap
5680
- // 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.
5681
5705
  if (
5682
5706
  this.#upgrading &&
5683
5707
  mode === 'pull' &&
5684
- bootstrapping.length === 0 &&
5708
+ catchingUp.length === 0 &&
5685
5709
  this.#localResetEpoch === resetEpoch
5686
5710
  ) {
5687
5711
  this.#setUpgrading(false);
@@ -5689,7 +5713,7 @@ export class SyncClient {
5689
5713
  // RFC 0005 D7: coverage completion, lease end, scope revocation and TTL are
5690
5714
  // evaluated once per round, after the apply.
5691
5715
  this.#previousVersionLifetimeCheck();
5692
- return { ...summary, bootstrapping };
5716
+ return { ...summary, bootstrapping: catchingUp };
5693
5717
  }
5694
5718
 
5695
5719
  #handlePushResult(
@@ -5883,7 +5907,6 @@ export class SyncClient {
5883
5907
  async #applyCommit(
5884
5908
  frame: CommitFrame,
5885
5909
  summary: MutableSummary,
5886
- subscriptionId: string,
5887
5910
  source: 'delta' | 'pull',
5888
5911
  ): Promise<void> {
5889
5912
  await applyCommitFrame(
@@ -5901,7 +5924,6 @@ export class SyncClient {
5901
5924
  )) {
5902
5925
  if (table !== undefined)
5903
5926
  batch.appliedCommit({
5904
- subscriptionId,
5905
5927
  table,
5906
5928
  commitSeq: frame.commitSeq,
5907
5929
  source,
@@ -5957,8 +5979,12 @@ export class SyncClient {
5957
5979
  }
5958
5980
 
5959
5981
  /** Whether a fresh-bootstrap clear would remove at least one local row. */
5960
- #scopedRowsExist(table: CompiledClientTable, effective: ScopeMap): boolean {
5961
- const scope = localScopePredicate(table, effective);
5982
+ #scopedRowsExist(
5983
+ table: CompiledClientTable,
5984
+ effective: ScopeMap,
5985
+ owners: readonly ScopeMap[],
5986
+ ): boolean {
5987
+ const scope = localScopePredicate(table, effective, owners);
5962
5988
  return (
5963
5989
  scope !== undefined &&
5964
5990
  this.#db.query(
@@ -5973,19 +5999,21 @@ export class SyncClient {
5973
5999
  table: CompiledClientTable,
5974
6000
  clearFirst: boolean,
5975
6001
  effective: ScopeMap,
6002
+ owners: readonly ScopeMap[],
5976
6003
  hasRows: boolean,
5977
6004
  resetEpoch: number,
5978
6005
  ): Parameters<typeof applyRowsSegment>[4] {
5979
6006
  return {
5980
6007
  clearFirst,
5981
6008
  effective,
6009
+ owners,
5982
6010
  isCurrent: () => this.#localResetEpoch === resetEpoch,
5983
6011
  onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
5984
6012
  transaction: (fn) =>
5985
6013
  this.#applyBatch((batch) => {
5986
6014
  if (
5987
6015
  hasRows ||
5988
- (clearFirst && this.#scopedRowsExist(table, effective))
6016
+ (clearFirst && this.#scopedRowsExist(table, effective, owners))
5989
6017
  )
5990
6018
  batch.table(table.name);
5991
6019
  const result = fn();
@@ -5996,66 +6024,64 @@ export class SyncClient {
5996
6024
  }
5997
6025
 
5998
6026
  /**
5999
- * Apply a segment (rows or sqlite image); a §5.6/§3.3 fail-closed error
6000
- * (no local scope-column mapping) marks the subscription `failed` and
6001
- * 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.
6002
6031
  */
6003
6032
  async #applySegmentOrFail(
6004
6033
  section: OpenSection,
6005
6034
  summary: MutableSummary,
6035
+ tableName: string,
6006
6036
  apply: (
6007
6037
  table: CompiledClientTable,
6008
6038
  clearFirst: boolean,
6009
6039
  effective: ScopeMap,
6040
+ owners: readonly ScopeMap[],
6010
6041
  ) => number | Promise<number>,
6011
- clearFirst: boolean,
6012
6042
  ): Promise<void> {
6013
- const sub = section.sub;
6014
- if (sub === undefined) return;
6015
- 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');
6016
6050
  try {
6017
6051
  summary.segmentRowsApplied += await apply(
6018
6052
  table,
6019
- clearFirst,
6020
- section.start.effectiveScopes,
6053
+ !section.seeded.has(tableName),
6054
+ effective,
6055
+ unitOwners(loadUnits(this.#db), table, unit.id),
6021
6056
  );
6022
- section.cleared = true;
6057
+ section.seeded.add(tableName);
6023
6058
  } catch (error) {
6024
6059
  if (
6025
- error instanceof ClientSyncError &&
6026
- error.code === 'sync.scope_revoked'
6027
- ) {
6028
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6029
- this.#applyBatch((batch) => {
6030
- saveSubscription(
6031
- this.#db,
6032
- definedObject({
6033
- id: sub.id,
6034
- table: sub.table,
6035
- scopes: sub.scopes,
6036
- params: sub.params,
6037
- cursor: sub.cursor,
6038
- effectiveScopes: sub.effectiveScopes,
6039
- status: 'failed',
6040
- reasonCode: 'sync.scope_revoked',
6041
- }),
6042
- );
6043
- if (registered !== undefined) {
6044
- batch.window(registered.baseKey, sub.table, registered.unit);
6045
- }
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',
6046
6072
  });
6047
- summary.failed.push(sub.id);
6048
- section.skip = true;
6049
- return;
6050
- }
6051
- 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);
6052
6077
  }
6053
6078
  }
6054
6079
 
6055
6080
  async #downloadSegment(
6056
6081
  frame: SegmentRefFrame,
6057
- sub: SubscriptionRecord,
6082
+ scopes: UnitScopes,
6058
6083
  onProgress: (bytesReceived: number) => void,
6084
+ signal: AbortSignal | undefined,
6059
6085
  ): Promise<Uint8Array> {
6060
6086
  const downloader = this.#config.segments;
6061
6087
  if (downloader === undefined) {
@@ -6089,18 +6115,32 @@ export class SyncClient {
6089
6115
  true,
6090
6116
  );
6091
6117
  }
6092
- bytes = await fetchUrl(frame.url, onProgress);
6118
+ bytes = await fetchUrl(frame.url, onProgress, signal, frame.byteLength);
6093
6119
  } else {
6094
6120
  bytes = await downloader({
6095
6121
  segmentId: frame.segmentId,
6096
6122
  table: frame.table,
6097
- 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
+ ),
6132
+ byteLength: frame.byteLength,
6098
6133
  onProgress,
6134
+ ...(signal !== undefined ? { signal } : {}),
6099
6135
  });
6100
6136
  }
6101
- // §5.1: verify the content address before applying; on mismatch the
6102
- // segment is discarded and the cursor/resume token stay unpersisted,
6103
- // so the next pull re-delivers.
6137
+ // §5.4: the descriptor's byteLength caps the body; §5.1: verify the
6138
+ // content address before applying. On either failure the segment is
6139
+ // discarded and the cursor/resume token stay unpersisted, so the next
6140
+ // pull re-delivers.
6141
+ if (bytes.byteLength > frame.byteLength) {
6142
+ throw invalidRequest('segment exceeds its byteLength', true);
6143
+ }
6104
6144
  onProgress(bytes.byteLength);
6105
6145
  const hash = await sha256Hex(bytes);
6106
6146
  if (`sha256:${hash}` !== frame.segmentId) {
@@ -6113,201 +6153,207 @@ export class SyncClient {
6113
6153
  }
6114
6154
 
6115
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
+ */
6116
6161
  #finishSection(
6117
- sub: SubscriptionRecord,
6118
- start: SubStartFrame,
6119
- nextCursor: number,
6120
- bootstrapState: string | undefined,
6162
+ section: OpenSection,
6163
+ end: SubEndFrame,
6121
6164
  summary: MutableSummary,
6122
- ): boolean {
6123
- if (start.status === 'active') {
6124
- // §1.4 rule 4: durable cursor/resume state persists only at SUB_END;
6125
- // §3.3: the effective-scope echo is persisted for the purge contract.
6126
- // An absent bootstrapState clears any previous resume token (§4.4:
6127
- // absent = bootstrap complete, or not bootstrapping).
6128
- const wasPending = sub.cursor < 0 || sub.bootstrapState !== undefined;
6129
- const completed =
6130
- wasPending && nextCursor >= 0 && bootstrapState === undefined;
6131
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6132
- this.#applyBatch((batch) => {
6133
- saveSubscription(
6134
- this.#db,
6135
- definedObject({
6136
- id: sub.id,
6137
- table: sub.table,
6138
- scopes: sub.scopes,
6139
- params: sub.params,
6140
- cursor: nextCursor,
6141
- bootstrapState: bootstrapState,
6142
- effectiveScopes: start.effectiveScopes,
6143
- status: 'active',
6144
- }),
6145
- );
6146
- if (completed) {
6147
- const table = this.#table(sub.table);
6148
- const effective = start.effectiveScopes;
6149
- const covered = this.#db
6150
- .query(
6151
- `SELECT id,intent,base FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq<=?`,
6152
- [sub.table, nextCursor],
6153
- )
6154
- .filter((row) =>
6155
- [row.intent, row.base].some((json) => {
6156
- if (json === null) return false;
6157
- const values: Record<string, JsonRowValue> = JSON.parse(
6158
- String(json),
6159
- );
6160
- return matchesLocalScopes(table, effective, values);
6161
- }),
6162
- );
6163
- if (covered.length) {
6164
- const scope = covered.map((row) =>
6165
- JSON.stringify([sub.table, String(row.id)]),
6166
- );
6167
- restoreFailedBases(this.#db, this.#schema, scope);
6168
- for (const row of covered)
6169
- this.#db.exec(
6170
- `DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
6171
- [sub.table, String(row.id), nextCursor],
6172
- );
6173
- batch.table(sub.table);
6174
- this.#replayOutbox(scope, false);
6175
- }
6176
- }
6177
- if (completed && registered !== undefined) {
6178
- // A zero-row bootstrap is a window-domain transition, not a fake
6179
- // row/table change (SPEC §4.8 / §7.5).
6180
- batch.window(registered.baseKey, sub.table, registered.unit);
6181
- }
6182
- });
6183
- return true;
6184
- }
6185
-
6186
- if (start.status === 'reset') {
6187
- // §4.6: discard cursor + resume token, keep local rows, re-bootstrap
6188
- // with cursor = -1 on the next pull. Staleness, not a purge.
6189
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6190
- this.#applyBatch((batch) => {
6191
- saveSubscription(
6192
- this.#db,
6193
- definedObject({
6194
- id: sub.id,
6195
- table: sub.table,
6196
- scopes: sub.scopes,
6197
- params: sub.params,
6198
- cursor: -1,
6199
- effectiveScopes: sub.effectiveScopes,
6200
- status: 'active',
6201
- reasonCode: start.reasonCode,
6202
- }),
6203
- );
6204
- if (registered !== undefined) {
6205
- batch.window(registered.baseKey, sub.table, registered.unit);
6206
- }
6207
- });
6208
- summary.resets.push(sub.id);
6209
- return false;
6210
- }
6211
-
6212
- // revoked (§3.3): purge rows matching the LAST-echoed effective scopes
6213
- // (never the requested map), drop doomed outbox commits, stop pulling.
6214
- const table = this.#table(sub.table);
6215
- const lastEffective = sub.effectiveScopes;
6216
- const registered = getWindowUnitBySubId(this.#db, sub.id);
6217
- 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);
6218
6172
  this.#applyBatch((batch) => {
6219
- if (
6220
- lastEffective !== undefined &&
6221
- Object.keys(lastEffective).length > 0
6222
- ) {
6223
- try {
6224
- const scope = [
6225
- JSON.stringify([table.name]),
6226
- ...this.#dropRetainedRows(
6227
- batch,
6228
- (name, values) =>
6229
- name === table.name &&
6230
- matchesLocalScopes(table, lastEffective, values),
6231
- ),
6232
- ];
6233
- deleteScopedRows(this.#db, table, lastEffective);
6234
- batch.scopeMap(table, lastEffective);
6235
- const pendingById = new Map(
6236
- listOutbox(this.#db).map((commit) => [
6237
- commit.clientCommitId,
6238
- commit,
6239
- ]),
6240
- );
6241
- const droppedIds = dropOutboxCommitsInScope(
6242
- this.#db,
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,
6243
6208
  table,
6244
- lastEffective,
6209
+ last,
6210
+ unitOwners(units, table, unit.id),
6245
6211
  );
6246
- if (droppedIds.length > 0) {
6247
- for (const clientCommitId of droppedIds) {
6248
- const commit = pendingById.get(clientCommitId);
6249
- if (commit === undefined) continue;
6250
- const results: CommitOperationOutcome[] = commit.operations.map(
6251
- (operation, opIndex) => {
6252
- const rejection: RejectionRecord = {
6253
- clientCommitId,
6254
- opIndex,
6255
- code: 'sync.scope_revoked',
6256
- message:
6257
- 'the commit was dropped because its effective scope was revoked',
6258
- retryable: false,
6259
- operation,
6260
- };
6261
- this.#rejections.push(rejection);
6262
- return { status: 'error', rejection };
6263
- },
6264
- );
6265
- recordCommitOutcome(this.#db, {
6266
- clientCommitId,
6267
- status: 'rejected',
6268
- recordedAtMs: this.#now(),
6269
- results,
6270
- operations: commit.operations,
6271
- });
6272
- }
6273
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
6274
- batch.status();
6275
- batch.rejections();
6276
- batch.outcomes();
6277
- }
6278
- this.#replayOutbox(scope);
6279
- this.#deleteUnreferencedBlobs();
6280
- } catch (error) {
6281
- if (
6282
- error instanceof ClientSyncError &&
6283
- error.code === 'sync.scope_revoked'
6284
- ) {
6285
- failed = true;
6286
- } else {
6287
- throw error;
6288
- }
6289
- }
6290
6212
  }
6291
- saveSubscription(
6292
- this.#db,
6293
- definedObject({
6294
- id: sub.id,
6295
- table: sub.table,
6296
- scopes: sub.scopes,
6297
- params: sub.params,
6298
- cursor: nextCursor,
6299
- effectiveScopes: lastEffective,
6213
+ if (revoked || failed) {
6214
+ saveUnit(this.#db, {
6215
+ ...unit,
6300
6216
  status: failed ? 'failed' : 'revoked',
6301
- reasonCode: start.reasonCode,
6302
- }),
6303
- );
6304
- if (registered !== undefined) {
6305
- 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);
6306
6276
  }
6307
6277
  });
6308
- summary.revoked.push(sub.id);
6309
- if (failed) summary.failed.push(sub.id);
6310
- 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
+ }
6311
6357
  }
6312
6358
 
6313
6359
  // -- optimistic state ----------------------------------------------------------
@@ -6343,12 +6389,14 @@ export class SyncClient {
6343
6389
  return { opIndex, existed: true, syncVersion, values };
6344
6390
  }
6345
6391
 
6392
+ /** `onlyKeys` holds overlay row keys (`JSON [table,rowId]`). */
6346
6393
  #captureBeforeImages(
6347
6394
  operations: readonly OutboxOperation[],
6348
6395
  onlyKeys?: ReadonlySet<string>,
6349
6396
  ): OutboxBeforeImage[] {
6350
6397
  return operations.flatMap((operation, opIndex) =>
6351
- onlyKeys && !onlyKeys.has(`${operation.table}\u0000${operation.rowId}`)
6398
+ onlyKeys &&
6399
+ !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
6352
6400
  ? []
6353
6401
  : [this.#captureBeforeImage(operation, opIndex)],
6354
6402
  );
@@ -6408,14 +6456,14 @@ export class SyncClient {
6408
6456
  imageByIndex.has(index),
6409
6457
  );
6410
6458
  const affectedKeys = new Set(
6411
- commit.operations.map(
6412
- (operation) => `${operation.table}\u0000${operation.rowId}`,
6459
+ commit.operations.map((operation) =>
6460
+ JSON.stringify([operation.table, operation.rowId]),
6413
6461
  ),
6414
6462
  );
6415
6463
  if (complete) {
6416
6464
  const restored = new Set<string>();
6417
6465
  commit.operations.forEach((operation, index) => {
6418
- const key = `${operation.table}\u0000${operation.rowId}`;
6466
+ const key = JSON.stringify([operation.table, operation.rowId]);
6419
6467
  if (restored.has(key)) return;
6420
6468
  const image = imageByIndex.get(index);
6421
6469
  if (image) this.#restoreBeforeImage(operation, image, batch);
@@ -6429,15 +6477,15 @@ export class SyncClient {
6429
6477
  deleteOutboxCommit(this.#db, commit.clientCommitId);
6430
6478
 
6431
6479
  if (!complete) return;
6432
- for (const later of listOutbox(this.#db)) {
6480
+ for (const later of listOutbox(this.#db, [...affectedKeys])) {
6433
6481
  if (later.seq <= commit.seq) continue;
6434
6482
  const affectedOperations = later.operations.filter((operation) =>
6435
- affectedKeys.has(`${operation.table}\u0000${operation.rowId}`),
6483
+ affectedKeys.has(JSON.stringify([operation.table, operation.rowId])),
6436
6484
  );
6437
6485
  if (affectedOperations.length === 0) continue;
6438
6486
  replaceOutboxBeforeImages(
6439
6487
  this.#db,
6440
- later.clientCommitId,
6488
+ later,
6441
6489
  this.#captureBeforeImages(later.operations, affectedKeys),
6442
6490
  );
6443
6491
  // §7.4.4: a later commit the recovery already classified refused never
@@ -6614,27 +6662,30 @@ export class SyncClient {
6614
6662
  type: localColumnType(column),
6615
6663
  }));
6616
6664
  const sparse: Array<RowValue | undefined> = [];
6617
- for (const column of table.columns) {
6618
- const raw = values[column.name];
6665
+ for (const { name, type } of declared) {
6666
+ const raw = values[name];
6619
6667
  if (raw === undefined) {
6620
6668
  sparse.push(undefined);
6621
6669
  continue;
6622
6670
  }
6623
- // §7.1: the schema-agnostic outbox form serializes through JSON, which
6624
- // turns NaN and ±Infinity into null. The authoring boundary refuses them
6625
- // instead of recording a different value; the wire `f64` encoding itself
6626
- // stays IEEE-754 binary64 (§2.4).
6671
+ // §2.4/§7.1: authoring refuses the push admission values the server
6672
+ // rejects. JSON would also turn NaN and ±Infinity into null, so the
6673
+ // outbox never records a different value.
6627
6674
  if (
6628
- localColumnType(column) === 'float' &&
6629
- typeof raw === 'number' &&
6630
- !Number.isFinite(raw)
6675
+ (type === 'float' &&
6676
+ typeof raw === 'number' &&
6677
+ !Number.isFinite(raw)) ||
6678
+ (type === 'string' && typeof raw === 'string' && raw.includes('\0'))
6631
6679
  )
6632
- return `column ${column.name} (float) requires a finite number value`;
6680
+ return `column ${name} holds a value push admission rejects`;
6633
6681
  try {
6682
+ if (typeof raw === 'string' && type === 'json')
6683
+ parseJsonDocument(raw, 'json value');
6684
+ if (typeof raw === 'string' && type === 'blob_ref') parseBlobRef(raw);
6634
6685
  sparse.push(jsonToRowValue(raw));
6635
6686
  } catch (error) {
6636
- if (error instanceof ClientSyncError)
6637
- return `column ${column.name}: ${error.message}`;
6687
+ if (error instanceof ClientSyncError || error instanceof DecodeError)
6688
+ return `column ${name}: ${error.message}`;
6638
6689
  throw error;
6639
6690
  }
6640
6691
  }
@@ -6703,11 +6754,24 @@ export class SyncClient {
6703
6754
  scope,
6704
6755
  this.#schema,
6705
6756
  );
6757
+ const outbox = new Set(listOutbox(this.#db, scope));
6706
6758
  const pending = [
6707
6759
  ...failedOverlayCommits(this.#db, false, scope, this.#schema),
6708
- ...listOutbox(this.#db, scope),
6760
+ ...outbox,
6709
6761
  ].sort((a, b) => a.createdAtMs - b.createdAtMs || a.seq - b.seq);
6710
- for (const commit of [...acknowledged, ...pending])
6762
+ // §7.2: a caller that restored the bases itself has just written the
6763
+ // server base of every exact-key row in scope. Each pending commit's
6764
+ // before-image of such a row is re-taken right before the commit
6765
+ // replays, so a later rollback restores that base plus earlier intent.
6766
+ const rebased =
6767
+ restoreBases || scope === undefined ? undefined : new Set(scope);
6768
+ for (const commit of [...acknowledged, ...pending]) {
6769
+ if (rebased !== undefined && outbox.has(commit))
6770
+ replaceOutboxBeforeImages(
6771
+ this.#db,
6772
+ commit,
6773
+ this.#captureBeforeImages(commit.operations, rebased),
6774
+ );
6711
6775
  this.#applyOperationsLocally(
6712
6776
  commit.operations.filter(
6713
6777
  (op) =>
@@ -6718,6 +6782,7 @@ export class SyncClient {
6718
6782
  batch,
6719
6783
  true,
6720
6784
  );
6785
+ }
6721
6786
  };
6722
6787
  const priorRejections = [...this.#rejections];
6723
6788
  try {