@syncular/client 0.85.0 → 0.90.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 (58) hide show
  1. package/README.md +13 -4
  2. package/dist/apply.d.ts +1 -1
  3. package/dist/apply.js +25 -26
  4. package/dist/blob.d.ts +0 -4
  5. package/dist/blob.js +7 -22
  6. package/dist/client.d.ts +31 -10
  7. package/dist/client.js +501 -465
  8. package/dist/diagnostics.d.ts +2 -4
  9. package/dist/diagnostics.js +3 -17
  10. package/dist/encryption.js +5 -30
  11. package/dist/errors.d.ts +2 -0
  12. package/dist/errors.js +4 -0
  13. package/dist/failed-overlay.d.ts +8 -2
  14. package/dist/failed-overlay.js +33 -22
  15. package/dist/local-purge.d.ts +1 -0
  16. package/dist/local-purge.js +1 -1
  17. package/dist/local-rebootstrap-receipt.js +2 -2
  18. package/dist/local-rebootstrap.js +1 -1
  19. package/dist/native-bridge.d.ts +8 -3
  20. package/dist/native-bridge.js +29 -12
  21. package/dist/outcomes.d.ts +13 -1
  22. package/dist/outcomes.js +21 -20
  23. package/dist/previous-version.js +23 -35
  24. package/dist/progress.d.ts +4 -0
  25. package/dist/progress.js +14 -2
  26. package/dist/realtime-supervisor.d.ts +4 -1
  27. package/dist/realtime-supervisor.js +2 -2
  28. package/dist/schema.js +14 -13
  29. package/dist/state.d.ts +16 -4
  30. package/dist/state.js +83 -44
  31. package/dist/sync-scheduler.d.ts +8 -2
  32. package/dist/sync-scheduler.js +11 -3
  33. package/dist/worker-core.js +14 -10
  34. package/dist/worker-host.d.ts +10 -2
  35. package/dist/worker-host.js +15 -0
  36. package/dist/worker-protocol.d.ts +4 -1
  37. package/package.json +3 -3
  38. package/src/apply.ts +34 -47
  39. package/src/blob.ts +7 -24
  40. package/src/client.ts +699 -553
  41. package/src/diagnostics.ts +3 -19
  42. package/src/encryption.ts +15 -40
  43. package/src/errors.ts +5 -0
  44. package/src/failed-overlay.ts +39 -29
  45. package/src/local-purge.ts +1 -1
  46. package/src/local-rebootstrap-receipt.ts +2 -5
  47. package/src/local-rebootstrap.ts +1 -2
  48. package/src/native-bridge.ts +40 -14
  49. package/src/outcomes.ts +36 -31
  50. package/src/previous-version.ts +31 -40
  51. package/src/progress.ts +18 -2
  52. package/src/realtime-supervisor.ts +7 -3
  53. package/src/schema.ts +13 -13
  54. package/src/state.ts +107 -64
  55. package/src/sync-scheduler.ts +17 -5
  56. package/src/worker-core.ts +14 -18
  57. package/src/worker-host.ts +30 -1
  58. package/src/worker-protocol.ts +4 -0
@@ -31,9 +31,10 @@
31
31
  */
32
32
  import type { RowColumn, RowValue } from '@syncular/core';
33
33
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
34
- import { ClientSyncError } from './errors';
34
+ import { ClientSyncError, localStateCorrupt } from './errors';
35
35
  import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap';
