@syncular/client 0.85.0 → 0.86.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/src/client.ts CHANGED
@@ -379,7 +379,7 @@ export interface SyncIdleResult extends SyncSummary {
379
379
 
380
380
  export interface SyncIdleOptions {
381
381
  /** §7.8: a strict positive round count. Default: 20. */
382
- readonly maxRounds?: number;
382
+ readonly maxRounds?: number | undefined;
383
383
  /**
384
384
  * Total budget for one drive, across every round, on the client clock. A
385
385
  * drive past it after a completed round resolves with `budgetExhausted`.
@@ -388,6 +388,12 @@ export interface SyncIdleOptions {
388
388
  * `Infinity` disables the bound.
389
389
  */
390
390
  readonly timeoutMs?: number;
391
+ /**
392
+ * §8.4 host policy: end the drive without a round when the replica has no
393
+ * unit, no outbox commit, and no unit list to clear on the server. The
394
+ * shipped host loops pass it; the native bridge ignores it.
395
+ */
396
+ readonly skipEmpty?: boolean;
391
397
  }
392
398
 
393
399
  export type CurrentBaseProof =
@@ -438,6 +444,18 @@ export interface SyncClientLimits {
438
444
  * raises `client.push_request_too_large` and stays queued.
439
445
  */
440
446
  readonly maxPushRequestBytes?: number;
447
+ /**
448
+ * §5.4: rows segment downloads one pull response runs at once. Default 4.
449
+ * SQLite images keep their own bound of two (§5.3).
450
+ */
451
+ readonly segmentPrefetch?: number;
452
+ /**
453
+ * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
454
+ * exceeds it, unreferenced bodies without pending work are evicted oldest
455
+ * first after each cache write. Referenced bodies stay cached even past the
456
+ * cap. Absent: retain until storage pressure.
457
+ */
458
+ readonly blobCacheMaxBytes?: number;
441
459
  }
442
460
 
443
461
  export interface SyncClientConfig {
@@ -452,14 +470,6 @@ export interface SyncClientConfig {
452
470
  readonly segments?: SegmentDownloader;
453
471
  /** Blob upload/download (§5.9). Required to use `uploadBlob`/`fetchBlob`. */
454
472
  readonly blobs?: BlobTransport;
455
- /**
456
- * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
457
- * exceeds this, unreferenced bodies without pending work are evicted in
458
- * creation timestamp order after each cache write. Referenced bodies remain cached
459
- * even when that exceeds the cap. Absent means retain until storage pressure (the shipped
460
- * default; a referenced body always stays resolvable without a re-download).
461
- */
462
- readonly blobCacheMaxBytes?: number;
463
473
  readonly realtime?: RealtimeConnector;
464
474
  /**
465
475
  * SPEC §8.8: how sync rounds treat the realtime binding. `optional`
@@ -928,6 +938,15 @@ export type ClientSnapshotReader = {
928
938
  | Promise<ReturnType<ClientSnapshotMethods[Key]>>;
929
939
  };
930
940
 
941
+ /** Encodes a request in the current wire version. */
942
+ function encodeRequestFrames(frames: RequestFrame[]): Uint8Array {
943
+ return encodeRequest({
944
+ wireVersion: PROTOCOL_WIRE_VERSION,
945
+ msgKind: 'request',
946
+ frames,
947
+ });
948
+ }
949
+
931
950
  /** §7.7: progress fields of a payload; no payload is current. */
932
951
  const NO_PAYLOAD: Partial<SyncProgress> = {
933
952
  table: undefined,
@@ -1087,6 +1106,7 @@ export class SyncClient {
1087
1106
  config.limits?.maxPushOperationsPerRequest,
1088
1107
  ],
1089
1108
  ['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
1109
+ ['segmentPrefetch', config.limits?.segmentPrefetch],
1090
1110
  ] as const) {
1091
1111
  if (
1092
1112
  value !== undefined &&
@@ -1094,7 +1114,7 @@ export class SyncClient {
1094
1114
  ) {
1095
1115
  throw new ClientSyncError(
1096
1116
  'sync.invalid_request',
1097
- 'push limit must be an integer in 1..=4294967295',
1117
+ 'limit must be an integer in 1..=4294967295',
1098
1118
  false,
1099
1119
  { limit: name },
1100
1120
  );
@@ -2365,8 +2385,7 @@ export class SyncClient {
2365
2385
  )
2366
2386
  : 0;
2367
2387
  const pressure =
2368
- this.#config.blobCacheMaxBytes !== undefined &&
2369
- blobBytes > this.#config.blobCacheMaxBytes;
2388
+ blobBytes > (this.#config.limits?.blobCacheMaxBytes ?? Infinity);
2370
2389
  return {
2371
2390
  status: pressure ? 'pressure' : 'healthy',
2372
2391
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
@@ -2647,7 +2666,7 @@ export class SyncClient {
2647
2666
 
2648
2667
  /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
2649
2668
  #enforceBlobCacheCap(): void {
2650
- const cap = this.#config.blobCacheMaxBytes;
2669
+ const cap = this.#config.limits?.blobCacheMaxBytes;
2651
2670
  if (cap === undefined) return;
2652
2671
  enforceBlobCacheCap(this.#db, this.#schema, cap);
2653
2672
  }
@@ -4086,13 +4105,7 @@ export class SyncClient {
4086
4105
  // frames make a valid probe whose encoded size cancels out of the
4087
4106
  // per-commit delta measured against the canonical encoder.
4088
4107
  const baseBytes =
4089
- byteCap === undefined
4090
- ? 0
4091
- : encodeRequest({
4092
- wireVersion: PROTOCOL_WIRE_VERSION,
4093
- msgKind: 'request',
4094
- frames: [header, pull],
4095
- }).length;
4108
+ byteCap === undefined ? 0 : encodeRequestFrames([header, pull]).length;
4096
4109
  const pushFrames: RequestFrame[] = [];
4097
4110
  const outbox: OutboxCommit[] = [];
4098
4111
  const frameBytes: number[] = [];
@@ -4189,11 +4202,7 @@ export class SyncClient {
4189
4202
  const frame =
4190
4203
  byteCap === undefined
4191
4204
  ? 0
4192
- : encodeRequest({
4193
- wireVersion: PROTOCOL_WIRE_VERSION,
4194
- msgKind: 'request',
4195
- frames: [header, pushFrame, pull],
4196
- }).length - baseBytes;
4205
+ : encodeRequestFrames([header, pushFrame, pull]).length - baseBytes;
4197
4206
  // The head is always encoded so the caller can report the full
4198
4207
  // projected request size with the final header and subscription bytes;
4199
4208
  // a later commit defers once it no longer fits.
@@ -4621,11 +4630,7 @@ export class SyncClient {
4621
4630
  // The fixed frames encode as envelope + fixed frames + END; each
4622
4631
  // admitted push frame adds its own (5 + payload). Trimming the tail
4623
4632
  // re-fits the request to the final registration state.
4624
- const fixedBytes = encodeRequest({
4625
- wireVersion: PROTOCOL_WIRE_VERSION,
4626
- msgKind: 'request',
4627
- frames: fixedFrames,
4628
- }).length;
4633
+ const fixedBytes = encodeRequestFrames(fixedFrames).length;
4629
4634
  if (fixedBytes > byteCap)
4630
4635
  throw this.#pushCapacityError('bytes', byteCap, fixedBytes);
4631
4636
  let admittedBytes = 0;
@@ -4651,11 +4656,7 @@ export class SyncClient {
4651
4656
  ...pushFrames,
4652
4657
  ...fixedFrames.slice(lead.length),
4653
4658
  ];
4654
- const requestBytes = encodeRequest({
4655
- wireVersion: PROTOCOL_WIRE_VERSION,
4656
- msgKind: 'request',
4657
- frames,
4658
- });
4659
+ const requestBytes = encodeRequestFrames(frames);
4659
4660
  const responseBytes = await this.#roundTrip(requestBytes, signal);
4660
4661
  const message = decodeResponse(responseBytes);
4661
4662
  // §1.5: a complete, decodable response ends the report obligation.
@@ -4789,17 +4790,18 @@ export class SyncClient {
4789
4790
  !(Number.isFinite(timeoutMs) && timeoutMs > 0)
4790
4791
  )
4791
4792
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
4792
- const key = `${maxRounds ?? 'default'}:${timeoutMs}`;
4793
+ const skipEmpty = typeof options === 'object' && options.skipEmpty === true;
4794
+ const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}`;
4793
4795
  const pending = this.#syncIdlePending.get(key);
4794
4796
  if (pending !== undefined) return pending;
4795
4797
  const previous = this.#syncIdleTail;
4796
4798
  let drive: Promise<SyncIdleResult>;
4797
4799
  if (previous === undefined) {
4798
- drive = this.#syncIdleRounds(maxRounds, timeoutMs);
4800
+ drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4799
4801
  } else {
4800
4802
  drive = previous.then(() => {
4801
4803
  this.#syncIdlePending.delete(key);
4802
- return this.#syncIdleRounds(maxRounds, timeoutMs);
4804
+ return this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4803
4805
  });
4804
4806
  this.#syncIdlePending.set(key, drive);
4805
4807
  }
@@ -4818,6 +4820,7 @@ export class SyncClient {
4818
4820
  async #syncIdleRounds(
4819
4821
  maxRounds: number | undefined,
4820
4822
  timeoutMs: number,
4823
+ skipEmpty: boolean,
4821
4824
  ): Promise<SyncIdleResult> {
4822
4825
  const budget = maxRounds ?? 20;
4823
4826
  const aggregate = {
@@ -4835,6 +4838,21 @@ export class SyncClient {
4835
4838
  budgetExhausted,
4836
4839
  };
4837
4840
  };
4841
+ // §8.4: a replica without units, outbox work, or a server-side unit list
4842
+ // to clear has nothing to exchange; a host drive ends without a round.
4843
+ this.#requireActive();
4844
+ if (
4845
+ skipEmpty &&
4846
+ this.#schemaFloor === undefined &&
4847
+ !this.#hasStartupWork() &&
4848
+ loadUnits(this.#db).length === 0 &&
4849
+ (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined ||
4850
+ getMeta(this.#db, REGISTERED_DIGEST_KEY) ===
4851
+ bytesToHex(registrationDigest([])))
4852
+ ) {
4853
+ this.#setSyncNeeded(false);
4854
+ return result(false);
4855
+ }
4838
4856
  const states = () =>
4839
4857
  JSON.stringify(
4840
4858
  loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
@@ -5436,11 +5454,12 @@ export class SyncClient {
5436
5454
 
5437
5455
  // §5.4/§5.5: queue every segment download of this response, so a paged
5438
5456
  // bootstrap overlaps its page fetches instead of paying one blocking round
5439
- // trip per page. At most four downloads run at once, the Rust native
5440
- // transport's pool size: enough to overlap round trips, while the client
5441
- // holds at most four bodies, the one being applied and three ahead. An
5442
- // image starts only beside at most one other body, so at most two are
5443
- // images (§5.3 client memory); later descriptors wait in order. The
5457
+ // trip per page. `limits.segmentPrefetch` downloads run at once, by
5458
+ // default four, the Rust native transport's pool size: enough to overlap
5459
+ // round trips, while the client holds that many bodies, the one being
5460
+ // applied and the rest ahead. An image starts only beside at most one
5461
+ // other body, so at most two are images (§5.3 client memory) whatever the
5462
+ // limit; later descriptors wait in order. The
5444
5463
  // loop takes each body out of the map before applying it and tops the
5445
5464
  // window up at the next descriptor. Eligibility mirrors the loop: a
5446
5465
  // descriptor outside an applied section or from an unconfigured
@@ -5452,7 +5471,7 @@ export class SyncClient {
5452
5471
  const prefetch = () => {
5453
5472
  for (
5454
5473
  let next;
5455
- prefetched.size < 4 &&
5474
+ prefetched.size < (this.#config.limits?.segmentPrefetch ?? 4) &&
5456
5475
  !(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
5457
5476
  (next = queued.shift());
5458
5477
  ) {
@@ -5593,11 +5612,17 @@ export class SyncClient {
5593
5612
  skip: false,
5594
5613
  }
5595
5614
  : undefined;
5596
- // §7.7: a section boundary ends the previous payload.
5615
+ // §7.7: a section boundary ends the previous payload; the same
5616
+ // snapshot takes the section's extent (§4.4).
5617
+ const extent = message.frames[index + 1];
5618
+ const stated =
5619
+ section !== undefined && extent?.type === 'UNIT_EXTENT';
5597
5620
  this.#progress.update({
5598
5621
  ...NO_PAYLOAD,
5599
5622
  phase: 'import',
5600
5623
  unitId: section?.unit.id,
5624
+ unitRowsTotal: stated ? extent.rowsTotal : undefined,
5625
+ unitRowsProcessed: stated ? extent.rowsDone : undefined,
5601
5626
  });
5602
5627
  break;
5603
5628
  }
@@ -5625,19 +5650,22 @@ export class SyncClient {
5625
5650
  // §5.6: rows an earlier attempt at this position applied. A
5626
5651
  // partly applied image already ran its table's first-page clear.
5627
5652
  appliedRows = section.unit.applied?.[frame.segmentId];
5628
- if (appliedRows !== undefined) {
5629
- section.seeded.add(frame.table);
5630
- if (appliedRows === frame.rowCount) break;
5631
- }
5653
+ if (appliedRows !== undefined) section.seeded.add(frame.table);
5654
+ const imported = appliedRows === frame.rowCount;
5632
5655
  this.#progress.update({
5633
5656
  ...NO_PAYLOAD,
5634
- phase: 'download',
5657
+ phase: imported ? 'import' : 'download',
5635
5658
  unitId,
5636
5659
  table: frame.table,
5637
5660
  segmentId: frame.segmentId,
5638
- bytesTotal: frame.byteLength,
5661
+ bytesTotal: imported ? undefined : frame.byteLength,
5639
5662
  rowsTotal: frame.rowCount,
5640
5663
  });
5664
+ if (imported) {
5665
+ // §7.7: an earlier attempt imported this payload.
5666
+ this.#progress.update({ rowsProcessed: frame.rowCount });
5667
+ break;
5668
+ }
5641
5669
  prefetch();
5642
5670
  const pending = prefetched.get(frame);
5643
5671
  prefetched.delete(frame);
@@ -5748,6 +5776,10 @@ export class SyncClient {
5748
5776
  this.#localResetEpoch === resetEpoch
5749
5777
  ) {
5750
5778
  this.#finishSection(section, frame, summary);
5779
+ // §7.7: a completed bootstrap ends at what it imported.
5780
+ const processed = this.#progress.snapshot()?.unitRowsProcessed;
5781
+ if (frame.bootstrapState === undefined && processed !== undefined)
5782
+ this.#progress.update({ unitRowsTotal: processed });
5751
5783
  }
5752
5784
  section = undefined;
5753
5785
  // The counters stay: `complete` and `failed` report them.
@@ -6679,7 +6711,7 @@ export class SyncClient {
6679
6711
  const values = table.columns.map((column) =>
6680
6712
  jsonToRowValue(image.values?.[column.name] ?? null),
6681
6713
  );
6682
- upsertLocalRow(this.#db, table, values, image.syncVersion, false);
6714
+ upsertLocalRow(this.#db, table, values, image.syncVersion);
6683
6715
  }
6684
6716
 
6685
6717
  #legacyUndoOptimisticRows(
@@ -6867,7 +6899,7 @@ export class SyncClient {
6867
6899
  ).length
6868
6900
  )
6869
6901
  continue;
6870
- upsertLocalRow(this.#db, table, values, version, false);
6902
+ upsertLocalRow(this.#db, table, values, version);
6871
6903
  }
6872
6904
  }
6873
6905
 
package/src/encryption.ts CHANGED
@@ -116,23 +116,16 @@ function encryptionKeyId(
116
116
  }
117
117
  const selectorColumn = config.keyIdColumns?.[table.name];
118
118
  if (selectorColumn === undefined) return table.name;
119
- const index = table.columns.findIndex(
120
- (column) => column.name === selectorColumn,
121
- );
122
- if (index < 0) {
123
- throw new EncryptError(
124
- `encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`,
125
- );
126
- }
127
- if (table.columns[index]?.encrypted === true) {
128
- throw new EncryptError(
129
- `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`,
130
- );
131
- }
132
- const selected = values[index];
119
+ // The column must exist, stay plaintext, and hold a non-empty string.
120
+ const selected =
121
+ values[
122
+ table.columns.findIndex(
123
+ (column) => column.name === selectorColumn && column.encrypted !== true,
124
+ )
125
+ ];
133
126
  if (typeof selected !== 'string' || selected.length === 0) {
134
127
  throw new EncryptError(
135
- `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`,
128
+ `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must be a plaintext column holding a non-empty string`,
136
129
  );
137
130
  }
138
131
  return selected;
@@ -29,7 +29,7 @@ import type {
29
29
  import { deleteLocalRow, upsertLocalRow } from './apply';
30
30
 
31
31
  /** Protected failure state. The server base advances independently of intent. */
32
- const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
32
+ const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE rowid=?`;
33
33
 
34
34
  export function ensureFailedOverlaySchema(db: ClientDatabase): void {
35
35
  db.exec(
@@ -44,24 +44,42 @@ export function ensureFailedOverlaySchema(db: ClientDatabase): void {
44
44
  );
45
45
  }
46
46
 
47
+ /**
48
+ * Server writes, after they are stored: each `written` row replaces the base
49
+ * of its key's retained rows (`undefined`: deleted), and the table's retained
50
+ * intents re-read their unique conflicts with the written keys. A written row
51
+ * without a retained row costs no statement.
52
+ */
47
53
  export function retainedBaseWrite(
48
54
  db: ClientDatabase,
49
55
  table: CompiledClientTable,
50
- rowId: string,
51
- values?: Readonly<Record<string, JsonRowValue>>,
52
- version?: number,
56
+ written: ReadonlyMap<
57
+ string,
58
+ readonly [readonly RowValue[], number] | undefined
59
+ >,
53
60
  ): void {
54
- db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE tbl=? AND id=?`, [
55
- values === undefined ? null : JSON.stringify(values),
56
- version ?? null,
57
- table.name,
58
- rowId,
59
- ]);
60
- if (!hasUniqueIndex(table)) return;
61
+ if (!written.size) return;
61
62
  for (const retained of db.query(
62
- `SELECT commit_id,idx,intent,unique_conflicts FROM ${RETAINED_ROWS} WHERE tbl=? AND commit_seq IS NULL`,
63
+ `SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE tbl=?`,
63
64
  [table.name],
64
65
  )) {
66
+ const base = written.get(retained.id as string);
67
+ if (written.has(retained.id as string))
68
+ db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE rowid=?`, [
69
+ base
70
+ ? JSON.stringify(
71
+ Object.fromEntries(
72
+ table.columns.map((column, index) => [
73
+ column.name,
74
+ rowValueToJson(base[0][index] ?? null),
75
+ ]),
76
+ ),
77
+ )
78
+ : null,
79
+ base?.[1] ?? null,
80
+ retained.r as number,
81
+ ]);
82
+ if (!hasUniqueIndex(table) || retained.commit_seq !== null) continue;
65
83
  const prior: readonly (Omit<
66
84
  NonNullable<RetainedCommitRow['uniqueConflicts']>[number],
67
85
  'serverRow'
@@ -69,14 +87,14 @@ export function retainedBaseWrite(
69
87
  retained.unique_conflicts === null
70
88
  ? []
71
89
  : JSON.parse(retained.unique_conflicts as string);
72
- const conflicts = prior.filter((conflict) => conflict.rowId !== rowId);
73
- if (values !== undefined && retained.intent !== null) {
90
+ const conflicts = prior.filter((conflict) => !written.has(conflict.rowId));
91
+ if (retained.intent !== null) {
74
92
  const intent: Record<string, JsonRowValue> = JSON.parse(
75
93
  retained.intent as string,
76
94
  );
77
95
  conflicts.push(
78
96
  ...uniqueConflicts(db, table, mapRowValues(intent, jsonToRowValue))
79
- .filter((conflict) => conflict.rowId === rowId)
97
+ .filter((conflict) => written.has(conflict.rowId))
80
98
  .map((conflict) => ({
81
99
  ...conflict,
82
100
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
@@ -93,8 +111,7 @@ export function retainedBaseWrite(
93
111
  ),
94
112
  )
95
113
  : null,
96
- retained.commit_id as string,
97
- Number(retained.idx),
114
+ retained.r as number,
98
115
  ]);
99
116
  }
100
117
  }
@@ -181,7 +198,7 @@ function retainedRows(
181
198
  // A scope joins through the (tbl, id) index; a scan per applied commit
182
199
  // would make a drained batch quadratic.
183
200
  return db.query(
184
- `SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
201
+ `SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
185
202
  [scope ? JSON.stringify(scope) : null],
186
203
  );
187
204
  }
@@ -190,7 +207,7 @@ export function restoreFailedBases(
190
207
  db: ClientDatabase,
191
208
  schema: CompiledClientSchema,
192
209
  scope?: OverlayScope,
193
- ): boolean {
210
+ ): void {
194
211
  const seen = new Set<string>();
195
212
  for (const row of retainedRows(db, scope)) {
196
213
  const key = JSON.stringify([row.tbl, row.id]);
@@ -211,11 +228,9 @@ export function restoreFailedBases(
211
228
  jsonToRowValue(values[column.name] ?? null),
212
229
  ),
213
230
  (row.version ?? -1) as number,
214
- false,
215
231
  );
216
232
  }
217
233
  }
218
- return seen.size > 0;
219
234
  }
220
235
 
221
236
  export function failedOverlayCommits(
@@ -278,8 +293,7 @@ export function failedOverlayCommits(
278
293
  serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
279
294
  })),
280
295
  ),
281
- row.commit_id as string,
282
- row.idx as number,
296
+ row.r as number,
283
297
  ]);
284
298
  }
285
299
  }
@@ -25,6 +25,7 @@ import {
25
25
  type SnapshotReadRequest,
26
26
  type SyncClient,
27
27
  type SyncClientConfig,
28
+ type SyncIdleOptions,
28
29
  type UnitCatchup,
29
30
  type WindowState,
30
31
  } from './client';
@@ -1087,10 +1088,13 @@ export abstract class NativeBridgeClient implements PromiseMethods<
1087
1088
  return this.command('sync', {});
1088
1089
  }
1089
1090
 
1091
+ /** The Rust core has no §8.4 empty-replica gate: `skipEmpty` is not sent. */
1090
1092
  async syncUntilIdle(
1091
- maxRounds?: number,
1093
+ options?: number | SyncIdleOptions,
1092
1094
  timeoutMs?: number,
1093
1095
  ): Promise<unknown> {
1096
+ const maxRounds = typeof options === 'object' ? options.maxRounds : options;
1097
+ if (typeof options === 'object') timeoutMs = options.timeoutMs;
1094
1098
  return this.command('syncUntilIdle', {
1095
1099
  ...(maxRounds !== undefined ? { maxRounds } : {}),
1096
1100
  ...(timeoutMs !== undefined ? { timeoutMs } : {}),
package/src/outcomes.ts CHANGED
@@ -488,17 +488,13 @@ export function persistCommitOutcomeResolution(
488
488
 
489
489
  /**
490
490
  * Bound journal growth without deleting active failures. If active failures
491
- * alone exceed the cap the journal intentionally remains over-capacity.
491
+ * alone exceed the cap the journal intentionally remains over-capacity. The
492
+ * client constructor validates `maxEntries`.
492
493
  */
493
494
  export function pruneCommitOutcomes(
494
495
  db: ClientDatabase,
495
496
  maxEntries: number,
496
497
  ): number {
497
- if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
498
- throw invalidRequest(
499
- 'outcome retention maxEntries must be a positive safe integer',
500
- );
501
- }
502
498
  const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
503
499
  ?.count as number | undefined;
504
500
  const excess = Math.max(0, (count ?? 0) - maxEntries);
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.
@@ -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 (