@syncular/client 0.65.1 → 0.66.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
@@ -150,17 +150,21 @@ installRealtimeSupervisor(handle, {
150
150
  });
151
151
  ```
152
152
 
153
- It owns one connection attempt, retries initial failure and later socket loss
154
- with bounded exponential jitter, suspends while offline/background/protected,
155
- runs `syncUntilIdle()` before reporting `connected`, and cancels before
156
- `close()`.
153
+ It owns one connection attempt at a time, retries initial failure and later
154
+ socket loss with bounded exponential jitter, suspends while
155
+ offline/background/protected without resetting that backoff, runs
156
+ `syncUntilIdle()` before reporting `connected`, and settles its attempt and
157
+ disconnect before `close()` closes the client. A failed disconnect, an
158
+ unreadable first diagnostics read, or a throwing timer cancel latches phase
159
+ `unsupported` with a `failureCode`, and `close()` rejects with a
160
+ `RealtimeSupervisorError` of that code.
157
161
 
158
162
  Multi-tab handles share ONE leader socket across every tab, so pass
159
163
  `sharedTransport: true` (the templates do): backgrounding this tab then
160
164
  leaves the shared socket alone — a sibling tab may still be visible — while
161
165
  offline and protection continue to suspend. Each client accepts exactly one
162
166
  supervisor for its lifetime; a second `installRealtimeSupervisor` call
163
- throws. `realtimeSupervisorSnapshot()` and
167
+ throws `realtime.supervisor_already_installed`. `realtimeSupervisorSnapshot()` and
164
168
  `subscribeRealtimeSupervisor()` expose only `phase`, `attempt`, and the bounded
165
169
  library delay for UI/diagnostics—never raw transport prose or identities.
166
170
 
@@ -844,8 +848,12 @@ through the core, without intermediate download updates.
844
848
 
845
849
  Import reports every 1,024 rows and its final count. `rowsProcessed` includes work
846
850
  inside the current transaction; a failed import can roll those rows back. SQLite
847
- images commit in chunks of at most 1,024 rows and yield after each commit.
848
- Earlier committed chunks survive a later interruption. `complete` follows checkpoint persistence
851
+ images commit in transactions of 1,024 rows, then twice as many per transaction
852
+ up to 65,536, and yield after each commit. Earlier committed transactions
853
+ survive a later interruption. A SQLite image payload also reports
854
+ `importWriteMs` (time before COMMIT: row statements with index maintenance)
855
+ and `importCommitMs` (COMMIT and revision publication), each summed over the
856
+ payload's transactions. `complete` follows checkpoint persistence
849
857
  and optimistic-state reconciliation for the round. More bootstrap pages can
850
858
  remain; use window coverage to determine whether a query is complete.
851
859
  Listener exceptions do not fail sync. Listeners should hand UI work off and avoid
package/dist/apply.d.ts CHANGED
@@ -71,10 +71,10 @@ export interface SqliteSegmentDescriptor {
71
71
  readonly scopeDigest: string;
72
72
  }
73
73
  /**
74
- * Apply a §5.3 sqlite image in committed chunks of at most 1,024 rows: validate
75
- * the in-file metadata against the descriptor, validate the data table's
76
- * column names/order against the generated schema, run the §5.6
77
- * first-page clear when fresh, then bulk-copy each chunk through a
74
+ * Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
75
+ * rows: validate the in-file metadata against the descriptor, validate the
76
+ * data table's column names/order against the generated schema, run the
77
+ * §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
78
78
  * primary-key upsert — `_syncular_version` lands in
79
79
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
80
80
  */
package/dist/apply.js CHANGED
@@ -125,29 +125,15 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
125
125
  * fatal (`sync.schema_mismatch`): the descriptor validates, never infers.
126
126
  */
127
127
  export function validateSegmentColumns(schema, table, segment) {
128
- const mismatch = (detail) => {
129
- throw new ClientSyncError('sync.schema_mismatch', `rows segment for ${JSON.stringify(segment.table)} does not match the generated schema: ${detail}`);
130
- };
131
- if (segment.table !== table.name) {
132
- mismatch(`segment table ${JSON.stringify(segment.table)}`);
133
- }
134
- if (segment.schemaVersion !== schema.version) {
135
- mismatch(`segment schemaVersion ${segment.schemaVersion}`);
136
- }
137
- if (segment.columns.length !== table.columns.length) {
138
- mismatch(`column count ${segment.columns.length}`);
139
- }
140
- for (let i = 0; i < table.columns.length; i++) {
141
- const expected = table.columns[i];
142
- const actual = segment.columns[i];
143
- if (expected === undefined || actual === undefined)
144
- continue;
145
- if (expected.name !== actual.name ||
146
- expected.type !== actual.type ||
147
- expected.nullable !== actual.nullable) {
148
- mismatch(`column ${i} (${actual.name})`);
149
- }
150
- }
128
+ const column = segment.columns.length !== table.columns.length
129
+ ? 'count'
130
+ : table.columns.findIndex((expected, i) => expected.name !== segment.columns[i]?.name ||
131
+ expected.type !== segment.columns[i]?.type ||
132
+ expected.nullable !== segment.columns[i]?.nullable);
133
+ if (segment.table !== table.name ||
134
+ segment.schemaVersion !== schema.version ||
135
+ column !== -1)
136
+ throw new ClientSyncError('sync.schema_mismatch', 'rows segment columns do not match the generated schema (§5.2)', false, column === -1 ? { table: table.name } : { table: table.name, column });
151
137
  }
152
138
  /**
153
139
  * Scope-matched local delete (§3.3 purge / §4.8 eviction / §5.6 first-page
@@ -252,10 +238,10 @@ function imageInvalid(detail) {
252
238
  throw invalidRequest(`sqlite segment rejected: ${detail} (§5.3)`);
253
239
  }
254
240
  /**
255
- * Apply a §5.3 sqlite image in committed chunks of at most 1,024 rows: validate
256
- * the in-file metadata against the descriptor, validate the data table's
257
- * column names/order against the generated schema, run the §5.6
258
- * first-page clear when fresh, then bulk-copy each chunk through a
241
+ * Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
242
+ * rows: validate the in-file metadata against the descriptor, validate the
243
+ * data table's column names/order against the generated schema, run the
244
+ * §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
259
245
  * primary-key upsert — `_syncular_version` lands in
260
246
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
261
247
  */
@@ -285,23 +271,13 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
285
271
  if (meta.length !== 1 || record === undefined) {
286
272
  imageInvalid('_syncular_segment must contain exactly one row');
287
273
  }
288
- if (record.format !== 1)
289
- imageInvalid(`format ${String(record.format)}`);
290
- if (record.tbl !== table.name) {
291
- imageInvalid(`image table ${String(record.tbl)}`);
292
- }
293
- if (Number(record.sv) !== schema.version) {
294
- imageInvalid(`schemaVersion ${String(record.sv)}`);
295
- }
296
- if (Number(record.pin) !== descriptor.asOfCommitSeq) {
297
- imageInvalid(`asOfCommitSeq ${String(record.pin)}`);
298
- }
299
- if (record.sd !== descriptor.scopeDigest) {
300
- imageInvalid('scopeDigest mismatch');
301
- }
302
- if (Number(record.rc) !== descriptor.rowCount) {
303
- imageInvalid(`rowCount ${String(record.rc)}`);
304
- }
274
+ if (record.format !== 1 ||
275
+ record.tbl !== table.name ||
276
+ Number(record.sv) !== schema.version ||
277
+ Number(record.pin) !== descriptor.asOfCommitSeq ||
278
+ record.sd !== descriptor.scopeDigest ||
279
+ Number(record.rc) !== descriptor.rowCount)
280
+ imageInvalid('_syncular_segment does not match the descriptor');
305
281
  // 2. Column names and order vs the generated schema (§5.3 rule 3 —
306
282
  // sync.schema_mismatch, the §5.2 rule specialized).
307
283
  const info = db.query(`PRAGMA ${IMAGE_ALIAS}.table_info(${quoteIdent(table.name)})`);
@@ -312,7 +288,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
312
288
  const actual = info.map((row) => String(row.name));
313
289
  if (actual.length !== expected.length ||
314
290
  expected.some((name, index) => actual[index] !== name)) {
315
- throw new ClientSyncError('sync.schema_mismatch', `sqlite segment for ${JSON.stringify(table.name)} does not match the generated schema: columns [${actual.join(', ')}] (§5.3)`);
291
+ throw new ClientSyncError('sync.schema_mismatch', 'sqlite segment columns do not match the generated schema (§5.3)', false, { table: table.name });
316
292
  }
317
293
  const primaryKeys = info.filter((column) => Number(column.pk) > 0);
318
294
  if (primaryKeys.length !== 1 || primaryKeys[0]?.name !== table.primaryKey)
@@ -329,50 +305,62 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
329
305
  .map((name) => `${name}=excluded.${name}`)
330
306
  .join(', ');
331
307
  const version = quoteIdent(SYNC_VERSION_COLUMN);
332
- let after;
333
- let applied = 0;
334
- for (;;) {
335
- if (options.isCurrent?.() === false)
336
- return applied;
337
- const boundary = db.query(`SELECT ${primaryKey} AS boundary FROM ${source} ${after === undefined ? '' : `WHERE ${primaryKey} > ?`} ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, after === undefined ? [] : [after])[0]?.boundary;
308
+ // A statement copies the 1,024 rows after `from`; NULL keys cannot hide
309
+ // between statements.
310
+ const range = (from) => {
311
+ const params = from === undefined ? [] : [from];
312
+ const predicates = from === undefined ? [] : [`${primaryKey}>?`];
313
+ const boundary = db.query(`SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, params)[0]?.b;
338
314
  if (boundary === null)
339
315
  imageInvalid('image primary key must not be null');
340
- const predicates = [];
341
- const params = [];
342
- if (after !== undefined) {
343
- predicates.push(`${primaryKey} > ?`);
344
- params.push(after);
345
- }
346
316
  if (boundary !== undefined) {
347
- predicates.push(`${primaryKey} <= ?`);
317
+ predicates.push(`${primaryKey}<=?`);
348
318
  params.push(boundary);
349
319
  }
320
+ return [boundary, predicates.join(' AND ') || 'true', params];
321
+ };
322
+ let [boundary, where, params] = range();
323
+ let applied = 0;
324
+ // §5.3: a transaction holds one statement at first and doubles after each
325
+ // commit up to 64; a replaying transaction holds one.
326
+ for (let statements = 1;; statements = Math.min(statements * 2, 64)) {
327
+ if (options.isCurrent?.() === false)
328
+ return applied;
329
+ const first = applied === 0;
350
330
  const replay = countOutbox(db) ||
351
331
  db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [
352
332
  table.name,
353
333
  ]).length;
354
334
  const rows = replay
355
- ? db.query(`SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`, params)
335
+ ? db.query(`SELECT * FROM ${source} WHERE ${where}`, params)
356
336
  : [];
357
337
  (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
358
338
  const scope = !replay
359
339
  ? []
360
340
  : [
361
341
  ...(hasUniqueIndex(table) ? [JSON.stringify([table.name])] : []),
362
- ...(after === undefined && options.clearFirst
342
+ ...(first && options.clearFirst
363
343
  ? bootstrapScope(db, table, options.effective, options.owners)
364
344
  : []),
365
345
  ...rows.map((row) => JSON.stringify([table.name, String(row[table.primaryKey])])),
366
346
  ];
367
347
  const protectedRows = restoreFailedBases(db, schema, scope);
368
- if (after === undefined && options.clearFirst)
348
+ if (first && options.clearFirst)
369
349
  deleteScopedRows(db, table, options.effective, options.owners);
370
350
  const kept = new Set();
371
351
  const skipped = new Set();
372
352
  const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
373
- const where = predicates.join(' AND ') || 'true';
374
- db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${where} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates} WHERE excluded.${version}>${quoteIdent(table.name)}.${version}`, params);
375
- applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
353
+ for (let statement = 1;; statement++) {
354
+ db.exec(`INSERT INTO ${quoteIdent(table.name)}(${insertNames.join(', ')})SELECT ${[...names, quoteIdent('_syncular_version')].join(', ')} FROM ${source} WHERE ${where} ON CONFLICT(${primaryKey})DO UPDATE SET ${updates} WHERE excluded.${version}>${quoteIdent(table.name)}.${version}`, params);
355
+ applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
356
+ options.onProgress?.(applied);
357
+ if (replay ||
358
+ statement === statements ||
359
+ boundary === undefined ||
360
+ applied === count)
361
+ break;
362
+ [boundary, where, params] = range(boundary);
363
+ }
376
364
  if (protectedRows)
377
365
  for (const row of landing) {
378
366
  retainedBaseWrite(db, table, String(row[table.primaryKey]), Object.fromEntries(table.columns.map((column) => [
@@ -382,14 +370,15 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
382
370
  }
383
371
  return rebaseScope(scope, kept, skipped);
384
372
  });
385
- options.onProgress?.(applied);
386
373
  await yieldToHost();
387
374
  if (boundary === undefined || applied === count)
388
375
  break;
389
- after = boundary;
376
+ [boundary, where, params] = range(boundary);
390
377
  }
391
378
  if (applied !== count)
392
379
  imageInvalid('image applied row count does not match descriptor');
380
+ // A file replica's WAL keeps its high-water size until truncated.
381
+ db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
393
382
  return applied;
394
383
  });
