@syncular/client 0.71.1 → 0.72.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/apply.d.ts CHANGED
@@ -71,9 +71,9 @@ export interface SqliteSegmentDescriptor {
71
71
  readonly scopeDigest: string;
72
72
  }
73
73
  /**
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
74
+ * Apply a §5.3 sqlite image in committed chunks of at most 65,536 rows,
75
+ * each sized from the time the chunk before took: validate the in-file
76
+ * metadata against the descriptor, validate the data table's column names/order against the generated schema, run the
77
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`.
@@ -87,6 +87,8 @@ export declare function applySqliteSegment(db: ClientDatabase, schema: CompiledC
87
87
  readonly transaction?: ApplyTransaction;
88
88
  readonly onProgress?: (rowsProcessed: number) => void;
89
89
  readonly isCurrent?: () => boolean;
90
+ /** Monotonic milliseconds that time each chunk. */
91
+ readonly now?: () => number;
90
92
  }): Promise<number>;
91
93
  /**
92
94
  * Apply a decoded rows segment: each block in one local transaction
package/dist/apply.js CHANGED
@@ -266,14 +266,15 @@ function imageInvalid(detail) {
266
266
  throw invalidRequest(`sqlite segment rejected: ${detail} (§5.3)`);
267
267
  }
268
268
  /**
269
- * Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
270
- * rows: validate the in-file metadata against the descriptor, validate the
271
- * data table's column names/order against the generated schema, run the
269
+ * Apply a §5.3 sqlite image in committed chunks of at most 65,536 rows,
270
+ * each sized from the time the chunk before took: validate the in-file
271
+ * metadata against the descriptor, validate the data table's column names/order against the generated schema, run the
272
272
  * §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
273
273
  * primary-key upsert — `_syncular_version` lands in
274
274
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
275
275
  */