36
36
  import {
37
+ bytesToHex,
37
38
  type CompiledClientSchema,
38
39
  fromSqlValue,
39
40
  type JsonRowValue,
@@ -285,10 +286,7 @@ function hasExactKeys(
285
286
  }
286
287
 
287
288
  function localCorrupt(what: string): never {
288
- throw new ClientSyncError(
289
- 'sync.local_corrupt',
290
- `persisted ${what} is invalid`,
291
- );
289
+ throw localStateCorrupt(`persisted ${what} is invalid`);
292
290
  }
293
291
 
294
292
  // ---------------------------------------------------------------------------
@@ -649,12 +647,7 @@ export function capturePreviousVersion(
649
647
  function rowIdText(table: LocalSchemaDescriptorTable, row: SqlRow): string {
650
648
  const value = row[table.primaryKey] ?? null;
651
649
  if (value === null) return '';
652
- if (value instanceof Uint8Array) {
653
- return [...value]
654
- .map((byte) => byte.toString(16).padStart(2, '0'))
655
- .join('');
656
- }
657
- return String(value);
650
+ return value instanceof Uint8Array ? bytesToHex(value) : String(value);
658
651
  }
659
652
 
660
653
  function decodePreviousVersionPayload(
@@ -807,39 +800,37 @@ function firstIncompatibility(
807
800
  // validation, even against a removed table.
808
801
  if (operation.op === 'delete') continue;
809
802
  const table = schema.tables.get(operation.table);
810
- if (table === undefined) {
803
+ const column =
804
+ table &&
805
+ Object.keys(operation.values ?? {}).find(
806
+ (key) => !table.columnIndex.has(key),
807
+ );
808
+ // §7.1: an insert-intent operation presents every current column, so a
809
+ // non-nullable column it lacks leaves the commit unencodable.
810
+ const missing =
811
+ operation.insert === true
812
+ ? table?.columns.find(
813
+ (entry) =>
814
+ !entry.nullable && operation.values?.[entry.name] === undefined,
815
+ )
816
+ : undefined;
817
+ const refusal =
818
+ table === undefined
819
+ ? { reason: 'unknown-table' as const }
820
+ : column !== undefined
821
+ ? { reason: 'unknown-column' as const, column }
822
+ : missing !== undefined
823
+ ? {
824
+ reason: 'missing-required-column' as const,
825
+ column: missing.name,
826
+ }
827
+ : undefined;
828
+ if (refusal !== undefined)
811
829
  return {
812
830
  commitId: commit.clientCommitId,
813
831
  table: operation.table,
814
- reason: 'unknown-table',
832
+ ...refusal,
815
833
  };
816
- }
817
- for (const key of Object.keys(operation.values ?? {})) {
818
- if (!table.columnIndex.has(key)) {
819
- return {
820
- commitId: commit.clientCommitId,
821
- table: operation.table,
822
- reason: 'unknown-column',
823
- column: key,
824
- };
825
- }
826
- }
827
- // §7.1: an insert-intent operation presents every current column, so a
828
- // non-nullable column it lacks leaves the commit unencodable.
829
- if (operation.insert === true) {
830
- const missing = table.columns.find(
831
- (column) =>
832
- !column.nullable && operation.values?.[column.name] === undefined,
833
- );
834
- if (missing !== undefined) {
835
- return {
836
- commitId: commit.clientCommitId,
837
- table: operation.table,
838
- reason: 'missing-required-column',
839
- column: missing.name,
840
- };
841
- }
842
- }
843
834
  }
844
835
  return undefined;
845
836
  }
package/src/progress.ts CHANGED
@@ -14,6 +14,10 @@ export interface SyncProgress {
14
14
  readonly bytesTotal?: number | undefined;
15
15
  readonly rowsProcessed: number;
16
16
  readonly rowsTotal?: number | undefined;
17
+ /** The unit's bootstrap rows as the server counted them (SPEC §4.4, §7.7). */
18
+ readonly unitRowsTotal?: number | undefined;
19
+ /** Rows of the unit's bootstrap imported so far, across its sections. */
20
+ readonly unitRowsProcessed?: number | undefined;
17
21
  /** Time in this payload's import transactions before COMMIT, in ms. */
18
22
  readonly importWriteMs?: number | undefined;
19
23
  /** Time committing them and publishing their changes, in ms. */
@@ -68,7 +72,19 @@ export class ProgressEmitter {
68
72
  }
69
73
 
70
74
  update(update: Partial<SyncProgress>): void {
71
- if (this.#snapshot?.state === 'running')
72
- this.emit({ ...this.#snapshot, ...update });
75
+ const before = this.#snapshot;
76
+ if (before?.state !== 'running') return;
77
+ const next = { ...before, ...update };
78
+ // §7.7: each rise of the payload counter raises the unit's, and the unit
79
+ // total never falls below what was imported.
80
+ if (next.unitRowsProcessed !== undefined) {
81
+ const processed =
82
+ next.unitRowsProcessed +
83
+ Math.max(0, next.rowsProcessed - before.rowsProcessed);
84
+ next.unitRowsProcessed = processed;
85
+ if (next.unitRowsTotal !== undefined)
86
+ next.unitRowsTotal = Math.max(next.unitRowsTotal, processed);
87
+ }
88
+ this.emit(next);
73
89
  }
74
90
  }
@@ -11,7 +11,10 @@ type CancelTimer = () => void;
11
11
  export interface RealtimeSupervisorClient {
12
12
  connectRealtime(): Promise<void>;
13
13
  disconnectRealtime(): void | Promise<void>;
14
- syncUntilIdle(maxRounds?: number): unknown | Promise<unknown>;
14
+ /** Receives `{ skipEmpty: true }` (§8.4); a numeric-budget signature also fits. */
15
+ syncUntilIdle(
16
+ options?: number | { readonly skipEmpty?: boolean },
17
+ ): unknown | Promise<unknown>;
15
18
  diagnosticsSnapshot():
16
19
  | ClientDiagnosticsSnapshot
17
20
  | Promise<ClientDiagnosticsSnapshot>;
@@ -477,7 +480,7 @@ export class RealtimeSupervisor {
477
480
  return;
478
481
  }
479
482
  this.#round = Promise.resolve()
480
- .then(() => this.#client.syncUntilIdle())
483
+ .then(() => this.#client.syncUntilIdle({ skipEmpty: true }))
481
484
  .then(
482
485
  () => undefined,
483
486
  () => undefined,
@@ -637,7 +640,8 @@ export class RealtimeSupervisor {
637
640
  });
638
641
  this.#transport = true;
639
642
  }
640
- if (generation === this.#generation) await this.#client.syncUntilIdle();
643
+ if (generation === this.#generation)
644
+ await this.#client.syncUntilIdle({ skipEmpty: true });
641
645
  caughtUp = generation === this.#generation && this.#transport;
642
646
  } catch {
643
647
  // A refused socket or a failed catch-up round fails the attempt.
package/src/schema.ts CHANGED
@@ -18,7 +18,7 @@ import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay';
18
18
  */
19
19
  import type { RowColumn, RowValue } from '@syncular/core';
20
20
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
21
- import { ClientSyncError, invalidRequest } from './errors';
21
+ import { invalidRequest, localStateCorrupt } from './errors';
22
22
  import { snakeToCamel } from './naming';
23
23
 
24
24
  /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
@@ -383,11 +383,10 @@ function sqlType(column: RowColumn): string {
383
383
  case 'blob_ref':
384
384
  return 'TEXT';
385
385
  case 'integer':
386
+ case 'boolean':
386
387
  return 'INTEGER';
387
388
  case 'float':
388
389
  return 'REAL';
389
- case 'boolean':
390
- return 'INTEGER';
391
390
  case 'bytes':
392
391
  case 'crdt':
393
392
  // §5.10: a crdt column stores its opaque bytes locally, exactly like
@@ -712,12 +711,14 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
712
711
  UNITS_TABLE,
713
712
  "id TEXT PRIMARY KEY,scopes TEXT NOT NULL,explicit INTEGER NOT NULL DEFAULT 0,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT,cursor INTEGER DEFAULT -1,bootstrap_state TEXT,seeded TEXT NOT NULL DEFAULT '[]',echo TEXT",
714
713
  );
715
- // §5.6 applied-segment record, added after the table shipped.
716
- try {
717
- db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN applied TEXT`);
718
- } catch {
719
- // column already exists
720
- }
714
+ // §5.6 applied-segment record and §7.4.3 restriction, added after the
715
+ // table shipped.
716
+ for (const column of ['applied', 'restriction'])
717
+ try {
718
+ db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN ${column} TEXT`);
719
+ } catch {
720
+ // column already exists
721
+ }
721
722
  // §4.8 window registry: base + value → the unit it holds, the
722
723
  // completeness oracle and one of a unit's references (§4.1).
723
724
  createTable(
@@ -743,8 +744,7 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
743
744
  `SELECT 1 FROM ${legacyEvictions} WHERE NOT json_valid(effective_scopes) OR json_type(effective_scopes)<>'object' OR EXISTS(SELECT 1 FROM json_each(effective_scopes) WHERE json_type(value)<>'array' OR EXISTS(SELECT 1 FROM json_each(value) v WHERE v.type<>'text'))`,
744
745
  ).length > 0
745
746
  )
746
- throw new ClientSyncError(
747
- 'sync.local_corrupt',
747
+ throw localStateCorrupt(
748
748
  'a version 3 pending eviction cannot be upgraded',
749
749
  );
750
750
  db.exec(
@@ -790,7 +790,7 @@ export function resetLocalReplica(
790
790
  ): string[] {
791
791
  const kept = bump
792
792
  ? pruneUnknownUnits(db, schema, true)
793
- : { tables: new Set<string>(), units: [] };
793
+ : { tables: new Set<string>(), units: [], restricts: undefined };
794
794
  const keptNames = [...kept.tables];
795
795
  db.exec(
796
796
  `DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`,
@@ -815,7 +815,7 @@ export function resetLocalReplica(
815
815
  for (const table of schema.tables.values()) createSyncedTable(db, table);
816
816
  for (const table of schema.tables.values())
817
817
  for (const index of table.ftsIndexes) createFtsProjection(db, table, index);
818
- resetUnits(db, kept.units);
818
+ resetUnits(db, kept.units, kept.restricts);
819
819
  return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
820
820
  }
821
821
 
package/src/state.ts CHANGED
@@ -9,8 +9,13 @@ export const UNITS_TABLE = '_syncular_units';
9
9
  * contract is keyed on. The replica cursor, the echo digest and the
10
10
  * registration digest the server holds live in meta.
11
11
  */
12
- import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
13
- import { ClientSyncError } from './errors';
12
+ import {
13
+ definedObject,
14
+ type FencedRecord,
15
+ type ScopeMap,
16
+ type UnitScopes,
17
+ } from '@syncular/core';
18
+ import { localStateCorrupt } from './errors';
14
19
  import type { CompiledClientSchema, CompiledClientTable } from './schema';
15
20
  import type { ClientDatabase } from './database';
16
21
  import type { LocalRevision } from './invalidation';
@@ -48,6 +53,13 @@ export interface UnitRecord {
48
53
  /** §5.6 applied-segment record: segment id → rows applied at the unit's
49
54
  * current cursor and token. */
50
55
  readonly applied?: Readonly<Record<string, number>> | undefined;
56
+ /** §7.4.3 restriction: the kept cursor and the tables to bootstrap. */
57
+ readonly restrict?: Restriction | undefined;
58
+ }
59
+
60
+ export interface Restriction {
61
+ readonly cursor: number;
62
+ readonly tables: readonly string[];
51
63
  }
52
64
 
53
65
  /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
@@ -94,7 +106,8 @@ export function pairScopes(
94
106
  }
95
107
 
96
108
  /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
97
- * A bootstrapping unit owns the tables its current bootstrap seeded. */
109
+ * A bootstrapping unit owns the tables its current bootstrap seeded, and a
110
+ * restricted one the tables outside its restriction. */
98
111
  export function unitOwners(
99
112
  units: readonly UnitRecord[],
100
113
  table: CompiledClientTable,
@@ -106,7 +119,8 @@ export function unitOwners(
106
119
  (owning(unit) ||
107
120
  (unit.status === 'active' &&
108
121
  unit.echo !== undefined &&
109
- unit.seeded.includes(table.name))) &&
122
+ (unit.seeded.includes(table.name) ||
123
+ unit.restrict?.tables.includes(table.name) === false))) &&
110
124
  covers(table, unit.scopes)
111
125
  ? pairScopes(unit.scopes, table.name, unit.echo)
112
126
  : undefined;
@@ -116,18 +130,16 @@ export function unitOwners(
116
130
 
117
131
  /** A unit row; every persisted field must have its stored type and shape,
118
132
  * otherwise the row is `sync.local_corrupt` (§7.5). */
133
+ export const unitStateCorrupt = () =>
134
+ localStateCorrupt('persisted unit state is invalid');
135
+
119
136
  function rowToRecord(row: Record<string, unknown>): UnitRecord {
120
- const corrupt = () =>
121
- new ClientSyncError(
122
- 'sync.local_corrupt',
123
- 'persisted unit state is invalid',
124
- );
125
137
  const json = (raw: unknown): unknown => {
126
- if (typeof raw !== 'string') throw corrupt();
138
+ if (typeof raw !== 'string') throw unitStateCorrupt();
127
139
  try {
128
140
  return JSON.parse(raw);
129
141
  } catch {
130
- throw corrupt();
142
+ throw unitStateCorrupt();
131
143
  }
132
144
  };
133
145
  const isMap = (value: unknown): value is Record<string, unknown> =>
@@ -135,13 +147,14 @@ function rowToRecord(row: Record<string, unknown>): UnitRecord {
135
147
  const isStrings = (value: unknown): value is string[] =>
136
148
  Array.isArray(value) && value.every((item) => typeof item === 'string');
137
149
  const optionalText = (value: unknown) => {
138
- if (value !== null && typeof value !== 'string') throw corrupt();
150
+ if (value !== null && typeof value !== 'string') throw unitStateCorrupt();
139
151
  return value ?? undefined;
140
152
  };
141
153
  const scopes = json(row.scopes);
142
154
  const seeded = json(row.seeded);
143
155
  const echo = row.echo === null ? undefined : json(row.echo);
144
156
  const applied = row.applied === null ? undefined : json(row.applied);
157
+ const restrict = row.restriction === null ? undefined : json(row.restriction);
145
158
  const { id, status, cursor } = row;
146
159
  if (
147
160
  typeof id !== 'string' ||
@@ -164,22 +177,33 @@ function rowToRecord(row: Record<string, unknown>): UnitRecord {
164
177
  )
165
178
  ))
166
179
  )
167
- throw corrupt();
168
- const record: { -readonly [K in keyof UnitRecord]: UnitRecord[K] } = {
180
+ throw unitStateCorrupt();
181
+ let restriction: UnitRecord['restrict'];
182
+ if (restrict !== undefined) {
183
+ if (
184
+ !isMap(restrict) ||
185
+ !Number.isInteger(restrict.cursor) ||
186
+ !isStrings(restrict.tables)
187
+ )
188
+ throw unitStateCorrupt();
189
+ restriction = {
190
+ cursor: restrict.cursor as number,
191
+ tables: restrict.tables,
192
+ };
193
+ }
194
+ return definedObject({
169
195
  id,
170
196
  scopes: scopes as UnitScopes,
171
197
  explicit: row.explicit === 1,
172
198
  status,
173
199
  seeded,
174
- };
175
- const reasonCode = optionalText(row.reason_code);
176
- if (reasonCode !== undefined) record.reasonCode = reasonCode;
177
- if (typeof cursor === 'number') record.cursor = cursor;
178
- const bootstrapState = optionalText(row.bootstrap_state);
179
- if (bootstrapState !== undefined) record.bootstrapState = bootstrapState;
180
- if (echo !== undefined) record.echo = echo as FencedRecord[];
181
- if (applied !== undefined) record.applied = applied as Record<string, number>;
182
- return record;
200
+ reasonCode: optionalText(row.reason_code),
201
+ cursor: typeof cursor === 'number' ? cursor : undefined,
202
+ bootstrapState: optionalText(row.bootstrap_state),
203
+ echo: echo as FencedRecord[] | undefined,
204
+ applied: applied as Record<string, number> | undefined,
205
+ restrict: restriction,
206
+ });
183
207
  }
184
208
 
185
209
  /** Every unit in registration order (§4.1). */
@@ -201,7 +225,7 @@ export function getUnit(
201
225
  * §5.6 applied-segment record ends when the cursor or the token changes. */
202
226
  export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
203
227
  db.exec(
204
- `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo,applied=iif((cursor,bootstrap_state)IS(excluded.cursor,excluded.bootstrap_state),applied,NULL)`,
228
+ `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo,restriction)VALUES(?,?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo,restriction=excluded.restriction,applied=iif((cursor,bootstrap_state)IS(excluded.cursor,excluded.bootstrap_state),applied,NULL)`,
205
229
  [
206
230
  record.id,
207
231
  JSON.stringify(record.scopes),
@@ -212,6 +236,7 @@ export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
212
236
  record.bootstrapState ?? null,
213
237
  JSON.stringify(record.seeded),
214
238
  record.echo === undefined ? null : JSON.stringify(record.echo),
239
+ record.restrict === undefined ? null : JSON.stringify(record.restrict),
215
240
  ],
216
241
  );
217
242
  }
@@ -238,17 +263,24 @@ export function deleteUnit(db: ClientDatabase, id: string): void {
238
263
  * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
239
264
  * registrations (the app's declared intent) and discard the synced state of
240
265
  * every unit outside `keep`, so the next round sends the list and
241
- * fresh-bootstraps those units. The replica cursor survives only while a
266
+ * fresh-bootstraps those units. A bump (`restricts` given) keeps every echo
267
+ * and restricts the units it names. The replica cursor survives only while a
242
268
  * kept unit is live. Caller owns the transaction.
243
269
  */
244
270
  export function resetUnits(
245
271
  db: ClientDatabase,
246
272
  keep: readonly string[] = [],
273
+ restricts?: ReadonlyMap<string, Restriction>,
247
274
  ): void {
248
275
  db.exec(
249
- `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL,applied=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`,
276
+ `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',${restricts ? '' : 'echo=NULL,'}applied=NULL,restriction=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`,
250
277
  [...keep],
251
278
  );
279
+ for (const [id, restrict] of restricts ?? [])
280
+ db.exec(`UPDATE ${UNITS_TABLE} SET restriction=? WHERE id=?`, [
281
+ JSON.stringify(restrict),
282
+ id,
283
+ ]);
252
284
  db.exec(
253
285
  `DELETE FROM ${META_TABLE} WHERE key IN(?,?) OR key=? AND NOT EXISTS(SELECT 1 FROM ${UNITS_TABLE} WHERE cursor IS NULL)`,
254
286
  [ECHO_DIGEST_KEY, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY],
@@ -299,7 +331,11 @@ export function pruneUnknownUnits(
299
331
  db: ClientDatabase,
300
332
  schema: CompiledClientSchema,
301
333
  bump = false,
302
- ): { readonly tables: ReadonlySet<string>; readonly units: string[] } {
334
+ ): {
335
+ readonly tables: ReadonlySet<string>;
336
+ readonly units: string[];
337
+ readonly restricts: Map<string, Restriction>;
338
+ } {
303
339
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
304
340
  const previous =
305
341
  stored === undefined
@@ -318,10 +354,7 @@ export function pruneUnknownUnits(
318
354
  Array.isArray(generations) ||
319
355
  Object.values(generations).some((value) => typeof value !== 'string')
320
356
  )
321
- throw new ClientSyncError(
322
- 'sync.local_corrupt',
323
- 'invalid persisted table generations',
324
- );
357
+ throw localStateCorrupt('invalid persisted table generations');
325
358
  const kept = new Set(
326
359
  [...schema.tables.values()]
327
360
  .filter(
@@ -388,22 +421,41 @@ export function pruneUnknownUnits(
388
421
  db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
389
422
  deleteUnit(db, id);
390
423
  }
391
- return {
392
- tables: kept,
393
- units: loadUnits(db)
394
- .filter(
395
- ({ scopes }) =>
396
- Object.entries(previous ?? {}).every(
397
- ([name, old]) =>
398
- kept.has(name) ||
399
- !Object.keys(scopes).every((v) => old[v] !== undefined),
400
- ) &&
401
- [...schema.tables.values()].every(
402
- (table) => kept.has(table.name) || !covers(table, scopes),
403
- ),
404
- )
405
- .map((unit) => unit.id),
406
- };
424
+ const units: string[] = [];
425
+ const restricts = new Map<string, Restriction>();
426
+ for (const unit of loadUnits(db)) {
427
+ const covered = [...schema.tables.values()]
428
+ .filter((table) => covers(table, unit.scopes))
429
+ .map((table) => table.name);
430
+ if (
431
+ Object.entries(previous ?? {}).every(
432
+ ([name, old]) =>
433
+ kept.has(name) ||
434
+ !Object.keys(unit.scopes).every((v) => old[v] !== undefined),
435
+ ) &&
436
+ covered.every((name) => kept.has(name))
437
+ ) {
438
+ units.push(unit.id);
439
+ continue;
440
+ }
441
+ // §7.4.3 restriction: a live, post-bootstrap or restricted unit keeps its
442
+ // rows of kept tables through its kept cursor and bootstraps the rest.
443
+ const tables = covered
444
+ .filter((name) => !kept.has(name) || unit.restrict?.tables.includes(name))
445
+ .sort();
446
+ const cursor =
447
+ unit.restrict?.cursor ??
448
+ (bootstrapping(unit) ? -1 : (unit.cursor ?? replicaCursor(db)));
449
+ if (
450
+ bump &&
451
+ unit.status === 'active' &&
452
+ cursor >= 0 &&
453
+ tables.length > 0 &&
454
+ tables.length < covered.length
455
+ )
456
+ restricts.set(unit.id, { cursor, tables });
457
+ }
458
+ return { tables: kept, units, restricts };
407
459
  }
408
460
 
409
461
  export function getMeta(db: ClientDatabase, key: string): string | undefined {
@@ -422,20 +474,14 @@ export function setMeta(db: ClientDatabase, key: string, value: string): void {
422
474
  export function getLocalRevision(db: ClientDatabase): LocalRevision {
423
475
  const raw = getMeta(db, LOCAL_REVISION_KEY);
424
476
  if (raw === undefined) return 0n;
425
- if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw)) {
426
- throw new ClientSyncError(
427
- 'sync.local_corrupt',
428
- 'persisted local revision is invalid',
429
- );
430
- }
431
- const revision = BigInt(raw);
432
- if (revision > MAX_U64) {
433
- throw new ClientSyncError(
434
- 'sync.local_corrupt',
435
- 'persisted local revision is invalid',
436
- );
477
+ if (
478
+ typeof raw !== 'string' ||
479
+ !/^(0|[1-9][0-9]*)$/.test(raw) ||
480
+ BigInt(raw) > MAX_U64
481
+ ) {
482
+ throw localStateCorrupt('persisted local revision is invalid');
437
483
  }
438
- return revision;
484
+ return BigInt(raw);
439
485
  }
440
486
 
441
487
  /**
@@ -445,10 +491,7 @@ export function getLocalRevision(db: ClientDatabase): LocalRevision {
445
491
  export function bumpLocalRevision(db: ClientDatabase): LocalRevision {
446
492
  const current = getLocalRevision(db);
447
493
  if (current === MAX_U64) {
448
- throw new ClientSyncError(
449
- 'sync.local_corrupt',
450
- 'local revision exhausted u64',
451
- );
494
+ throw localStateCorrupt('local revision exhausted u64');
452
495
  }
453
496
  const next = current + 1n;
454
497
  setMeta(db, LOCAL_REVISION_KEY, next.toString());
@@ -1,11 +1,12 @@
1
1
  import type { WakeReason } from '@syncular/core';
2
- import type { SecurityLifecycle } from './client';
2
+ import type { SecurityLifecycle, SyncIdleOptions } from './client';
3
+ import { invalidRequest } from './errors';
3
4
  import type { SyncIntent } from './invalidation';
4
5
 
5
6
  export interface SyncSchedulerClient {
6
7
  statusSnapshot(): { readonly syncNeeded: boolean };
7
8
  securityLifecycle(): SecurityLifecycle;
8
- syncUntilIdle(maxRounds?: number): Promise<unknown>;
9
+ syncUntilIdle(options: SyncIdleOptions): Promise<unknown>;
9
10
  onSyncNeeded(
10
11
  listener: (reason: 'startup' | 'hello' | WakeReason) => void,
11
12
  ): () => void;
@@ -14,6 +15,12 @@ export interface SyncSchedulerClient {
14
15
 
15
16
  export interface SyncSchedulerOptions {
16
17
  readonly maxRounds?: number;
18
+ /**
19
+ * §8.4: milliseconds a queued drive waits before it starts, so the claims
20
+ * and writes of one burst ride in one round. Default 0: the drive starts
21
+ * in the next microtask.
22
+ */
23
+ readonly coalesceMs?: number;
17
24
  readonly onError?: (error: unknown) => void;
18
25
  readonly now?: () => number;
19
26
  readonly queueMicrotask?: (callback: () => void) => void;
@@ -30,6 +37,9 @@ export function installSyncScheduler(
30
37
  client: SyncSchedulerClient,
31
38
  options: SyncSchedulerOptions = {},
32
39
  ): SyncScheduler {
40
+ const coalesceMs = options.coalesceMs ?? 0;
41
+ if (!(Number.isFinite(coalesceMs) && coalesceMs >= 0))
42
+ throw invalidRequest('coalesceMs must be a non-negative finite number');
33
43
  const now = options.now ?? Date.now;
34
44
  const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
35
45
  const schedule =
@@ -71,12 +81,14 @@ export function installSyncScheduler(
71
81
  immediatePending = true;
72
82
  if (stopped || running || immediateQueued) return;
73
83
  immediateQueued = true;
74
- enqueue(() => {
84
+ const start = (): void => {
75
85
  immediateQueued = false;
76
86
  if (stopped || !immediatePending) return;
77
87
  immediatePending = false;
78
88
  run();
79
- });
89
+ };
90
+ if (coalesceMs > 0) schedule(start, coalesceMs);
91
+ else enqueue(start);
80
92
  };
81
93
 
82
94
  const run = (): void => {
@@ -88,7 +100,7 @@ export function installSyncScheduler(
88
100
  running = true;
89
101
  backgroundReady = false;
90
102
  void client
91
- .syncUntilIdle(options.maxRounds)
103
+ .syncUntilIdle({ maxRounds: options.maxRounds, skipEmpty: true })
92
104
  .then((result) => {
93
105
  retryDelayMs = 250;
94
106
  if (