@syncular/server 0.78.3 → 0.79.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.
package/README.md CHANGED
@@ -384,6 +384,12 @@ lock; D1 and custom adapters without `lockPartition()` fail with
384
384
  `sync.storage.partition_lock_unsupported`. See
385
385
  [host-owned authority transactions](https://syncular.dev/guide-remote-operations/#host-owned-authority-transactions).
386
386
 
387
+ A host that only reads, such as a `resolveScopes` callback that reads its
388
+ grants, calls `prepareReadTransaction(tx, schema.version, checkpoints)`
389
+ instead. It pins the transaction to one snapshot (`REPEATABLE READ READ ONLY`
390
+ on PostgreSQL) without the partition lock, so a pull never waits on a push.
391
+ D1 fails with `sync.storage.snapshot_unsupported` (SPEC §6.8).
392
+
387
393
  `scanRows` is a Syncular scope-index scan, never an unscoped administrative
388
394
  query. Passing an empty or omitted `scopeFilter` throws the exported
389
395
  `StorageQueryError` with `code: 'sync.storage.scan_requires_scope'` on
package/dist/events.d.ts CHANGED
@@ -267,6 +267,19 @@ export interface RealtimeWakeEvent extends RealtimeEventBase {
267
267
  readonly type: 'realtime.wake';
268
268
  readonly reason: WakeReason;
269
269
  }
270
+ /**
271
+ * §8.9: a bridge gave up delivering a commit, or a client's changed
272
+ * registrations, to the partition's other hosts after its retries. Sessions
273
+ * there learn of the commit from the next one, which arrives non-adjacent.
274
+ */
275
+ export interface RealtimeRelayFailedEvent {
276
+ readonly type: 'realtime.relay_failed';
277
+ readonly atMs: number;
278
+ readonly partition: string;
279
+ /** The commit the message carried; absent for changed registrations. */
280
+ readonly commitSeq?: number;
281
+ readonly attempts: number;
282
+ }
270
283
  /** A §4.6 prune pass finished (whether or not the horizon moved). */
271
284
  export interface PruneCompletedEvent {
272
285
  readonly type: 'prune.completed';
@@ -311,7 +324,7 @@ export interface LeaseRevokedEvent {
311
324
  * `lease.issued`, `reaction.queued`, `scopes.resolve_failed`) and shared by
312
325
  * all of them, so a sink can group one request's events.
313
326
  */
314
- export type SyncularServerEvent = (RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent) & {
327
+ export type SyncularServerEvent = (RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | RealtimeRelayFailedEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent) & {
315
328
  readonly requestId?: string;
316
329
  };
317
330
  /**
@@ -1207,6 +1207,11 @@ class PostgresTransaction {
1207
1207
  this.#assertOpen();
1208
1208
  await lockPartitionOn(this.#client, this.#partition);
1209
1209
  }
1210
+ async pinSnapshot() {
1211
+ this.#assertOpen();
1212
+ // PostgreSQL refuses this after the transaction's first statement.
1213
+ await this.#client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
1214
+ }
1210
1215
  async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
1211
1216
  this.#assertOpen();
1212
1217
  await this.#ensurePushSavepoint();
@@ -40,3 +40,9 @@ export declare function serveNotReadyError(refusal: ServeGateRefusal): SyncError
40
40
  * actor authority under the lock and commits or rolls back the transaction.
41
41
  */
42
42
  export declare function prepareAuthorityTransaction(tx: StorageTransaction, runningSchemaVersion: number, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
43
+ /**
44
+ * Pin a host-owned read transaction to one snapshot without the partition
45
+ * lock, then gate it (§6.8). A scope resolver reads its authority graph here,
46
+ * so a pull never waits on a push. The caller rolls the transaction back.
47
+ */
48
+ export declare function prepareReadTransaction(tx: StorageTransaction, runningSchemaVersion: number, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
package/dist/readiness.js CHANGED
@@ -74,14 +74,32 @@ export function serveNotReadyError(refusal) {
74
74
  * Lock and gate a host-owned non-push transaction (§6.8). The caller checks
75
75
  * actor authority under the lock and commits or rolls back the transaction.
76
76
  */
77
- export async function prepareAuthorityTransaction(tx, runningSchemaVersion, checkpoints) {
77
+ export function prepareAuthorityTransaction(tx, runningSchemaVersion, checkpoints) {
78
+ return prepareHostTransaction(tx, 'lock', runningSchemaVersion, checkpoints);
79
+ }
80
+ /**
81
+ * Pin a host-owned read transaction to one snapshot without the partition
82
+ * lock, then gate it (§6.8). A scope resolver reads its authority graph here,
83
+ * so a pull never waits on a push. The caller rolls the transaction back.
84
+ */
85
+ export function prepareReadTransaction(tx, runningSchemaVersion, checkpoints) {
86
+ return prepareHostTransaction(tx, 'snapshot', runningSchemaVersion, checkpoints);
87
+ }
88
+ async function prepareHostTransaction(tx, boundary, runningSchemaVersion, checkpoints) {
78
89
  if (!Number.isInteger(runningSchemaVersion) ||
79
90
  runningSchemaVersion < 1 ||
80
91
  runningSchemaVersion > 0x7fffffff)
81
92
  throw syncError('sync.invalid_request', 'schema version must be a positive 32-bit integer');
82
- if (typeof tx.lockPartition !== 'function')
83
- throw new StorageQueryError('sync.storage.partition_lock_unsupported');
84
- await tx.lockPartition();
93
+ if (boundary === 'lock') {
94
+ if (typeof tx.lockPartition !== 'function')
95
+ throw new StorageQueryError('sync.storage.partition_lock_unsupported');
96
+ await tx.lockPartition();
97
+ }
98
+ else {
99
+ if (typeof tx.pinSnapshot !== 'function')
100
+ throw new StorageQueryError('sync.storage.snapshot_unsupported');
101
+ await tx.pinSnapshot();
102
+ }
85
103
  const gate = await tx.readServeGate(runningSchemaVersion);
86
104
  const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
87
105
  if (refusal !== undefined)
@@ -17,7 +17,7 @@
17
17
  * the `sync` wake-up (§8.3).
18
18
  */
19
19
  import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
20
- import type { ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
20
+ import type { RealtimeNotifier, ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
21
21
  import { type SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
22
22
  import { type SyncularServerEvents } from './events.js';
23
23
  import { type CompiledSchema } from './schema.js';
@@ -53,6 +53,13 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
53
53
  * error, never a stale or lost latest document).
54
54
  */
55
55
  readonly presenceMinIntervalMs?: number;
56
+ /**
57
+ * §8.9: the bridge to the hubs of other hosts that hold sockets of the same
58
+ * partition. When set, the commits and registration changes of this hub's
59
+ * own rounds go to `fanout` in place of this hub, and `fanout` delivers
60
+ * them to every hub of the partition, this one included.
61
+ */
62
+ readonly fanout?: RealtimeNotifier;
56
63
  }
57
64
  export interface RealtimeConnectOptions {
58
65
  readonly partition: string;
@@ -311,6 +318,12 @@ export declare class RealtimeHub {
311
318
  wake(partition: string, reason: WakeReason): void;
312
319
  /** Wake every session on every partition (fanout listener gap, §8.3). */
313
320
  wakeAll(reason: WakeReason): void;
321
+ /**
322
+ * §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
323
+ * partition that has not observed that sequence with `catchup-required`; a
324
+ * session that observed a later commit was already woken by the gap (§8.2).
325
+ */
326
+ wakeBehind(partition: string, commitSeq: number): void;
314
327
  /**
315
328
  * §8.5: send `heartbeat` to every session. The host calls this on its
316
329
  * heartbeat interval (suggested 30 s); a client that hears nothing for twice
package/dist/realtime.js CHANGED
@@ -624,8 +624,14 @@ export class RealtimeSession {
624
624
  async refreshRegistrations(failClosed) {
625
625
  const generation = ++this.#registrationGeneration;
626
626
  let registrations;
627
+ /** The live units of the reloaded record: a unit the client still lists. */
628
+ let listed = new Set();
627
629
  try {
628
- registrations = await this.#hub.loadRegistrations(this, await this.#storage.getClientRecord(this.partition, this.clientId));
630
+ const record = await this.#storage.getClientRecord(this.partition, this.clientId);
631
+ registrations = await this.#hub.loadRegistrations(this, record);
632
+ listed = new Set((record?.registration?.units ?? [])
633
+ .map((scopes) => unitId(scopes))
634
+ .filter((id) => !record?.catchingUp.some((unit) => unit.id === id)));
629
635
  }
630
636
  catch {
631
637
  if (!failClosed) {
@@ -650,10 +656,12 @@ export class RealtimeSession {
650
656
  this.reconcilePresence(previousKeys);
651
657
  // §8.7: a host refresh that removes or narrows a registration wakes the
652
658
  // session, so its client runs the round whose §3.3 revocation purge
653
- // drops the rows it lost. A registration survives when the same unit
654
- // and table come back with every previous scope value still allowed.
655
- if (failClosed &&
656
- previous.some((old) => !registrations.some((next) => next.id === old.id &&
659
+ // drops the rows it lost. A round-end or post-pull reload wakes it when a
660
+ // unit the client still lists lost scopes: the round may have answered
661
+ // the unit active before the grant went. A registration survives when the
662
+ // same unit and table come back with every previous scope value allowed.
663
+ if (previous.some((old) => (failClosed || listed.has(old.id)) &&
664
+ !registrations.some((next) => next.id === old.id &&
657
665
  next.table === old.table &&
658
666
  Object.entries(next.effective).every(([variable, values]) => old.effective[variable]?.every((value) => values.includes(value)) ?? false))))
659
667
  this.sendWake('catchup-required');
@@ -1005,7 +1013,7 @@ export class RealtimeHub {
1005
1013
  partition: identity.partition,
1006
1014
  actorId: identity.actorId,
1007
1015
  ...(identity.context !== undefined ? { context: identity.context } : {}),
1008
- realtime: this,
1016
+ realtime: this.#config.fanout ?? this,
1009
1017
  };
1010
1018
  }
1011
1019
  /** The host's error reporter (`SyncServerConfig.onError`), if any. */
@@ -1227,6 +1235,20 @@ export class RealtimeHub {
1227
1235
  for (const session of this.#sessions)
1228
1236
  session.sendWake(reason);
1229
1237
  }
1238
+ /**
1239
+ * §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
1240
+ * partition that has not observed that sequence with `catchup-required`; a
1241
+ * session that observed a later commit was already woken by the gap (§8.2).
1242
+ */
1243
+ wakeBehind(partition, commitSeq) {
1244
+ for (const session of this.#sessions) {
1245
+ if (session.partition !== partition)
1246
+ continue;
1247
+ if (session.lastKnownSeq >= commitSeq)
1248
+ continue;
1249
+ session.sendWake('catchup-required');
1250
+ }
1251
+ }
1230
1252
  /**
1231
1253
  * §8.5: send `heartbeat` to every session. The host calls this on its
1232
1254
  * heartbeat interval (suggested 30 s); a client that hears nothing for twice
@@ -84,6 +84,10 @@ class SqliteTransaction extends SqliteFamilyTransaction {
84
84
  this.assertOpen();
85
85
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
86
86
  }
87
+ async pinSnapshot() {
88
+ this.assertOpen();
89
+ // The one connection's BEGIN IMMEDIATE already reads one snapshot.
90
+ }
87
91
  async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
88
92
  this.assertOpen();
89
93
  const result = this.#storage.db
@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
9
9
  constructor(cause: unknown, opIndex?: number);
10
10
  }
11
11
  /** Stable, privacy-safe failures for trusted server storage queries. */
12
- export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.scope_patterns_changed' | 'sync.storage.scope_value_missing' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.partition_lock_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
12
+ export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.scope_patterns_changed' | 'sync.storage.scope_value_missing' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.partition_lock_unsupported' | 'sync.storage.snapshot_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
13
13
  /**
14
14
  * Host-only query error. Messages never include identifiers, values, SQL,
15
15
  * paths, or row data; callers branch on `code`, never message text. The
@@ -29,6 +29,7 @@ const STORAGE_QUERY_MESSAGES = {
29
29
  'sync.storage.physical_layout_mismatch': 'a synced table does not match the storage layout the running code reads and writes',
30
30
  'sync.storage.transaction_query_unsupported': 'this storage transaction cannot run registered queries',
31
31
  'sync.storage.partition_lock_unsupported': 'this storage transaction cannot serialize partition authority',
32
+ 'sync.storage.snapshot_unsupported': 'this storage transaction cannot read one snapshot without the partition lock',
32
33
  'sync.storage.query_over_staged_writes': 'registered query reads a table this transaction has buffered writes for',
33
34
  'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
34
35
  'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
package/dist/storage.d.ts CHANGED
@@ -629,6 +629,15 @@ export interface StorageTransaction {
629
629
  * existing custom storage implementations fail closed at that boundary.
630
630
  */
631
631
  lockPartition?(): Promise<void>;
632
+ /**
633
+ * Make this transaction read one snapshot of committed state without the
634
+ * push-serialization lock, so a concurrent push neither waits for it nor
635
+ * becomes visible halfway through it (§6.8 host-owned read transactions).
636
+ * Must precede the transaction's first read. PostgreSQL sets
637
+ * `REPEATABLE READ READ ONLY`; SQLite's `BEGIN IMMEDIATE` already reads one
638
+ * snapshot. Host-owned paths call `prepareReadTransaction`.
639
+ */
640
+ pinSnapshot?(): Promise<void>;
632
641
  /**
633
642
  * Serialize every push apply for this partition before any operation read,
634
643
  * validation, merge, or write, and read the admission token once for the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.78.3",
3
+ "version": "0.79.0",
4
4
  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
68
68
  "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
69
69
  },
70
70
  "dependencies": {
71
- "@syncular/core": "0.78.3"
71
+ "@syncular/core": "0.79.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
package/src/events.ts CHANGED
@@ -299,6 +299,20 @@ export interface RealtimeWakeEvent extends RealtimeEventBase {
299
299
  readonly reason: WakeReason;
300
300
  }
301
301
 
302
+ /**
303
+ * §8.9: a bridge gave up delivering a commit, or a client's changed
304
+ * registrations, to the partition's other hosts after its retries. Sessions
305
+ * there learn of the commit from the next one, which arrives non-adjacent.
306
+ */
307
+ export interface RealtimeRelayFailedEvent {
308
+ readonly type: 'realtime.relay_failed';
309
+ readonly atMs: number;
310
+ readonly partition: string;
311
+ /** The commit the message carried; absent for changed registrations. */
312
+ readonly commitSeq?: number;
313
+ readonly attempts: number;
314
+ }
315
+
302
316
  /** A §4.6 prune pass finished (whether or not the horizon moved). */
303
317
  export interface PruneCompletedEvent {
304
318
  readonly type: 'prune.completed';
@@ -367,6 +381,7 @@ export type SyncularServerEvent = (
367
381
  | RealtimeClosedEvent
368
382
  | RealtimeDeltaEvent
369
383
  | RealtimeWakeEvent
384
+ | RealtimeRelayFailedEvent
370
385
  | PruneCompletedEvent
371
386
  | ScopesResolveFailedEvent
372
387
  | LeaseIssuedEvent
@@ -1774,6 +1774,14 @@ class PostgresTransaction implements StorageTransaction {
1774
1774
  await lockPartitionOn(this.#client, this.#partition);
1775
1775
  }
1776
1776
 
1777
+ async pinSnapshot(): Promise<void> {
1778
+ this.#assertOpen();
1779
+ // PostgreSQL refuses this after the transaction's first statement.
1780
+ await this.#client.query(
1781
+ 'SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY',
1782
+ );
1783
+ }
1784
+
1777
1785
  async advanceCheckpoint(
1778
1786
  name: string,
1779
1787
  ownerEpoch: number,
package/src/readiness.ts CHANGED
@@ -115,10 +115,37 @@ export function serveNotReadyError(refusal: ServeGateRefusal): SyncError {
115
115
  * Lock and gate a host-owned non-push transaction (§6.8). The caller checks
116
116
  * actor authority under the lock and commits or rolls back the transaction.
117
117
  */
118
- export async function prepareAuthorityTransaction(
118
+ export function prepareAuthorityTransaction(
119
119
  tx: StorageTransaction,
120
120
  runningSchemaVersion: number,
121
121
  checkpoints?: readonly CheckpointDeclaration[],
122
+ ): Promise<void> {
123
+ return prepareHostTransaction(tx, 'lock', runningSchemaVersion, checkpoints);
124
+ }
125
+
126
+ /**
127
+ * Pin a host-owned read transaction to one snapshot without the partition
128
+ * lock, then gate it (§6.8). A scope resolver reads its authority graph here,
129
+ * so a pull never waits on a push. The caller rolls the transaction back.
130
+ */
131
+ export function prepareReadTransaction(
132
+ tx: StorageTransaction,
133
+ runningSchemaVersion: number,
134
+ checkpoints?: readonly CheckpointDeclaration[],
135
+ ): Promise<void> {
136
+ return prepareHostTransaction(
137
+ tx,
138
+ 'snapshot',
139
+ runningSchemaVersion,
140
+ checkpoints,
141
+ );
142
+ }
143
+
144
+ async function prepareHostTransaction(
145
+ tx: StorageTransaction,
146
+ boundary: 'lock' | 'snapshot',
147
+ runningSchemaVersion: number,
148
+ checkpoints?: readonly CheckpointDeclaration[],
122
149
  ): Promise<void> {
123
150
  if (
124
151
  !Number.isInteger(runningSchemaVersion) ||
@@ -129,9 +156,15 @@ export async function prepareAuthorityTransaction(
129
156
  'sync.invalid_request',
130
157
  'schema version must be a positive 32-bit integer',
131
158
  );
132
- if (typeof tx.lockPartition !== 'function')
133
- throw new StorageQueryError('sync.storage.partition_lock_unsupported');
134
- await tx.lockPartition();
159
+ if (boundary === 'lock') {
160
+ if (typeof tx.lockPartition !== 'function')
161
+ throw new StorageQueryError('sync.storage.partition_lock_unsupported');
162
+ await tx.lockPartition();
163
+ } else {
164
+ if (typeof tx.pinSnapshot !== 'function')
165
+ throw new StorageQueryError('sync.storage.snapshot_unsupported');
166
+ await tx.pinSnapshot();
167
+ }
135
168
  const gate = await tx.readServeGate(runningSchemaVersion);
136
169
  const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
137
170
  if (refusal !== undefined) throw serveNotReadyError(refusal);
package/src/realtime.ts CHANGED
@@ -33,6 +33,7 @@ import {
33
33
  type WakeReason,
34
34
  } from '@syncular/core';
35
35
  import type {
36
+ RealtimeNotifier,
36
37
  ServerLimits,
37
38
  SyncRequestContext,
38
39
  SyncServerConfig,
@@ -95,6 +96,13 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
95
96
  * error, never a stale or lost latest document).
96
97
  */
97
98
  readonly presenceMinIntervalMs?: number;
99
+ /**
100
+ * §8.9: the bridge to the hubs of other hosts that hold sockets of the same
101
+ * partition. When set, the commits and registration changes of this hub's
102
+ * own rounds go to `fanout` in place of this hub, and `fanout` delivers
103
+ * them to every hub of the partition, this one included.
104
+ */
105
+ readonly fanout?: RealtimeNotifier;
98
106
  }
99
107
 
100
108
  export interface RealtimeConnectOptions {
@@ -831,10 +839,18 @@ export class RealtimeSession {
831
839
  async refreshRegistrations(failClosed: boolean): Promise<void> {
832
840
  const generation = ++this.#registrationGeneration;
833
841
  let registrations: Registration[];
842
+ /** The live units of the reloaded record: a unit the client still lists. */
843
+ let listed = new Set<string>();
834
844
  try {
835
- registrations = await this.#hub.loadRegistrations(
836
- this,
837
- await this.#storage.getClientRecord(this.partition, this.clientId),
845
+ const record = await this.#storage.getClientRecord(
846
+ this.partition,
847
+ this.clientId,
848
+ );
849
+ registrations = await this.#hub.loadRegistrations(this, record);
850
+ listed = new Set(
851
+ (record?.registration?.units ?? [])
852
+ .map((scopes) => unitId(scopes))
853
+ .filter((id) => !record?.catchingUp.some((unit) => unit.id === id)),
838
854
  );
839
855
  } catch {
840
856
  if (!failClosed) {
@@ -858,12 +874,14 @@ export class RealtimeSession {
858
874
  this.reconcilePresence(previousKeys);
859
875
  // §8.7: a host refresh that removes or narrows a registration wakes the
860
876
  // session, so its client runs the round whose §3.3 revocation purge
861
- // drops the rows it lost. A registration survives when the same unit
862
- // and table come back with every previous scope value still allowed.
877
+ // drops the rows it lost. A round-end or post-pull reload wakes it when a
878
+ // unit the client still lists lost scopes: the round may have answered
879
+ // the unit active before the grant went. A registration survives when the
880
+ // same unit and table come back with every previous scope value allowed.
863
881
  if (
864
- failClosed &&
865
882
  previous.some(
866
883
  (old) =>
884
+ (failClosed || listed.has(old.id)) &&
867
885
  !registrations.some(
868
886
  (next) =>
869
887
  next.id === old.id &&
@@ -1301,7 +1319,7 @@ export class RealtimeHub {
1301
1319
  partition: identity.partition,
1302
1320
  actorId: identity.actorId,
1303
1321
  ...(identity.context !== undefined ? { context: identity.context } : {}),
1304
- realtime: this,
1322
+ realtime: this.#config.fanout ?? this,
1305
1323
  };
1306
1324
  }
1307
1325
 
@@ -1573,6 +1591,19 @@ export class RealtimeHub {
1573
1591
  for (const session of this.#sessions) session.sendWake(reason);
1574
1592
  }
1575
1593
 
1594
+ /**
1595
+ * §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
1596
+ * partition that has not observed that sequence with `catchup-required`; a
1597
+ * session that observed a later commit was already woken by the gap (§8.2).
1598
+ */
1599
+ wakeBehind(partition: string, commitSeq: number): void {
1600
+ for (const session of this.#sessions) {
1601
+ if (session.partition !== partition) continue;
1602
+ if (session.lastKnownSeq >= commitSeq) continue;
1603
+ session.sendWake('catchup-required');
1604
+ }
1605
+ }
1606
+
1576
1607
  /**
1577
1608
  * §8.5: send `heartbeat` to every session. The host calls this on its
1578
1609
  * heartbeat interval (suggested 30 s); a client that hears nothing for twice
@@ -197,6 +197,11 @@ class SqliteTransaction
197
197
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
198
198
  }
199
199
 
200
+ async pinSnapshot(): Promise<void> {
201
+ this.assertOpen();
202
+ // The one connection's BEGIN IMMEDIATE already reads one snapshot.
203
+ }
204
+
200
205
  async advanceCheckpoint(
201
206
  name: string,
202
207
  ownerEpoch: number,
@@ -37,6 +37,7 @@ export type StorageQueryErrorCode =
37
37
  | 'sync.storage.physical_layout_mismatch'
38
38
  | 'sync.storage.transaction_query_unsupported'
39
39
  | 'sync.storage.partition_lock_unsupported'
40
+ | 'sync.storage.snapshot_unsupported'
40
41
  | 'sync.storage.query_over_staged_writes'
41
42
  | 'sync.storage.erase_unsupported'
42
43
  | 'sync.storage.invalid_erase_query';
@@ -77,6 +78,8 @@ const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
77
78
  'this storage transaction cannot run registered queries',
78
79
  'sync.storage.partition_lock_unsupported':
79
80
  'this storage transaction cannot serialize partition authority',
81
+ 'sync.storage.snapshot_unsupported':
82
+ 'this storage transaction cannot read one snapshot without the partition lock',
80
83
  'sync.storage.query_over_staged_writes':
81
84
  'registered query reads a table this transaction has buffered writes for',
82
85
  'sync.storage.scan_requires_scope':
package/src/storage.ts CHANGED
@@ -794,6 +794,15 @@ export interface StorageTransaction {
794
794
  * existing custom storage implementations fail closed at that boundary.
795
795
  */
796
796
  lockPartition?(): Promise<void>;
797
+ /**
798
+ * Make this transaction read one snapshot of committed state without the
799
+ * push-serialization lock, so a concurrent push neither waits for it nor
800
+ * becomes visible halfway through it (§6.8 host-owned read transactions).
801
+ * Must precede the transaction's first read. PostgreSQL sets
802
+ * `REPEATABLE READ READ ONLY`; SQLite's `BEGIN IMMEDIATE` already reads one
803
+ * snapshot. Host-owned paths call `prepareReadTransaction`.
804
+ */
805
+ pinSnapshot?(): Promise<void>;
797
806
  /**
798
807
  * Serialize every push apply for this partition before any operation read,
799
808
  * validation, merge, or write, and read the admission token once for the