276
276
  export async function applySqliteSegment(db, schema, table, bytes, descriptor, options) {
277
+ const now = options.now ?? (() => performance.now());
277
278
  const withImage = db.withSqliteImage?.bind(db);
278
279
  if (withImage === undefined) {
279
280
  throw invalidRequest('database cannot import images; disable accept bit 2 (§4.2)');
@@ -333,12 +334,12 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
333
334
  .map((name) => `${name}=excluded.${name}`)
334
335
  .join(', ');
335
336
  const version = quoteIdent(SYNC_VERSION_COLUMN);
336
- // A statement copies the 1,024 rows after `from`; NULL keys cannot hide
337
- // between statements.
338
- const range = (from) => {
337
+ // A statement copies the `rows` rows after `from`; NULL keys cannot
338
+ // hide between statements.
339
+ const range = (from, rows) => {
339
340
  const params = from === undefined ? [] : [from];
340
341
  const predicates = from === undefined ? [] : [`${primaryKey}>?`];
341
- const boundary = db.query(`SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`, params)[0]?.b;
342
+ const boundary = db.query(`SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET ${rows - 1}`, params)[0]?.b;
342
343
  if (boundary === null)
343
344
  imageInvalid('image primary key must not be null');
344
345
  if (boundary !== undefined) {
@@ -347,13 +348,17 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
347
348
  }
348
349
  return [boundary, predicates.join(' AND ') || 'true', params];
349
350
  };
350
- let [boundary, where, params] = range();
351
+ let [boundary, where, params] = range(undefined, 1024);
351
352
  let applied = 0;
352
- // §5.3: a transaction holds one statement at first and doubles after each
353
- // commit up to 64; a replaying transaction holds one.
354
- for (let statements = 1;; statements = Math.min(statements * 2, 64)) {
353
+ // §5.3: the first chunk holds 1,024 rows. A later chunk holds at most
354
+ // twice the rows of the one before, at most 65,536, and at most the rows
355
+ // the one before applied per 100 ms from its start to its COMMIT; a
356
+ // replaying chunk holds one statement.
357
+ for (let size = 1024;;) {
355
358
  if (options.isCurrent?.() === false)
356
359
  return applied;
360
+ const started = now();
361
+ let chunk = 0;
357
362
  const first = applied === 0;
358
363
  const replay = countOutbox(db) ||
359
364
  db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [
@@ -378,16 +383,18 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
378
383
  const kept = new Set();
379
384
  const skipped = new Set();
380
385
  const landing = rows.filter((row) => lands(db, table, String(row[table.primaryKey]), Number(row._syncular_version), kept, skipped));
381
- for (let statement = 1;; statement++) {
386
+ for (;;) {
382
387
  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);
383
- applied += Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
388
+ const copied = Number(db.query(`SELECT count(*)AS n FROM ${source} WHERE ${where}`, params)[0]?.n);
389
+ applied += copied;
390
+ chunk += copied;
384
391
  options.onProgress?.(applied);
385
392
  if (replay ||
386
- statement === statements ||
393
+ chunk >= size ||
387
394
  boundary === undefined ||
388
395
  applied === count)
389
396
  break;
390
- [boundary, where, params] = range(boundary);
397
+ [boundary, where, params] = range(boundary, Math.min(1024, size - chunk));
391
398
  }
392
399
  if (protectedRows)
393
400
  for (const row of landing) {
@@ -398,10 +405,12 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
398
405
  }
399
406
  return rebaseScope(scope, kept, skipped);
400
407
  });
408
+ const duration = now() - started;
401
409
  await yieldToHost();
402
410
  if (boundary === undefined || applied === count)
403
411
  break;
404
- [boundary, where, params] = range(boundary);
412
+ size = Math.max(1, Math.min(2 * chunk, 65_536, Math.floor((chunk * 100) / duration)));
413
+ [boundary, where, params] = range(boundary, Math.min(1024, size));
405
414
  }
406
415
  if (applied !== count)
407
416
  imageInvalid('image applied row count does not match descriptor');
package/dist/client.js CHANGED
@@ -772,7 +772,11 @@ export class SyncClient {
772
772
  this.#requireStarted();
773
773
  if (this.#preflightBarrier !== undefined)
774
774
  return this.#preflightBarrier;
775
- this.#securityLifecycle = 'preflight';
775
+ if (this.#securityLifecycle !== 'preflight')
776
+ this.#applyBatch((batch) => {
777
+ this.#securityLifecycle = 'preflight';
778
+ batch.status();
779
+ });
776
780
  this.#securityEpoch += 1;
777
781
  this.disconnectRealtime();
778
782
  const barrier = (async () => {
@@ -805,13 +809,15 @@ export class SyncClient {
805
809
  // §4.8: an interrupted eviction finishes before protected reads open.
806
810
  await this.#serialize(() => this.#drainPendingEvictions());
807
811
  this.#encryption = options.encryption;
808
- this.#securityLifecycle = 'active';
812
+ this.#applyBatch((batch) => {
813
+ this.#securityLifecycle = 'active';
814
+ batch.status();
815
+ });
809
816
  if (this.#hasStartupWork()) {
810
817
  this.#setSyncNeeded(true);
811
818
  this.#emitSyncNeeded('startup');
812
819
  this.#emitSyncIntent({ kind: 'interactive' });
813
820
  }
814
- this.#emitDiagnostics();
815
821
  }
816
822
  /** Persisted work an opened or activated replica owes one round (§8.4). */
817
823
  #hasStartupWork() {
@@ -1401,6 +1407,7 @@ export class SyncClient {
1401
1407
  schemaFloor: this.#schemaFloor,
1402
1408
  syncNeeded: this.#needsPull,
1403
1409
  previousVersionContext: this.#previousVersionStatus(),
1410
+ securityLifecycle: this.#securityLifecycle,
1404
1411
  };
1405
1412
  }
1406
1413
  /**
@@ -6,7 +6,7 @@
6
6
  * the frozen batch only after commit. Bridges forward this shape verbatim.
7
7
  */
8
8
  import type { ScopeMap } from '@syncular/core';
9
- import type { LeaseState, SchemaFloor } from './client.js';
9
+ import type { LeaseState, SchemaFloor, SecurityLifecycle } from './client.js';
10
10
  import type { CompiledClientTable } from './schema.js';
11
11
  export type LocalRevision = bigint;
12
12
  export interface TableChange {
@@ -26,6 +26,11 @@ export interface SyncStatusSnapshot {
26
26
  readonly leaseState: LeaseState | undefined;
27
27
  readonly schemaFloor: SchemaFloor | undefined;
28
28
  readonly syncNeeded: boolean;
29
+ /**
30
+ * §5.11: 'preflight' while protected reads, claims and sync are refused;
31
+ * a change batch carries the snapshot at each transition.
32
+ */
33
+ readonly securityLifecycle: SecurityLifecycle;
29
34
  /**
30
35
  * RFC 0005 A2: whether a previous-version cache is present, so a host's
31
36
  * update/rollback path can require its discard. `createdAtMs` is the capture
@@ -258,6 +258,12 @@ function localReadsBlocked(availability) {
258
258
  availability.reason === 'leader-incompatible' ||
259
259
  availability.reason === 'leadership-taken'));
260
260
  }
261
+ /** §5.11: a read or claim the security gate refused waits for activation. */
262
+ function refusedByPreflight(error) {
263
+ return (error instanceof Error &&
264
+ 'code' in error &&
265
+ error.code === 'client.security_preflight_required');
266
+ }
261
267
  /** One frozen snapshot per phase and availability for entries that have no
262
268
  * successful read, so switching between unread entries keeps the snapshot and
263
269
  * `rows` identity. */
@@ -295,6 +301,8 @@ class QueryEntry {
295
301
  #desiredRevision = 0n;
296
302
  #claimError;
297
303
  #claimPending = false;
304
+ #claimGated = false;
305
+ #gated = false;
298
306
  #offStatus;
299
307
  #offRound;
300
308
  constructor(store, spec, key, cache) {
@@ -375,8 +383,12 @@ class QueryEntry {
375
383
  if (generation !== this.#generation || this.#listeners.size === 0)
376
384
  return;
377
385
  this.#claimPending = false;
378
- this.#claimError = errorOf(error);
379
- this.#requestRead();
386
+ if (refusedByPreflight(error))
387
+ this.#gate(true);
388
+ else {
389
+ this.#claimError = errorOf(error);
390
+ this.#requestRead();
391
+ }
380
392
  });
381
393
  }
382
394
  refresh = () => {
@@ -395,6 +407,8 @@ class QueryEntry {
395
407
  this.#desiredRevision = 0n;
396
408
  this.#claimError = undefined;
397
409
  this.#claimPending = false;
410
+ this.#claimGated = false;
411
+ this.#gated = false;
398
412
  this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
399
413
  }
400
414
  dispose() {
@@ -479,6 +493,9 @@ class QueryEntry {
479
493
  });
480
494
  }
481
495
  #onAvailabilityChange() {
496
+ if (this.#gated &&
497
+ this.store.status.getSnapshot().status?.securityLifecycle !== 'preflight')
498
+ this.#resume();
482
499
  const availability = this.store.availabilitySnapshot();
483
500
  if (localReadsBlocked(availability)) {
484
501
  this.#publish({
@@ -502,6 +519,32 @@ class QueryEntry {
502
519
  if (wasBlocked)
503
520
  this.#requestRead();
504
521
  }
522
+ /** §5.11: the security gate refused this entry's read or claim. The
523
+ * entry keeps its snapshot and reads again when the status reports
524
+ * activation; a refusal that raced activation finds the client active. */
525
+ #gate(claim = false) {
526
+ this.#gated = true;
527
+ if (claim)
528
+ this.#claimGated = true;
529
+ if (this.#state.isRefreshing)
530
+ this.#publish({ ...this.#state, isRefreshing: false });
531
+ const generation = this.#generation;
532
+ void Promise.resolve(this.store.client.statusSnapshot()).then((status) => {
533
+ if (generation === this.#generation &&
534
+ status.securityLifecycle !== 'preflight')
535
+ this.#resume();
536
+ }, () => { });
537
+ }
538
+ #resume() {
539
+ if (!this.#gated)
540
+ return;
541
+ this.#gated = false;
542
+ if (this.#claimGated) {
543
+ this.#claimGated = false;
544
+ this.#claimCoverage();
545
+ }
546
+ this.#requestRead();
547
+ }
505
548
  /** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
506
549
  * sync attempt and resumes waiting when the next attempt starts. */
507
550
  #onRoundFailureChange() {
@@ -603,6 +646,11 @@ class QueryEntry {
603
646
  catch (error) {
604
647
  if (generation !== this.#generation || this.#listeners.size === 0)
605
648
  return;
649
+ if (refusedByPreflight(error)) {
650
+ this.#requested = false;
651
+ this.#gate();
652
+ return;
653
+ }
606
654
  // SPEC §7.5: a failed latest read is never `ready`; the last
607
655
  // successful rows and revision stay available beside the error.
608
656
  this.#publish({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.71.1",
3
+ "version": "0.72.1",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.71.1"
124
+ "@syncular/core": "0.72.1"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.71.1",
128
+ "@syncular/server": "0.72.1",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -469,9 +469,9 @@ function imageInvalid(detail: string): never {
469
469
  }
470
470
 
471
471
  /**
472
- * Apply a §5.3 sqlite image in committed transactions of 1,024 to 65,536
473
- * rows: validate the in-file metadata against the descriptor, validate the
474
- * data table's column names/order against the generated schema, run the
472
+ * Apply a §5.3 sqlite image in committed chunks of at most 65,536 rows,
473
+ * each sized from the time the chunk before took: validate the in-file
474
+ * metadata against the descriptor, validate the data table's column names/order against the generated schema, run the
475
475
  * §5.6 first-page clear when fresh, then bulk-copy 1,024-row ranges through a
476
476
  * primary-key upsert — `_syncular_version` lands in
477
477
  * `_sync_version` exactly like a rows segment's per-row `serverVersion`.
@@ -491,8 +491,11 @@ export async function applySqliteSegment(
491
491
  readonly transaction?: ApplyTransaction;
492
492
  readonly onProgress?: (rowsProcessed: number) => void;
493
493
  readonly isCurrent?: () => boolean;
494
+ /** Monotonic milliseconds that time each chunk. */
495
+ readonly now?: () => number;
494
496
  },
495
497
  ): Promise<number> {
498
+ const now = options.now ?? (() => performance.now());
496
499
  const withImage = db.withSqliteImage?.bind(db);
497
500
  if (withImage === undefined) {
498
501
  throw invalidRequest(
@@ -567,13 +570,13 @@ export async function applySqliteSegment(
567
570
  .map((name) => `${name}=excluded.${name}`)
568
571
  .join(', ');
569
572
  const version = quoteIdent(SYNC_VERSION_COLUMN);
570
- // A statement copies the 1,024 rows after `from`; NULL keys cannot hide
571
- // between statements.
572
- const range = (from?: SqlValue) => {
573
+ // A statement copies the `rows` rows after `from`; NULL keys cannot
574
+ // hide between statements.
575
+ const range = (from: SqlValue | undefined, rows: number) => {
573
576
  const params = from === undefined ? [] : [from];
574
577
  const predicates = from === undefined ? [] : [`${primaryKey}>?`];
575
578
  const boundary = db.query(
576
- `SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET 1023`,
579
+ `SELECT ${primaryKey} AS b FROM ${source} WHERE ${predicates[0] ?? 'true'} ORDER BY ${primaryKey} LIMIT 1 OFFSET ${rows - 1}`,
577
580
  params,
578
581
  )[0]?.b;
579
582
  if (boundary === null) imageInvalid('image primary key must not be null');
@@ -583,12 +586,16 @@ export async function applySqliteSegment(
583
586
  }
584
587
  return [boundary, predicates.join(' AND ') || 'true', params] as const;
585
588
  };
586
- let [boundary, where, params] = range();
589
+ let [boundary, where, params] = range(undefined, 1024);
587
590
  let applied = 0;
588
- // §5.3: a transaction holds one statement at first and doubles after each
589
- // commit up to 64; a replaying transaction holds one.
590
- for (let statements = 1; ; statements = Math.min(statements * 2, 64)) {
591
+ // §5.3: the first chunk holds 1,024 rows. A later chunk holds at most
592
+ // twice the rows of the one before, at most 65,536, and at most the rows
593
+ // the one before applied per 100 ms from its start to its COMMIT; a
594
+ // replaying chunk holds one statement.
595
+ for (let size = 1024; ;) {
591
596
  if (options.isCurrent?.() === false) return applied;
597
+ const started = now();
598
+ let chunk = 0;
592
599
  const first = applied === 0;
593
600
  const replay =
594
601
  countOutbox(db) ||
@@ -625,26 +632,31 @@ export async function applySqliteSegment(
625
632
  skipped,
626
633
  ),
627
634
  );
628
- for (let statement = 1; ; statement++) {
635
+ for (;;) {
629
636
  db.exec(
630
637
  `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}`,
631
638
  params,
632
639
  );
633
- applied += Number(
640
+ const copied = Number(
634
641
  db.query(
635
642
  `SELECT count(*)AS n FROM ${source} WHERE ${where}`,
636
643
  params,
637
644
  )[0]?.n,
638
645
  );
646
+ applied += copied;
647
+ chunk += copied;
639
648
  options.onProgress?.(applied);
640
649
  if (
641
650
  replay ||
642
- statement === statements ||
651
+ chunk >= size ||
643
652
  boundary === undefined ||
644
653
  applied === count
645
654
  )
646
655
  break;
647
- [boundary, where, params] = range(boundary);
656
+ [boundary, where, params] = range(
657
+ boundary,
658
+ Math.min(1024, size - chunk),
659
+ );
648
660
  }
649
661
  if (protectedRows)
650
662
  for (const row of landing) {
@@ -663,9 +675,14 @@ export async function applySqliteSegment(
663
675
  }
664
676
  return rebaseScope(scope, kept, skipped);
665
677
  });
678
+ const duration = now() - started;
666
679
  await yieldToHost();
667
680
  if (boundary === undefined || applied === count) break;
668
- [boundary, where, params] = range(boundary);
681
+ size = Math.max(
682
+ 1,
683
+ Math.min(2 * chunk, 65_536, Math.floor((chunk * 100) / duration)),
684
+ );
685
+ [boundary, where, params] = range(boundary, Math.min(1024, size));
669
686
  }
670
687
  if (applied !== count)
671
688
  imageInvalid('image applied row count does not match descriptor');
package/src/client.ts CHANGED
@@ -1642,7 +1642,11 @@ export class SyncClient {
1642
1642
  beginSecurityPreflight(): Promise<void> {
1643
1643
  this.#requireStarted();
1644
1644
  if (this.#preflightBarrier !== undefined) return this.#preflightBarrier;
1645
- this.#securityLifecycle = 'preflight';
1645
+ if (this.#securityLifecycle !== 'preflight')
1646
+ this.#applyBatch((batch) => {
1647
+ this.#securityLifecycle = 'preflight';
1648
+ batch.status();
1649
+ });
1646
1650
  this.#securityEpoch += 1;
1647
1651
  this.disconnectRealtime();
1648
1652
  const barrier = (async () => {
@@ -1681,13 +1685,15 @@ export class SyncClient {
1681
1685
  // §4.8: an interrupted eviction finishes before protected reads open.
1682
1686
  await this.#serialize(() => this.#drainPendingEvictions());
1683
1687
  this.#encryption = options.encryption;
1684
- this.#securityLifecycle = 'active';
1688
+ this.#applyBatch((batch) => {
1689
+ this.#securityLifecycle = 'active';
1690
+ batch.status();
1691
+ });
1685
1692
  if (this.#hasStartupWork()) {
1686
1693
  this.#setSyncNeeded(true);
1687
1694
  this.#emitSyncNeeded('startup');
1688
1695
  this.#emitSyncIntent({ kind: 'interactive' });
1689
1696
  }
1690
- this.#emitDiagnostics();
1691
1697
  }
1692
1698
 
1693
1699
  /** Persisted work an opened or activated replica owes one round (§8.4). */
@@ -2399,6 +2405,7 @@ export class SyncClient {
2399
2405
  schemaFloor: this.#schemaFloor,
2400
2406
  syncNeeded: this.#needsPull,
2401
2407
  previousVersionContext: this.#previousVersionStatus(),
2408
+ securityLifecycle: this.#securityLifecycle,
2402
2409
  };
2403
2410
  }
2404
2411
 
@@ -6,7 +6,7 @@
6
6
  * the frozen batch only after commit. Bridges forward this shape verbatim.
7
7
  */
8
8
  import type { ScopeMap } from '@syncular/core';
9
- import type { LeaseState, SchemaFloor } from './client';
9
+ import type { LeaseState, SchemaFloor, SecurityLifecycle } from './client';
10
10
  import type { CompiledClientTable } from './schema';
11
11
 
12
12
  export type LocalRevision = bigint;
@@ -30,6 +30,11 @@ export interface SyncStatusSnapshot {
30
30
  readonly leaseState: LeaseState | undefined;
31
31
  readonly schemaFloor: SchemaFloor | undefined;
32
32
  readonly syncNeeded: boolean;
33
+ /**
34
+ * §5.11: 'preflight' while protected reads, claims and sync are refused;
35
+ * a change batch carries the snapshot at each transition.
36
+ */
37
+ readonly securityLifecycle: SecurityLifecycle;
33
38
  /**
34
39
  * RFC 0005 A2: whether a previous-version cache is present, so a host's
35
40
  * update/rollback path can require its discard. `createdAtMs` is the capture
@@ -391,6 +391,15 @@ function localReadsBlocked(availability: SyncAvailability): boolean {
391
391
  );
392
392
  }
393
393
 
394
+ /** §5.11: a read or claim the security gate refused waits for activation. */
395
+ function refusedByPreflight(error: unknown): boolean {
396
+ return (
397
+ error instanceof Error &&
398
+ 'code' in error &&
399
+ error.code === 'client.security_preflight_required'
400
+ );
401
+ }
402
+
394
403
  /** One frozen snapshot per phase and availability for entries that have no
395
404
  * successful read, so switching between unread entries keeps the snapshot and
396
405
  * `rows` identity. */
@@ -428,6 +437,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
428
437
  #desiredRevision = 0n;
429
438
  #claimError: Error | undefined;
430
439
  #claimPending = false;
440
+ #claimGated = false;
441
+ #gated = false;
431
442
  #offStatus: (() => void) | undefined;
432
443
  #offRound: (() => void) | undefined;
433
444
 
@@ -518,8 +529,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
518
529
  if (generation !== this.#generation || this.#listeners.size === 0)
519
530
  return;
520
531
  this.#claimPending = false;
521
- this.#claimError = errorOf(error);
522
- this.#requestRead();
532
+ if (refusedByPreflight(error)) this.#gate(true);
533
+ else {
534
+ this.#claimError = errorOf(error);
535
+ this.#requestRead();
536
+ }
523
537
  },
524
538
  );
525
539
  }
@@ -538,6 +552,8 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
538
552
  this.#desiredRevision = 0n;
539
553
  this.#claimError = undefined;
540
554
  this.#claimPending = false;
555
+ this.#claimGated = false;
556
+ this.#gated = false;
541
557
  this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
542
558
  }
543
559
 
@@ -626,6 +642,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
626
642
  }
627
643
 
628
644
  #onAvailabilityChange(): void {
645
+ if (
646
+ this.#gated &&
647
+ this.store.status.getSnapshot().status?.securityLifecycle !== 'preflight'
648
+ )
649
+ this.#resume();
629
650
  const availability = this.store.availabilitySnapshot();
630
651
  if (localReadsBlocked(availability)) {
631
652
  this.#publish({
@@ -649,6 +670,37 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
649
670
  if (wasBlocked) this.#requestRead();
650
671
  }
651
672
 
673
+ /** §5.11: the security gate refused this entry's read or claim. The
674
+ * entry keeps its snapshot and reads again when the status reports
675
+ * activation; a refusal that raced activation finds the client active. */
676
+ #gate(claim = false): void {
677
+ this.#gated = true;
678
+ if (claim) this.#claimGated = true;
679
+ if (this.#state.isRefreshing)
680
+ this.#publish({ ...this.#state, isRefreshing: false });
681
+ const generation = this.#generation;
682
+ void Promise.resolve(this.store.client.statusSnapshot()).then(
683
+ (status) => {
684
+ if (
685
+ generation === this.#generation &&
686
+ status.securityLifecycle !== 'preflight'
687
+ )
688
+ this.#resume();
689
+ },
690
+ () => {},
691
+ );
692
+ }
693
+
694
+ #resume(): void {
695
+ if (!this.#gated) return;
696
+ this.#gated = false;
697
+ if (this.#claimGated) {
698
+ this.#claimGated = false;
699
+ this.#claimCoverage();
700
+ }
701
+ this.#requestRead();
702
+ }
703
+
652
704
  /** SPEC §7.5 failed transfer: incomplete coverage stops waiting on a failed
653
705
  * sync attempt and resumes waiting when the next attempt starts. */
654
706
  #onRoundFailureChange(): void {
@@ -759,6 +811,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
759
811
  } while (this.#requested && this.#listeners.size > 0);
760
812
  } catch (error) {
761
813
  if (generation !== this.#generation || this.#listeners.size === 0) return;
814
+ if (refusedByPreflight(error)) {
815
+ this.#requested = false;
816
+ this.#gate();
817
+ return;
818
+ }
762
819
  // SPEC §7.5: a failed latest read is never `ready`; the last
763
820
  // successful rows and revision stay available beside the error.
764
821
  this.#publish({