@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
@@ -24,6 +24,7 @@ import { encryptionConfigFromKeyring } from './encryption';
24
24
  import {
25
25
  classifySqliteFailure,
26
26
  ClientSyncError,
27
+ invalidRequest,
27
28
  STORAGE_BUSY_CODE,
28
29
  } from './errors';
29
30
  import {
@@ -64,6 +65,14 @@ export interface SyncWorkerOverrides {
64
65
  ) => Promise<ClientDatabase> | ClientDatabase;
65
66
  /** Retry deadline indirection for deterministic worker-host tests. */
66
67
  readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
68
+ /**
69
+ * Timer indirection for deterministic worker-host tests: background-intent
70
+ * deadlines and the client's §8.5 heartbeat watchdog.
71
+ */
72
+ readonly scheduleBackground?: (
73
+ callback: () => void,
74
+ delayMs: number,
75
+ ) => () => void;
67
76
  readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
68
77
  readonly createSegments?: (
69
78
  config: WorkerInitConfig,
@@ -201,6 +210,7 @@ export function startSyncWorkerCore(
201
210
  let offline = false;
202
211
  let headers: Readonly<Record<string, string>> = {};
203
212
  let closed = false;
213
+ let pushingDiagnostics = false;
204
214
 
205
215
  // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
206
216
  let syncChain: Promise<unknown> = Promise.resolve();
@@ -216,8 +226,32 @@ export function startSyncWorkerCore(
216
226
  // -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
217
227
  let autoSync = true;
218
228
  let autoSyncScheduled = false;
219
- let backgroundTimer: ReturnType<typeof setTimeout> | undefined;
229
+ let cancelBackground: (() => void) | undefined;
220
230
  let backgroundDue = Number.POSITIVE_INFINITY;
231
+ // §7.7 backoff for drives that end without a client retry intent.
232
+ let retryDelayMs = 250;
233
+ const scheduleBackground =
234
+ overrides.scheduleBackground ??
235
+ ((callback: () => void, delayMs: number): (() => void) => {
236
+ const timer = setTimeout(callback, delayMs);
237
+ return () => clearTimeout(timer);
238
+ });
239
+
240
+ const workerDiagnostics = (snapshot: ClientDiagnosticsSnapshot) =>
241
+ withClientDiagnosticsHost(snapshot, {
242
+ kind: 'worker',
243
+ role: 'leader',
244
+ connectivity: offline ? 'offline' : snapshot.host.connectivity,
245
+ realtime: snapshot.host.realtime,
246
+ });
247
+ const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
248
+ if (!closed) {
249
+ post({
250
+ t: 'event',
251
+ event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
252
+ });
253
+ }
254
+ };
221
255
 
222
256
  function runAutoSync(): void {
223
257
  if (
@@ -238,19 +272,44 @@ export function startSyncWorkerCore(
238
272
  return running.syncUntilIdle();
239
273
  })
240
274
  .then((summary) => {
275
+ retryDelayMs = 250;
241
276
  if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
242
277
  if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
243
278
  })
244
279
  .catch((error: unknown) => {
245
- if (!closed) {
246
- post({
247
- t: 'event',
248
- event: { kind: 'synced', error: toErrorShape(error) },
249
- });
280
+ if (closed) return;
281
+ post({
282
+ t: 'event',
283
+ event: { kind: 'synced', error: toErrorShape(error) },
284
+ });
285
+ // §7.8: a retryable drive rejection owes another drive. A retryable
286
+ // round failure already handed this loop its background intent; the
287
+ // drive deadline did not. An unreachable endpoint waits for the
288
+ // host's connectivity resume (§1.8).
289
+ const causeKind =
290
+ error instanceof ClientSyncError
291
+ ? error.details?.['causeKind']
292
+ : undefined;
293
+ if (
294
+ error instanceof ClientSyncError &&
295
+ error.retryable &&
296
+ causeKind !== 'network' &&
297
+ causeKind !== 'connect' &&
298
+ cancelBackground === undefined &&
299
+ !autoSyncScheduled
300
+ ) {
301
+ consumeSyncIntent({ kind: 'background', delayMs: retryDelayMs });
302
+ retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
250
303
  }
251
304
  });
252
305
  }
253
306
 
307
+ function stopBackground(): void {
308
+ cancelBackground?.();
309
+ cancelBackground = undefined;
310
+ backgroundDue = Number.POSITIVE_INFINITY;
311
+ }
312
+
254
313
  function consumeSyncIntent(intent: SyncIntent): void {
255
314
  if (
256
315
  !autoSync ||
@@ -265,12 +324,12 @@ export function startSyncWorkerCore(
265
324
  if (intent.kind === 'background') {
266
325
  if (autoSyncScheduled) return;
267
326
  const due = Date.now() + Math.max(0, intent.delayMs);
268
- if (backgroundTimer !== undefined && due >= backgroundDue) return;
269
- if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
327
+ if (cancelBackground !== undefined && due >= backgroundDue) return;
328
+ cancelBackground?.();
270
329
  backgroundDue = due;
271
- backgroundTimer = setTimeout(
330
+ cancelBackground = scheduleBackground(
272
331
  () => {
273
- backgroundTimer = undefined;
332
+ cancelBackground = undefined;
274
333
  backgroundDue = Number.POSITIVE_INFINITY;
275
334
  if (!autoSyncScheduled) {
276
335
  autoSyncScheduled = true;
@@ -281,11 +340,7 @@ export function startSyncWorkerCore(
281
340
  );
282
341
  return;
283
342
  }
284
- if (backgroundTimer !== undefined) {
285
- clearTimeout(backgroundTimer);
286
- backgroundTimer = undefined;
287
- backgroundDue = Number.POSITIVE_INFINITY;
288
- }
343
+ stopBackground();
289
344
  if (!autoSync || autoSyncScheduled || closed || client === undefined) {
290
345
  return;
291
346
  }
@@ -393,15 +448,12 @@ export function startSyncWorkerCore(
393
448
  ? { segments: bindings.segments }
394
449
  : {}),
395
450
  ...(blobs !== undefined ? { blobs } : {}),
396
- realtime: (handlers) => {
451
+ realtime: (handlers, clientId) => {
397
452
  // §12.2: a local authority has no realtime channel.
398
453
  if (realtimeConnector === undefined || local?.active()) {
399
- throw new ClientSyncError(
400
- 'sync.invalid_request',
401
- 'no realtime connector configured',
402
- );
454
+ throw invalidRequest('no realtime connector configured');
403
455
  }
404
- return realtimeConnector(handlers);
456
+ return realtimeConnector(handlers, clientId);
405
457
  },
406
458
  ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
407
459
  ...(config.limits !== undefined ? { limits: config.limits } : {}),
@@ -411,6 +463,10 @@ export function startSyncWorkerCore(
411
463
  ...(config.realtimePolicy !== undefined
412
464
  ? { realtimePolicy: config.realtimePolicy }
413
465
  : {}),
466
+ ...(config.realtimeHeartbeatMs !== undefined
467
+ ? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
468
+ : {}),
469
+ schedule: scheduleBackground,
414
470
  ...(config.encryption !== undefined
415
471
  ? { encryption: encryptionConfigFromKeyring(config.encryption) }
416
472
  : {}),
@@ -439,9 +495,9 @@ export function startSyncWorkerCore(
439
495
  // §7.4.5: surface the schema-bump reset + completion to the UI thread.
440
496
  post({ t: 'event', event: { kind: 'upgrading', upgrading } });
441
497
  },
442
- onPresence: (scopeKey) => {
443
- // §8.6: surface a presence change to the UI thread.
444
- post({ t: 'event', event: { kind: 'presence', scopeKey } });
498
+ onPresence: (scopeKey, error) => {
499
+ // §8.6: surface a presence change or rejection to the UI thread.
500
+ post({ t: 'event', event: { kind: 'presence', scopeKey, error } });
445
501
  },
446
502
  });
447
503
  started.onProgress((progress) => {
@@ -450,33 +506,12 @@ export function startSyncWorkerCore(
450
506
  started.onChange((batch) => {
451
507
  if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
452
508
  });
453
- const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
454
- if (closed) return;
455
- post({
456
- t: 'event',
457
- event: {
458
- kind: 'diagnostics',
459
- snapshot: withClientDiagnosticsHost(snapshot, {
460
- kind: 'worker',
461
- role: 'leader',
462
- connectivity: offline ? 'offline' : snapshot.host.connectivity,
463
- realtime: snapshot.host.realtime,
464
- }),
465
- },
466
- });
467
- };
468
- started.onDiagnostics(postDiagnostics);
469
509
  await started.start();
470
510
  realtimeConnector =
471
511
  overrides.createRealtime !== undefined
472
512
  ? overrides.createRealtime(config, started.clientId, http.headers)
473
513
  : config.endpoints.realtimeUrl !== undefined
474
- ? webSocketRealtimeConnector(
475
- config.endpoints.realtimeUrl.replace(
476
- '{clientId}',
477
- encodeURIComponent(started.clientId),
478
- ),
479
- )
514
+ ? webSocketRealtimeConnector(config.endpoints.realtimeUrl)
480
515
  : undefined;
481
516
  client = started;
482
517
  // `start()` may discover persisted subscriptions/outbox work. Its callback
@@ -510,8 +545,8 @@ export function startSyncWorkerCore(
510
545
  'commitOutcomes',
511
546
  'resolveCommitOutcome',
512
547
  'pendingCommits',
513
- 'subscriptions',
514
- 'subscription',
548
+ 'units',
549
+ 'unit',
515
550
  'connectRealtime',
516
551
  'disconnectRealtime',
517
552
  'setPresence',
@@ -530,9 +565,7 @@ export function startSyncWorkerCore(
530
565
  ]),
531
566
  ) as Pick<WorkerApi, (typeof coreMethods)[number]>),
532
567
  beginSecurityPreflight: async () => {
533
- if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
534
- backgroundTimer = undefined;
535
- backgroundDue = Number.POSITIVE_INFINITY;
568
+ stopBackground();
536
569
  autoSyncScheduled = false;
537
570
  await requireClient().beginSecurityPreflight();
538
571
  },
@@ -574,14 +607,15 @@ export function startSyncWorkerCore(
574
607
  },
575
608
  resetClientId: () => requireClient().resetClientId(),
576
609
  localRevision: () => requireClient().localRevision,
577
- diagnosticsSnapshot: (request) => {
578
- const snapshot = requireClient().diagnosticsSnapshot(request);
579
- return withClientDiagnosticsHost(snapshot, {
580
- kind: 'worker',
581
- role: 'leader',
582
- connectivity: offline ? 'offline' : snapshot.host.connectivity,
583
- realtime: snapshot.host.realtime,
584
- });
610
+ diagnosticsSnapshot: () => {
611
+ const running = requireClient();
612
+ // The first pull makes the worker a push source: no tab has asked for
613
+ // diagnostics before it, so no snapshot is built per revision until then.
614
+ if (!pushingDiagnostics) {
615
+ pushingDiagnostics = true;
616
+ running.onDiagnostics(postDiagnostics);
617
+ }
618
+ return workerDiagnostics(running.diagnosticsSnapshot());
585
619
  },
586
620
  setHeaders: (next) => {
587
621
  headers = next;
@@ -590,29 +624,15 @@ export function startSyncWorkerCore(
590
624
  offline = value;
591
625
  requireClient().setTransportEnabled(!value);
592
626
  if (offline) {
593
- if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
594
- backgroundTimer = undefined;
595
- backgroundDue = Number.POSITIVE_INFINITY;
596
- } else if (client !== undefined) {
597
- const snapshot = client.diagnosticsSnapshot();
598
- post({
599
- t: 'event',
600
- event: {
601
- kind: 'diagnostics',
602
- snapshot: withClientDiagnosticsHost(snapshot, {
603
- kind: 'worker',
604
- role: 'leader',
605
- connectivity: snapshot.host.connectivity,
606
- realtime: snapshot.host.realtime,
607
- }),
608
- },
609
- });
627
+ stopBackground();
628
+ } else if (client !== undefined && pushingDiagnostics) {
629
+ postDiagnostics(client.diagnosticsSnapshot());
610
630
  }
611
631
  },
612
632
  ...local?.methods,
613
633
  close: async () => {
614
634
  closed = true;
615
- if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
635
+ cancelBackground?.();
616
636
  await client?.close();
617
637
  local?.close();
618
638
  database?.close();
@@ -27,7 +27,11 @@ import type { PromiseMethods } from './client';
27
27
  * With `multiTab: false`, the loser is an `isLeader === false` handle whose
28
28
  * calls reject with `client.not_leader` (the single-tab contract).
29
29
  */
30
- import type { WakeReason } from '@syncular/core';
30
+ import {
31
+ type PresenceErrorCode,
32
+ serializeBlobRef,
33
+ type WakeReason,
34
+ } from '@syncular/core';
31
35
  import type { BlobRef, CachedBlob } from './blob';
32
36
  import type {
33
37
  ConflictRecord,
@@ -40,7 +44,6 @@ import type {
40
44
  SecurityLifecycle,
41
45
  SnapshotRead,
42
46
  SnapshotReadRequest,
43
- SubscribeInput,
44
47
  SyncClientConfig,
45
48
  SyncClientLimits,
46
49
  SyncSummary,
@@ -53,13 +56,12 @@ import type { DevtoolsRegistrar } from './devtools';
53
56
  import {
54
57
  ClientDiagnosticsEmitter,
55
58
  type ClientDiagnosticsListener,
56
- type ClientDiagnosticsRequest,
57
59
  type ClientDiagnosticsSnapshot,
58
60
  type RealtimePolicy,
59
61
  withClientDiagnosticsHost,
60
62
  } from './diagnostics';
61
63
  import type { EncryptionKeyringConfig } from './encryption';
62
- import { ClientSyncError } from './errors';
64
+ import { ClientSyncError, invalidRequest } from './errors';
63
65
  import {
64
66
  ChangeEmitter,
65
67
  type ClientChangeListener,
@@ -106,7 +108,8 @@ import {
106
108
  type PreviousVersionSnapshot,
107
109
  } from './previous-version';
108
110
  import type { ClientSchema } from './schema';
109
- import type { SubscriptionRecord } from './state';
111
+ import type { UnitScopes } from '@syncular/core';
112
+ import type { UnitRecord } from './state';
110
113
  import type { WindowBase } from './window';
111
114
  import {
112
115
  type LocalAuthorityState,
@@ -161,8 +164,7 @@ export function isolatedReplicaNames(options: {
161
164
  readonly replicaId: string;
162
165
  }): IsolatedReplicaNames {
163
166
  if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
164
- throw new ClientSyncError(
165
- 'sync.invalid_request',
167
+ throw invalidRequest(
166
168
  'an isolated replica id must contain only letters, numbers, dot, underscore, or dash',
167
169
  );
168
170
  }
@@ -213,6 +215,8 @@ export interface SyncClientHandleConfig {
213
215
  * `WorkerInitConfig`. Absent ⇒ `optional`.
214
216
  */
215
217
  readonly realtimePolicy?: RealtimePolicy;
218
+ /** SPEC §8.5 heartbeat interval, forwarded into `WorkerInitConfig`. */
219
+ readonly realtimeHeartbeatMs?: number;
216
220
  /**
217
221
  * RFC 0005 previous-version context, forwarded into the worker's
218
222
  * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -263,8 +267,9 @@ export interface SyncClientHandleConfig {
263
267
  }) => void;
264
268
  /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
265
269
  readonly onUpgrading?: (upgrading: boolean) => void;
266
- /** §8.6: presence on a scope key changed. */
267
- readonly onPresence?: (scopeKey: string) => void;
270
+ /** §8.6: presence on a scope key changed, or the server refused this
271
+ * client's publish on it (`error`, §8.6.2). */
272
+ readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
268
273
  /** Atomic privacy-safe diagnostics changed. */
269
274
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
270
275
  }
@@ -334,7 +339,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
334
339
  readonly #invalidation: InvalidationEmitter;
335
340
  readonly #progress = new ProgressEmitter();
336
341
  readonly #changes: ChangeEmitter;
337
- readonly #presence: Set<(scopeKey: string) => void>;
342
+ readonly #presence: Set<
343
+ (scopeKey: string, error?: PresenceErrorCode) => void
344
+ >;
338
345
  readonly #diagnostics: ClientDiagnosticsEmitter;
339
346
  readonly #roleListeners: Set<(role: HandleRole) => void>;
340
347
  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
@@ -352,7 +359,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
352
359
  tabs?: TabCoordinator;
353
360
  invalidation: InvalidationEmitter;
354
361
  changes: ChangeEmitter;
355
- presence: Set<(scopeKey: string) => void>;
362
+ presence: Set<(scopeKey: string, error?: PresenceErrorCode) => void>;
356
363
  diagnostics: ClientDiagnosticsEmitter;
357
364
  roleListeners?: Set<(role: HandleRole) => void>;
358
365
  leadershipListeners?: Set<(state: LeadershipState) => void>;
@@ -390,7 +397,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
390
397
  clientId: () => this.#clientId,
391
398
  role: () => this.#role,
392
399
  outbox: async () => (await this.statusSnapshot()).outbox,
393
- subscriptions: () => this.subscriptions(),
400
+ units: () => this.units(),
394
401
  conflicts: async () => (await this.conflicts()).length,
395
402
  rejections: async () => (await this.rejections()).length,
396
403
  syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
@@ -407,6 +414,13 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
407
414
  this.#leadership = state;
408
415
  if (state.state === 'leader') this.#clientId = state.clientId;
409
416
  if (state.state === 'follower') this.#clientId = state.leaderClientId;
417
+ // A new leader starts a fresh core that no tab has pulled from yet.
418
+ if (
419
+ this.#diagnostics.observed &&
420
+ (state.state === 'leader' || state.state === 'follower')
421
+ ) {
422
+ this.#pullDiagnostics();
423
+ }
410
424
  for (const listener of this.#leadershipListeners) {
411
425
  try {
412
426
  listener(state);
@@ -433,7 +447,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
433
447
  } else if (event.kind === 'presence') {
434
448
  for (const listener of this.#presence) {
435
449
  try {
436
- listener(event.scopeKey);
450
+ listener(event.scopeKey, event.error);
437
451
  } catch {
438
452
  /* a UI listener must never break event dispatch */
439
453
  }
@@ -475,14 +489,27 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
475
489
  }
476
490
 
477
491
  onDiagnostics(listener: ClientDiagnosticsListener): () => void {
478
- return this.#diagnostics.on(listener);
492
+ const off = this.#diagnostics.on(listener);
493
+ this.#pullDiagnostics();
494
+ return off;
495
+ }
496
+
497
+ /**
498
+ * The worker pushes diagnostics only after a consumer pulled once. A handle
499
+ * that cannot reach a core has nothing to observe, so a failed pull is
500
+ * dropped.
501
+ */
502
+ #pullDiagnostics(): void {
503
+ void this.diagnosticsSnapshot().catch(() => undefined);
479
504
  }
480
505
 
481
506
  /**
482
507
  * §8.6: subscribe to presence changes — the identical surface as
483
508
  * `SyncClient.onPresence`. Returns an unsubscribe function.
484
509
  */
485
- onPresence(listener: (scopeKey: string) => void): () => void {
510
+ onPresence(
511
+ listener: (scopeKey: string, error?: PresenceErrorCode) => void,
512
+ ): () => void {
486
513
  this.#presence.add(listener);
487
514
  return () => {
488
515
  this.#presence.delete(listener);
@@ -571,12 +598,12 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
571
598
  >;
572
599
  }
573
600
 
574
- subscribe(input: SubscribeInput): Promise<void> {
575
- return this.#call('subscribe', [input]);
601
+ subscribe(scopes: UnitScopes): Promise<string> {
602
+ return this.#call('subscribe', [scopes]);
576
603
  }
577
604
 
578
- subscribeMany(inputs: readonly SubscribeInput[]): Promise<void> {
579
- return this.#call('subscribeMany', [inputs]);
605
+ subscribeMany(units: readonly UnitScopes[]): Promise<string[]> {
606
+ return this.#call('subscribeMany', [units]);
580
607
  }
581
608
 
582
609
  securityLifecycle(): Promise<SecurityLifecycle> {
@@ -714,10 +741,8 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
714
741
  return this.#call('statusSnapshot', []);
715
742
  }
716
743
 
717
- async diagnosticsSnapshot(
718
- request: ClientDiagnosticsRequest = {},
719
- ): Promise<ClientDiagnosticsSnapshot> {
720
- const snapshot = await this.#call('diagnosticsSnapshot', [request]);
744
+ async diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot> {
745
+ const snapshot = await this.#call('diagnosticsSnapshot', []);
721
746
  return withClientDiagnosticsHost(snapshot, {
722
747
  ...snapshot.host,
723
748
  kind: 'worker',
@@ -754,12 +779,12 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
754
779
  return this.#call('pendingCommits', []);
755
780
  }
756
781
 
757
- subscriptions(): Promise<SubscriptionRecord[]> {
758
- return this.#call('subscriptions', []);
782
+ units(): Promise<UnitRecord[]> {
783
+ return this.#call('units', []);
759
784
  }
760
785
 
761
- subscription(id: string): Promise<SubscriptionRecord | undefined> {
762
- return this.#call('subscription', [id]);
786
+ unit(id: string): Promise<UnitRecord | undefined> {
787
+ return this.#call('unit', [id]);
763
788
  }
764
789
 
765
790
  connectRealtime(): Promise<void> {
@@ -790,6 +815,11 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
790
815
  return this.#call('uploadBlob', [bytes, options]);
791
816
  }
792
817
 
818
+ /** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
819
+ blobRefString(ref: BlobRef): string {
820
+ return serializeBlobRef(ref);
821
+ }
822
+
793
823
  fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
794
824
  return this.#call('fetchBlob', [blobIdOrRef]);
795
825
  }
@@ -862,7 +892,14 @@ async function startWorkerCore(options: {
862
892
  dispatchEvent: (event: SyncWorkerEvent) => void;
863
893
  }): Promise<LeaderCore> {
864
894
  const { config, initConfig, lease } = options;
865
- const worker = config.worker();
895
+ let worker: Worker;
896
+ try {
897
+ worker = config.worker();
898
+ } catch (error) {
899
+ // No worker exists to terminate; the lease is the only thing held.
900
+ await lease.release();
901
+ throw error;
902
+ }
866
903
  const pending = new Map<number, Pending>();
867
904
  const nextId = { value: 1 };
868
905
  let terminated = false;
@@ -961,6 +998,9 @@ async function startWorkerCore(options: {
961
998
  } as MainToWorkerMessage);
962
999
  },
963
1000
  );
1001
+ // A config callback is a consumer from the first round.
1002
+ if (config.onDiagnostics !== undefined)
1003
+ await invoke('diagnosticsSnapshot', []);
964
1004
  return {
965
1005
  clientId: initResult.clientId,
966
1006
  invoke,
@@ -1012,6 +1052,9 @@ function buildInitConfig(
1012
1052
  ...(config.realtimePolicy !== undefined
1013
1053
  ? { realtimePolicy: config.realtimePolicy }
1014
1054
  : {}),
1055
+ ...(config.realtimeHeartbeatMs !== undefined
1056
+ ? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
1057
+ : {}),
1015
1058
  ...(config.previousVersionContext !== undefined
1016
1059
  ? { previousVersionContext: config.previousVersionContext }
1017
1060
  : {}),
@@ -1031,7 +1074,7 @@ function fireConfigCallbacks(
1031
1074
  } else if (event.kind === 'upgrading') {
1032
1075
  config.onUpgrading?.(event.upgrading);
1033
1076
  } else if (event.kind === 'presence') {
1034
- config.onPresence?.(event.scopeKey);
1077
+ config.onPresence?.(event.scopeKey, event.error);
1035
1078
  } else if (event.kind === 'synced') {
1036
1079
  config.onSynced?.({
1037
1080
  ...(event.summary !== undefined ? { summary: event.summary } : {}),
@@ -1057,7 +1100,9 @@ export async function createSyncClientHandle(
1057
1100
  const lockName = resolvedConfig.lockName ?? 'syncular-leader';
1058
1101
  const invalidation = new InvalidationEmitter();
1059
1102
  const changes = new ChangeEmitter();
1060
- const presence = new Set<(scopeKey: string) => void>();
1103
+ const presence = new Set<
1104
+ (scopeKey: string, error?: PresenceErrorCode) => void
1105
+ >();
1061
1106
  const diagnostics = new ClientDiagnosticsEmitter();
1062
1107
  const roleListeners = new Set<(role: HandleRole) => void>();
1063
1108
  if (resolvedConfig.onRoleChange !== undefined)
@@ -1213,8 +1258,7 @@ function resolveReplicaConfig(
1213
1258
  ): SyncClientHandleConfig {
1214
1259
  if (config.replica?.mode !== 'isolated') return config;
1215
1260
  if (config.database.mode !== 'persistent') {
1216
- throw new ClientSyncError(
1217
- 'sync.invalid_request',
1261
+ throw invalidRequest(
1218
1262
  'isolated browser replicas require a named persistent database',
1219
1263
  );
1220
1264
  }
@@ -1,5 +1,5 @@
1
1
  import type { SiblingDatabase } from './database';
2
- import { ClientSyncError } from './errors';
2
+ import { ClientSyncError, invalidRequest } from './errors';
3
3
  import type { SyncTransport } from './transport';
4
4
  import type {
5
5
  WorkerLocalAuthority,
@@ -91,10 +91,7 @@ export const createWorkerLocalAuthority: WorkerLocalAuthorityFactory = (
91
91
  segments: (request) => {
92
92
  if (active()) return local.downloadSegment(request);
93
93
  if (segments === undefined) {
94
- throw new ClientSyncError(
95
- 'sync.invalid_request',
96
- 'no segment endpoint configured',
97
- );
94
+ throw invalidRequest('no segment endpoint configured');
98
95
  }
99
96
  return segments(request);
100
97
  },
@@ -17,7 +17,7 @@ import type { SyncProgress } from './progress';
17
17
  * so the UI thread never has to react to keep data flowing. Events are
18
18
  * still forwarded to the handle for visibility.
19
19
  */
20
- import type { WakeReason } from '@syncular/core';
20
+ import type { PresenceErrorCode, WakeReason } from '@syncular/core';
21
21
  import type { BlobRef, CachedBlob } from './blob';
22
22
  import type {
23
23
  ConflictRecord,
@@ -28,7 +28,6 @@ import type {
28
28
  QueryReadSpec,
29
29
  QuerySnapshot,
30
30
  SecurityLifecycle,
31
- SubscribeInput,
32
31
  SyncClientConfig,
33
32
  SyncClientLimits,
34
33
  SyncSummary,
@@ -53,7 +52,8 @@ import type {
53
52
  PreviousVersionSnapshot,
54
53
  } from './previous-version';
55
54
  import type { ClientSchema } from './schema';
56
- import type { SubscriptionRecord } from './state';
55
+ import type { UnitScopes } from '@syncular/core';
56
+ import type { UnitRecord } from './state';
57
57
  import type { WindowBase } from './window';
58
58
 
59
59
  // ---------------------------------------------------------------------------
@@ -147,6 +147,8 @@ export interface WorkerInitConfig {
147
147
  * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
148
148
  */
149
149
  readonly realtimePolicy?: RealtimePolicy;
150
+ /** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
151
+ readonly realtimeHeartbeatMs?: number;
150
152
  /**
151
153
  * RFC 0005 previous-version context, forwarded verbatim into the worker's
152
154
  * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -181,12 +183,12 @@ export interface WorkerApi extends Omit<
181
183
  securityLifecycle(): SecurityLifecycle;
182
184
  beginSecurityPreflight(): Promise<void>;
183
185
  activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
184
- subscribe(input: SubscribeInput): void;
185
- subscribeMany(inputs: readonly SubscribeInput[]): void;
186
+ subscribe(scopes: UnitScopes): string;
187
+ subscribeMany(units: readonly UnitScopes[]): string[];
186
188
  unsubscribe(id: string): void;
187
- /** §4.8 windowed subscriptions: set the live units for a window base. */
189
+ /** §4.8 windows: set the windowed-in values of a base. */
188
190
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
189
- /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
191
+ /** §4.8 completeness oracle: the windowed-in values of a base. */
190
192
  windowState(base: WindowBase): WindowState;
191
193
  mutate(mutations: readonly MutationInput[]): string;
192
194
  /** Partial-update convenience: read-merge-write one full-row upsert. */
@@ -222,8 +224,8 @@ export interface WorkerApi extends Omit<
222
224
  querySnapshot(spec: QueryReadSpec): QuerySnapshot;
223
225
  localRevision(): LocalRevision;
224
226
  pendingCommits(): OutboxCommit[];
225
- subscriptions(): SubscriptionRecord[];
226
- subscription(id: string): SubscriptionRecord | undefined;
227
+ units(): UnitRecord[];
228
+ unit(id: string): UnitRecord | undefined;
227
229
  connectRealtime(): Promise<void>;
228
230
  disconnectRealtime(): void;
229
231
  /** §8.6 presence: publish/clear a scope-keyed presence document. */
@@ -299,9 +301,11 @@ export type SyncWorkerEvent =
299
301
  readonly upgrading: boolean;
300
302
  }
301
303
  | {
302
- /** §8.6: presence on a scope key changed inside the worker. */
304
+ /** §8.6: presence on a scope key changed, or the server refused this
305
+ * client's publish on it (`error`, §8.6.2). */
303
306
  readonly kind: 'presence';
304
307
  readonly scopeKey: string;
308
+ readonly error?: PresenceErrorCode | undefined;
305
309
  }
306
310
  | {
307
311
  /** Exact revisioned core transaction; Sets and bigint clone directly. */