395
384
  }
package/dist/client.js CHANGED
@@ -3915,6 +3915,8 @@ export class SyncClient {
3915
3915
  bytesTotal: frame.byteLength,
3916
3916
  rowsProcessed: 0,
3917
3917
  rowsTotal: frame.rowCount,
3918
+ importWriteMs: undefined,
3919
+ importCommitMs: undefined,
3918
3920
  });
3919
3921
  prefetch();
3920
3922
  const pending = prefetched.get(frame);
@@ -3947,11 +3949,13 @@ export class SyncClient {
3947
3949
  bytesTotal: bytes.byteLength,
3948
3950
  rowsProcessed: 0,
3949
3951
  rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
3952
+ importWriteMs: undefined,
3953
+ importCommitMs: undefined,
3950
3954
  });
3951
3955
  await this.#applySegmentOrFail(section, summary, image?.table ?? segment.table, (table, clearFirst, effective, owners) => {
3952
3956
  const options = this.#segmentApplyOptions(table, clearFirst, effective, owners, image !== undefined
3953
3957
  ? image.rowCount > 0
3954
- : segment.blocks.some((block) => block.length > 0), resetEpoch);
3958
+ : segment.blocks.some((block) => block.length > 0), resetEpoch, image !== undefined);
3955
3959
  return image !== undefined
3956
3960
  ? applySqliteSegment(this.#db, this.#schema, table, bytes, image, options)
3957
3961
  : applyRowsSegment(this.#db, this.#schema, table, segment, options, this.#encryption);
@@ -4355,21 +4359,37 @@ export class SyncClient {
4355
4359
  this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${scope.sql} LIMIT 1`, scope.params).length > 0);
4356
4360
  }
4357
4361
  /** Shared transaction, reset fence and progress for both segment formats. */
4358
- #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch) {
4362
+ #segmentApplyOptions(table, clearFirst, effective, owners, hasRows, resetEpoch, image) {
4363
+ let writeMs = 0;
4364
+ let commitMs = 0;
4359
4365
  return {
4360
4366
  clearFirst,
4361
4367
  effective,
4362
4368
  owners,
4363
4369
  isCurrent: () => this.#localResetEpoch === resetEpoch,
4364
4370
  onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
4365
- transaction: (fn) => this.#applyBatch((batch) => {
4366
- if (hasRows ||
4367
- (clearFirst && this.#scopedRowsExist(table, effective, owners)))
4368
- batch.table(table.name);
4369
- const result = fn();
4370
- this.#replayOutbox(result, false);
4371
+ transaction: (fn) => {
4372
+ const started = performance.now();
4373
+ let written = started;
4374
+ const result = this.#applyBatch((batch) => {
4375
+ if (hasRows ||
4376
+ (clearFirst && this.#scopedRowsExist(table, effective, owners)))
4377
+ batch.table(table.name);
4378
+ const result = fn();
4379
+ this.#replayOutbox(result, false);
4380
+ written = performance.now();
4381
+ return result;
4382
+ });
4383
+ // §7.7: image payloads report their import cost.
4384
+ writeMs += written - started;
4385
+ commitMs += performance.now() - written;
4386
+ if (image)
4387
+ this.#progress.update({
4388
+ importWriteMs: Math.round(writeMs),
4389
+ importCommitMs: Math.round(commitMs),
4390
+ });
4371
4391
  return result;
4372
- }),
4392
+ },
4373
4393
  };
4374
4394
  }
4375
4395
  /**
@@ -11,6 +11,10 @@ export interface SyncProgress {
11
11
  readonly bytesTotal?: number;
12
12
  readonly rowsProcessed: number;
13
13
  readonly rowsTotal?: number;
14
+ /** Time in this payload's import transactions before COMMIT, in ms. */
15
+ readonly importWriteMs?: number | undefined;
16
+ /** Time committing them and publishing their changes, in ms. */
17
+ readonly importCommitMs?: number | undefined;
14
18
  readonly errorCode?: string;
15
19
  readonly causeKind?: TransportCauseKind;
16
20
  readonly httpStatus?: number;
@@ -1,5 +1,6 @@
1
1
  import type { SecurityLifecycle } from './client.js';
2
2
  import type { ClientDiagnosticsConnectivity, ClientDiagnosticsListener, ClientDiagnosticsSnapshot } from './diagnostics.js';
3
+ import { ClientSyncError } from './errors.js';
3
4
  type CancelTimer = () => void;
4
5
  export interface RealtimeSupervisorClient {
5
6
  connectRealtime(): Promise<void>;
@@ -23,13 +24,18 @@ export interface RealtimeSupervisorSnapshot {
23
24
  readonly attempt: number;
24
25
  /** Bounded host-policy delay, never server or transport prose. */
25
26
  readonly retryDelayMs?: number;
27
+ /** The latched failure of phase `unsupported` (or `stopped`). */
28
+ readonly failureCode?: RealtimeSupervisorFailureCode;
26
29
  }
30
+ /** SPEC §10.3: client-local supervisor failures, never on the wire. */
31
+ export type RealtimeSupervisorFailureCode = 'realtime.diagnostics_unavailable' | 'realtime.disconnect_failed' | 'realtime.cleanup_failed';
27
32
  export interface RealtimeSupervisorOptions {
28
33
  /**
29
34
  * Host online/offline evidence, the only connectivity the supervisor
30
35
  * trusts: a failed round does not suspend it. Unknown remains connectable
31
- * and observable. Each `online` report drives `syncUntilIdle`, so work a
32
- * failed round left behind resumes without realtime.
36
+ * and observable. Each `online` report drives `syncUntilIdle` while no
37
+ * socket is connected, so work a failed round left behind resumes without
38
+ * realtime.
33
39
  */
34
40
  readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
35
41
  /** Browser/native foreground evidence. Background suspends a tab-owned
@@ -73,12 +79,33 @@ export declare function browserConnectivitySignal(options?: BrowserConnectivityS
73
79
  /** Browser/Tauri-webview visibility evidence without importing DOM types. */
74
80
  export declare function documentLifecycleSignal(options?: DocumentLifecycleSignalOptions): RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
75
81
  /**
76
- * Supported host policy for Syncular's explicit realtime transport. It owns
77
- * exactly one connect attempt, runs an explicit catch-up round before claiming
78
- * connected, retries transient loss with bounded exponential jitter, and
79
- * suspends across offline, background, or protected-preflight state. Each
80
- * failed attempt, each host `online` report, and each foreground return
81
- * while no attempt starts at once drives one HTTP round (§1.8).
82
+ * SPEC §8.4: a supervisor failure. `code` is the latest latched failure, or
83
+ * `realtime.cleanup_failed` when only a cancel threw. Every failure of the
84
+ * lifetime is also named in its own field. Cause codes are Syncular codes or
85
+ * `unknown`; no message or original error is retained.
86
+ */
87
+ export declare class RealtimeSupervisorError extends ClientSyncError {
88
+ readonly name = "RealtimeSupervisorError";
89
+ readonly code: RealtimeSupervisorFailureCode;
90
+ readonly cleanupFailureCode?: 'realtime.cleanup_failed';
91
+ readonly diagnosticsFailureCode?: 'realtime.diagnostics_unavailable';
92
+ /** The code the client's `disconnectRealtime` rejected with. */
93
+ readonly disconnectCauseCode?: string;
94
+ /** Set by the installed `close()` when the client close failed as well. */
95
+ readonly stopFailureCode?: RealtimeSupervisorFailureCode;
96
+ readonly closeFailureCode?: string;
97
+ constructor(code: RealtimeSupervisorFailureCode, fields?: Omit<Partial<RealtimeSupervisorError>, 'code'>);
98
+ }
99
+ /**
100
+ * Supported host policy for Syncular's explicit realtime transport (§8.4). It
101
+ * owns one attempt at a time: a connect, then an explicit catch-up round
102
+ * before it claims connected. A successor never starts before the previous
103
+ * attempt and its disconnect settle. Transient loss retries with bounded
104
+ * exponential jitter, and the backoff survives offline, background and
105
+ * protected suspensions. While no socket is connected, each failed connect,
106
+ * each host `online` report and each foreground return drives one HTTP round
107
+ * (§1.8). A disconnect, diagnostics or cleanup failure latches phase
108
+ * `unsupported` with its `failureCode`, and `stop()` rejects with it.
82
109
  */
83
110
  export declare class RealtimeSupervisor {
84
111
  #private;
@@ -86,13 +113,20 @@ export declare class RealtimeSupervisor {
86
113
  snapshot(): RealtimeSupervisorSnapshot;
87
114
  subscribe(listener: () => void): () => void;
88
115
  start(): void;
89
- stop(): void;
116
+ /**
117
+ * Cancel the timer and every subscription, release the socket, and settle
118
+ * once the in-flight attempt, its disconnect and any driven round have
119
+ * settled. Rejects with a {@link RealtimeSupervisorError} when a failure
120
+ * latched during the lifetime or a cancel threw; every caller shares it.
121
+ */
122
+ stop(): Promise<void>;
90
123
  }
91
124
  /**
92
- * Install one supervisor and make client disposal cancel it before close.
93
- * A client accepts exactly one supervisor for its lifetime; installing a
94
- * second throws, because silently keeping the first would discard the second
95
- * call's options.
125
+ * Install one supervisor and make client disposal stop it before close.
126
+ * Repeated and reentrant `close()` calls share one operation. A client accepts
127
+ * exactly one supervisor for its lifetime; installing a second throws
128
+ * `realtime.supervisor_already_installed`, because silently keeping the first
129
+ * would discard the second call's options.
96
130
  */
97
131
  export declare function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(client: T, options?: RealtimeSupervisorOptions): T;
98
132
  export declare function realtimeSupervisorSnapshot(client: object): RealtimeSupervisorSnapshot;