@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
package/src/client.ts CHANGED
@@ -111,7 +111,6 @@ import {
111
111
  MAX_DIAGNOSTIC_QUERY_FAILURES,
112
112
  type RealtimePolicy,
113
113
  type RealtimeState,
114
- type TransportCauseKind,
115
114
  } from './diagnostics';
116
115
  import type { EncryptionConfig } from './encryption';
117
116
  import {
@@ -122,6 +121,7 @@ import {
122
121
  REALTIME_LOST_CODE,
123
122
  RealtimeUnavailableError,
124
123
  transportFailed,
124
+ localStateCorrupt,
125
125
  } from './errors';
126
126
  import {
127
127
  ChangeAccumulator,
@@ -189,6 +189,8 @@ import {
189
189
  type RetainedCommitRow,
190
190
  type ResolveCommitOutcomeInput,
191
191
  commitOutcome as readCommitOutcome,
192
+ type PendingDecision,
193
+ pendingDecisions,
192
194
  recordCommitOutcome,
193
195
  scrubPurgedOutcomes,
194
196
  } from './outcomes';
@@ -264,9 +266,11 @@ import {
264
266
  replicaCursor,
265
267
  saveUnit,
266
268
  saveUnitScopeSchema,
269
+ UNITS_TABLE,
267
270
  setMeta,
268
271
  type UnitRecord,
269
272
  unitOwners,
273
+ unitStateCorrupt,
270
274
  } from './state';
271
275
  import type {
272
276
  RealtimeConnector,
@@ -315,6 +319,13 @@ export type {
315
319
  ResolveCommitOutcomeInput,
316
320
  } from './outcomes';
317
321
 
322
+ /** §7.2.2: without `replacement`, the decision keeps the local intent. */
323
+ export interface ReplaceCommitOutcomeInput {
324
+ readonly clientCommitId: string;
325
+ readonly sequence: number;
326
+ readonly replacement?: readonly MutationInput[] | undefined;
327
+ }
328
+
318
329
  export interface SchemaFloor {
319
330
  readonly requiredSchemaVersion?: number;
320
331
  readonly latestSchemaVersion?: number;
@@ -379,7 +390,7 @@ export interface SyncIdleResult extends SyncSummary {
379
390
 
380
391
  export interface SyncIdleOptions {
381
392
  /** §7.8: a strict positive round count. Default: 20. */
382
- readonly maxRounds?: number;
393
+ readonly maxRounds?: number | undefined;
383
394
  /**
384
395
  * Total budget for one drive, across every round, on the client clock. A
385
396
  * drive past it after a completed round resolves with `budgetExhausted`.
@@ -388,6 +399,12 @@ export interface SyncIdleOptions {
388
399
  * `Infinity` disables the bound.
389
400
  */
390
401
  readonly timeoutMs?: number;
402
+ /**
403
+ * §8.4 host policy: end the drive without a round when the replica has no
404
+ * unit, no outbox commit, and no unit list to clear on the server. The
405
+ * shipped host loops pass it; the native bridge ignores it.
406
+ */
407
+ readonly skipEmpty?: boolean;
391
408
  }
392
409
 
393
410
  export type CurrentBaseProof =
@@ -438,6 +455,18 @@ export interface SyncClientLimits {
438
455
  * raises `client.push_request_too_large` and stays queued.
439
456
  */
440
457
  readonly maxPushRequestBytes?: number;
458
+ /**
459
+ * §5.4: rows segment downloads one pull response runs at once. Default 4.
460
+ * SQLite images keep their own bound of two (§5.3).
461
+ */
462
+ readonly segmentPrefetch?: number;
463
+ /**
464
+ * §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
465
+ * exceeds it, unreferenced bodies without pending work are evicted oldest
466
+ * first after each cache write. Referenced bodies stay cached even past the
467
+ * cap. Absent: retain until storage pressure.
468
+ */
469
+ readonly blobCacheMaxBytes?: number;
441
470
  }
442
471
 
443
472
  export interface SyncClientConfig {
@@ -452,14 +481,6 @@ export interface SyncClientConfig {
452
481
  readonly segments?: SegmentDownloader;
453
482
  /** Blob upload/download (§5.9). Required to use `uploadBlob`/`fetchBlob`. */
454
483
  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
484
  readonly realtime?: RealtimeConnector;
464
485
  /**
465
486
  * SPEC §8.8: how sync rounds treat the realtime binding. `optional`
@@ -720,6 +741,7 @@ const ACCEPT_SIGNED_URLS = 1 << 3;
720
741
  * Never a wire code (§10.3) — surfaced through the rejection channel.
721
742
  */
722
743
  const OUTBOX_INCOMPATIBLE_CODE = 'sync.outbox_incompatible';
744
+ const REPLACEMENT_REFUSED_CODE = 'sync.replacement_refused';
723
745
  /** §7.4.4: static text for a persisted commit the current codec refuses. */
724
746
  const LEGACY_VALUE_REFUSAL_MESSAGE =
725
747
  'the persisted commit carries values the current codec refuses';
@@ -731,19 +753,67 @@ const INVALID_STORED_VALUES_REASON = 'invalid_stored_values';
731
753
  * commit order up to this cap and defers the rest to the next round. */
732
754
  const MAX_OPS_PER_REQUEST = 500;
733
755
 
734
- async function sha256Hex(bytes: Uint8Array): Promise<string> {
735
- const digest = await crypto.subtle.digest(
736
- 'SHA-256',
737
- bytes.slice().buffer as ArrayBuffer,
738
- );
739
- return [...new Uint8Array(digest)]
740
- .map((b) => b.toString(16).padStart(2, '0'))
741
- .join('');
742
- }
743
-
744
756
  const invalidHostResponse = (message: string) =>
745
757
  new ClientSyncError('client.invalid_host_response', message);
746
758
 
759
+ /** A field of the structured `details` any thrown value carries. */
760
+ const errorDetail = (error: unknown, key: string): unknown => {
761
+ const details =
762
+ typeof error === 'object' && error !== null && 'details' in error
763
+ ? error.details
764
+ : undefined;
765
+ return typeof details === 'object' && details !== null
766
+ ? (details as Readonly<Record<string, unknown>>)[key]
767
+ : undefined;
768
+ };
769
+
770
+ /** §4.6: the unit state a reset, revocation or rearm starts over from. */
771
+ const UNIT_RESTART = {
772
+ cursor: -1,
773
+ bootstrapState: undefined,
774
+ seeded: [],
775
+ restrict: undefined,
776
+ } as const;
777
+
778
+ /** An overlay row key (`JSON [table,rowId]`). */
779
+ const rowKey = (operation: OutboxOperation) =>
780
+ JSON.stringify([operation.table, operation.rowId]);
781
+
782
+ const unproven = (
783
+ reason: Extract<CurrentBaseProof, { proven: false }>['reason'],
784
+ ): CurrentBaseProof => ({ proven: false, reason });
785
+
786
+ const replacementPending = () =>
787
+ new ClientSyncError(
788
+ 'client.replacement_pending',
789
+ 'the outcome has a pending replacement',
790
+ false,
791
+ );
792
+
793
+ /** §7.2.1: an active failure with a complete retained aggregate. */
794
+ const provable = (
795
+ candidate: CommitOutcome | undefined,
796
+ sequence: number,
797
+ ): candidate is CommitOutcome & {
798
+ readonly operations: readonly OutboxOperation[];
799
+ readonly retainedRows: readonly RetainedCommitRow[];
800
+ } =>
801
+ candidate !== undefined &&
802
+ candidate.sequence === sequence &&
803
+ candidate.resolution === 'active' &&
804
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
805
+ candidate.operations !== undefined &&
806
+ candidate.retainedRows !== undefined &&
807
+ candidate.operations.length === candidate.retainedRows.length &&
808
+ candidate.retainedRows.length > 0;
809
+
810
+ interface DriveStart {
811
+ readonly before: readonly UnitRecord[];
812
+ readonly epoch: number;
813
+ readonly registrationEpoch: number;
814
+ readonly securityEpoch: number;
815
+ }
816
+
747
817
  const outcomeNotFound = () =>
748
818
  new ClientSyncError(
749
819
  'sync.outcome_not_found',
@@ -890,8 +960,8 @@ function isFinalPushResult(frame: PushResultFrame): boolean {
890
960
  );
891
961
  }
892
962
 
893
- /** The stable `code` of a thrown realtime transport error, when it has one. */
894
- function realtimeErrorCode(error: unknown): string | undefined {
963
+ /** The stable `code` a thrown value carries, when it has one. */
964
+ function thrownCode(error: unknown): string | undefined {
895
965
  const code = (error as { code?: unknown } | undefined)?.code;
896
966
  return typeof code === 'string' ? code : undefined;
897
967
  }
@@ -908,6 +978,7 @@ export type ClientSnapshotMethods = Pick<
908
978
  | 'commitOutcome'
909
979
  | 'commitOutcomes'
910
980
  | 'resolveCommitOutcome'
981
+ | 'commitDelivery'
911
982
  >;
912
983
 
913
984
  /** Project a method contract across an asynchronous host boundary. */
@@ -928,6 +999,15 @@ export type ClientSnapshotReader = {
928
999
  | Promise<ReturnType<ClientSnapshotMethods[Key]>>;
929
1000
  };
930
1001
 
1002
+ /** Encodes a request in the current wire version. */
1003
+ function encodeRequestFrames(frames: RequestFrame[]): Uint8Array {
1004
+ return encodeRequest({
1005
+ wireVersion: PROTOCOL_WIRE_VERSION,
1006
+ msgKind: 'request',
1007
+ frames,
1008
+ });
1009
+ }
1010
+
931
1011
  /** §7.7: progress fields of a payload; no payload is current. */
932
1012
  const NO_PAYLOAD: Partial<SyncProgress> = {
933
1013
  table: undefined,
@@ -1080,21 +1160,19 @@ export class SyncClient {
1080
1160
  throw invalidRequest('transportEnabled must be a boolean');
1081
1161
  }
1082
1162
  this.#transportEnabled = config.transportEnabled !== false;
1083
- for (const [name, value] of [
1084
- ['maxPushCommitsPerRequest', config.limits?.maxPushCommitsPerRequest],
1085
- [
1086
- 'maxPushOperationsPerRequest',
1087
- config.limits?.maxPushOperationsPerRequest,
1088
- ],
1089
- ['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
1163
+ for (const name of [
1164
+ 'maxPushCommitsPerRequest',
1165
+ 'maxPushOperationsPerRequest',
1166
+ 'maxPushRequestBytes',
1167
+ 'segmentPrefetch',
1090
1168
  ] as const) {
1169
+ const value = config.limits?.[name];
1091
1170
  if (
1092
1171
  value !== undefined &&
1093
1172
  (!Number.isInteger(value) || value < 1 || value > 0xffffffff)
1094
1173
  ) {
1095
- throw new ClientSyncError(
1096
- 'sync.invalid_request',
1097
- 'push limit must be an integer in 1..=4294967295',
1174
+ throw invalidRequest(
1175
+ 'limit must be an integer in 1..=4294967295',
1098
1176
  false,
1099
1177
  { limit: name },
1100
1178
  );
@@ -1204,39 +1282,35 @@ export class SyncClient {
1204
1282
  "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
1205
1283
  )[0];
1206
1284
  if (meta !== undefined) {
1207
- if (meta.type !== 'table')
1208
- throw new Error('invalid metadata table');
1209
- const rows = this.#db.query(
1210
- 'SELECT value FROM _syncular_meta WHERE key = ?',
1211
- [LOCAL_SCHEMA_VERSION_KEY],
1212
- );
1213
- // A duplicated marker cannot be resolved. Picking one row could
1214
- // select an older version and drive a destructive reset over a
1215
- // newer replica.
1216
- if (rows.length > 1) throw new Error('invalid schema marker');
1217
- const row = rows[0];
1285
+ const rows =
1286
+ meta.type === 'table'
1287
+ ? this.#db.query(
1288
+ 'SELECT value FROM _syncular_meta WHERE key = ?',
1289
+ [LOCAL_SCHEMA_VERSION_KEY],
1290
+ )
1291
+ : undefined;
1292
+ const value = rows?.[0]?.value;
1293
+ const version = Number(value);
1294
+ // The catch below turns each refusal into `sync.local_corrupt`.
1218
1295
  if (
1219
- row === undefined &&
1220
- this.#db.query(
1221
- "SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1",
1222
- ).length > 0
1223
- ) {
1224
- throw new Error('missing paired schema marker');
1225
- }
1226
- if (row !== undefined) {
1227
- const value = row.value;
1228
- const version = Number(value);
1229
- if (
1230
- typeof value !== 'string' ||
1231
- !Number.isInteger(version) ||
1232
- version < 1 ||
1233
- version > 2147483647 ||
1234
- String(version) !== value
1235
- ) {
1236
- throw new Error('invalid schema marker');
1237
- }
1238
- marker = version;
1239
- }
1296
+ rows === undefined ||
1297
+ // A duplicated marker cannot be resolved. Picking one row could
1298
+ // select an older version and drive a destructive reset over a
1299
+ // newer replica.
1300
+ rows.length > 1 ||
1301
+ (value === undefined
1302
+ ? // A descriptor without its paired marker.
1303
+ this.#db.query(
1304
+ "SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1",
1305
+ ).length > 0
1306
+ : typeof value !== 'string' ||
1307
+ !Number.isInteger(version) ||
1308
+ version < 1 ||
1309
+ version > 2147483647 ||
1310
+ String(version) !== value)
1311
+ )
1312
+ throw new Error('invalid schema marker');
1313
+ if (value !== undefined) marker = version;
1240
1314
  }
1241
1315
  } catch (error) {
1242
1316
  // A recognized SQLite storage failure (including BUSY/LOCKED
@@ -1244,8 +1318,7 @@ export class SyncClient {
1244
1318
  // or otherwise unreadable marker is `sync.local_corrupt`.
1245
1319
  const failure = classifySqliteFailure(error);
1246
1320
  if (failure.code !== undefined) throw failure.error;
1247
- throw new ClientSyncError(
1248
- 'sync.local_corrupt',
1321
+ throw localStateCorrupt(
1249
1322
  'persisted local schema marker is unreadable or invalid',
1250
1323
  );
1251
1324
  }
@@ -1328,7 +1401,6 @@ export class SyncClient {
1328
1401
  if (this.#securityLifecycle === 'active' && this.#hasStartupWork()) {
1329
1402
  this.#needsPull = true;
1330
1403
  this.#emitSyncNeeded('startup');
1331
- this.#emitSyncIntent({ kind: 'interactive' });
1332
1404
  }
1333
1405
  // Console introspection is a no-op outside a dev page.
1334
1406
  this.#devtoolsUnregister = this.#config.devtools?.({
@@ -1356,32 +1428,23 @@ export class SyncClient {
1356
1428
  * marker, so the shape chosen here commits under that snapshot.
1357
1429
  */
1358
1430
  #detectAndResetSchema(marker: number | undefined): void {
1359
- if (marker === undefined) {
1360
- // Fresh install: the tables just created match the running code.
1361
- this.#db.transaction(() => {
1362
- ensureLocalSyncedSchema(this.#db, this.#schema);
1431
+ if (marker !== undefined && marker !== this.#schema.version)
1432
+ return this.#runSchemaReset();
1433
+ // A fresh install's tables just created match the running code. Same-version
1434
+ // opens remain self-healing for absent tables/indexes, and RFC 0005 D1
1435
+ // backfills the descriptor for a database first opened by 0.22.0 or
1436
+ // earlier WITHOUT a schema bump.
1437
+ this.#db.transaction(() => {
1438
+ ensureLocalSyncedSchema(this.#db, this.#schema);
1439
+ if (marker === undefined)
1363
1440
  setMeta(
1364
1441
  this.#db,
1365
1442
  LOCAL_SCHEMA_VERSION_KEY,
1366
1443
  String(this.#schema.version),
1367
1444
  );
1368
- setLocalSchemaDescriptor(this.#db, this.#schema);
1369
- saveUnitScopeSchema(this.#db, this.#schema);
1370
- });
1371
- return;
1372
- }
1373
- if (marker === this.#schema.version) {
1374
- // Same-version opens remain self-healing for absent tables/indexes, and
1375
- // RFC 0005 D1 backfills the descriptor for a database first opened by
1376
- // 0.22.0 or earlier WITHOUT a schema bump.
1377
- this.#db.transaction(() => {
1378
- ensureLocalSyncedSchema(this.#db, this.#schema);
1379
- setLocalSchemaDescriptor(this.#db, this.#schema);
1380
- saveUnitScopeSchema(this.#db, this.#schema);
1381
- });
1382
- return;
1383
- }
1384
- this.#runSchemaReset();
1445
+ setLocalSchemaDescriptor(this.#db, this.#schema);
1446
+ saveUnitScopeSchema(this.#db, this.#schema);
1447
+ });
1385
1448
  }
1386
1449
 
1387
1450
  /**
@@ -1512,9 +1575,7 @@ export class SyncClient {
1512
1575
  #runLogEpochReset(logEpoch: string): string[] {
1513
1576
  if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
1514
1577
  this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
1515
- this.#setSyncNeeded(true);
1516
1578
  this.#emitSyncNeeded('startup');
1517
- this.#emitSyncIntent({ kind: 'interactive' });
1518
1579
  return [];
1519
1580
  }
1520
1581
  const units = loadUnits(this.#db);
@@ -1548,9 +1609,7 @@ export class SyncClient {
1548
1609
  },
1549
1610
  );
1550
1611
  this.#localResetEpoch += 1;
1551
- this.#setSyncNeeded(true);
1552
1612
  this.#emitSyncNeeded('startup');
1553
- this.#emitSyncIntent({ kind: 'interactive' });
1554
1613
  return units.map((unit) => unit.id);
1555
1614
  }
1556
1615
 
@@ -1594,32 +1653,32 @@ export class SyncClient {
1594
1653
  this.#syncIntentListeners.clear();
1595
1654
  }
1596
1655
 
1656
+ /** Mark a pull as needed and tell the host; a startup wake also asks for
1657
+ * an interactive round. */
1597
1658
  #emitSyncNeeded(reason: 'startup' | 'hello' | WakeReason): void {
1659
+ this.#setSyncNeeded(true);
1598
1660
  if (!this.#transportEnabled) return;
1599
- try {
1600
- this.#config.onSyncNeeded?.(reason);
1601
- } catch {
1602
- // An observer cannot alter sync correctness.
1603
- }
1604
- for (const listener of this.#syncNeededListeners) {
1661
+ for (const listener of [
1662
+ this.#config.onSyncNeeded,
1663
+ ...this.#syncNeededListeners,
1664
+ ]) {
1605
1665
  try {
1606
- listener(reason);
1666
+ listener?.(reason);
1607
1667
  } catch {
1608
1668
  // An observer cannot alter sync correctness.
1609
1669
  }
1610
1670
  }
1671
+ if (reason === 'startup') this.#emitSyncIntent({ kind: 'interactive' });
1611
1672
  }
1612
1673
 
1613
1674
  #emitSyncIntent(intent: SyncIntent): void {
1614
1675
  if (!this.#transportEnabled && intent.kind !== 'none') return;
1615
- try {
1616
- this.#config.onSyncIntent?.(intent);
1617
- } catch {
1618
- // An observer cannot alter sync correctness.
1619
- }
1620
- for (const listener of this.#syncIntentListeners) {
1676
+ for (const listener of [
1677
+ this.#config.onSyncIntent,
1678
+ ...this.#syncIntentListeners,
1679
+ ]) {
1621
1680
  try {
1622
- listener(intent);
1681
+ listener?.(intent);
1623
1682
  } catch {
1624
1683
  // An observer cannot alter sync correctness.
1625
1684
  }
@@ -1676,16 +1735,11 @@ export class SyncClient {
1676
1735
  this.#syncOutstanding = false;
1677
1736
  })();
1678
1737
  this.#preflightBarrier = barrier;
1679
- void barrier.then(
1680
- () => {
1681
- if (this.#preflightBarrier === barrier)
1682
- this.#preflightBarrier = undefined;
1683
- },
1684
- () => {
1685
- if (this.#preflightBarrier === barrier)
1686
- this.#preflightBarrier = undefined;
1687
- },
1688
- );
1738
+ const release = () => {
1739
+ if (this.#preflightBarrier === barrier)
1740
+ this.#preflightBarrier = undefined;
1741
+ };
1742
+ void barrier.then(release, release);
1689
1743
  return barrier;
1690
1744
  }
1691
1745
 
@@ -1711,9 +1765,7 @@ export class SyncClient {
1711
1765
  });
1712
1766
  await this.#serialize(() => this.#revealSealed());
1713
1767
  if (this.#hasStartupWork()) {
1714
- this.#setSyncNeeded(true);
1715
1768
  this.#emitSyncNeeded('startup');
1716
- this.#emitSyncIntent({ kind: 'interactive' });
1717
1769
  }
1718
1770
  }
1719
1771
 
@@ -1862,11 +1914,7 @@ export class SyncClient {
1862
1914
  const unit = getUnit(this.#db, id);
1863
1915
  if (unit === undefined) return { state: 'unknown', id };
1864
1916
  const cursor = unit.cursor ?? replicaCursor(this.#db);
1865
- if (!Number.isSafeInteger(cursor))
1866
- throw new ClientSyncError(
1867
- 'sync.local_corrupt',
1868
- 'persisted unit state is invalid',
1869
- );
1917
+ if (!Number.isSafeInteger(cursor)) throw unitStateCorrupt();
1870
1918
  const active = unit.status === 'active';
1871
1919
  const pending = bootstrapping(unit);
1872
1920
  return definedObject({
@@ -1982,45 +2030,32 @@ export class SyncClient {
1982
2030
  return this.#previousVersionUnavailable(currentVersion, 'not-configured');
1983
2031
  }
1984
2032
  const record = this.#readPreviousVersionRecord();
1985
- const nowMs = this.#now();
1986
- if (this.#previousVersionLeaseInactive(nowMs)) {
1987
- this.#discardPreviousVersion();
1988
- return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1989
- }
1990
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1991
- this.#discardPreviousVersion();
1992
- return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1993
- }
1994
2033
  // Coverage completion is a live predicate: the container is normally
1995
2034
  // dropped by the sync path first, so a read can be the first observer.
1996
- if (this.#previousVersionCoverageComplete()) {
2035
+ const nowMs = this.#now();
2036
+ const ended = this.#previousVersionLeaseInactive(nowMs)
2037
+ ? 'lease-inactive'
2038
+ : loadUnits(this.#db).some((unit) => unit.status === 'revoked')
2039
+ ? 'scope-revoked'
2040
+ : this.#previousVersionCoverageComplete()
2041
+ ? 'coverage-complete'
2042
+ : record === undefined
2043
+ ? undefined
2044
+ : record.currentVersion !== currentVersion
2045
+ ? 'no-previous-descriptor'
2046
+ : this.#previousVersionExpired(record, nowMs)
2047
+ ? 'expired'
2048
+ : undefined;
2049
+ if (ended !== undefined) {
1997
2050
  this.#discardPreviousVersion();
1998
- return this.#previousVersionUnavailable(
1999
- currentVersion,
2000
- 'coverage-complete',
2001
- );
2051
+ return this.#previousVersionUnavailable(currentVersion, ended);
2002
2052
  }
2003
- if (record === undefined) {
2004
- const refusal = storedPreviousVersionRefusal(this.#db);
2053
+ if (record === undefined)
2005
2054
  return this.#previousVersionUnavailable(
2006
2055
  currentVersion,
2007
- refusal?.reason ?? 'no-previous-descriptor',
2056
+ storedPreviousVersionRefusal(this.#db)?.reason ??
2057
+ 'no-previous-descriptor',
2008
2058
  );
2009
- }
2010
- if (record.currentVersion !== currentVersion) {
2011
- this.#discardPreviousVersion();
2012
- return this.#previousVersionUnavailable(
2013
- currentVersion,
2014
- 'no-previous-descriptor',
2015
- );
2016
- }
2017
- if (
2018
- nowMs - record.createdAtMs >
2019
- previousVersionMaxAgeMs(this.#config.previousVersionContext)
2020
- ) {
2021
- this.#discardPreviousVersion();
2022
- return this.#previousVersionUnavailable(currentVersion, 'expired');
2023
- }
2024
2059
  const table = record.tables.find((entry) => entry.name === spec.table);
2025
2060
  if (table === undefined) {
2026
2061
  throw invalidRequest(
@@ -2152,21 +2187,24 @@ export class SyncClient {
2152
2187
  return;
2153
2188
  }
2154
2189
  const record = this.#readPreviousVersionRecord();
2155
- if (record === undefined) return;
2156
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
2157
- this.#discardPreviousVersion();
2158
- return;
2159
- }
2160
2190
  if (
2191
+ record !== undefined &&
2192
+ (loadUnits(this.#db).some((unit) => unit.status === 'revoked') ||
2193
+ this.#previousVersionExpired(record, nowMs) ||
2194
+ this.#previousVersionCoverageComplete())
2195
+ )
2196
+ this.#discardPreviousVersion();
2197
+ }
2198
+
2199
+ /** RFC 0005 D7: the container outlived `previousVersionContext.maxAgeMs`. */
2200
+ #previousVersionExpired(
2201
+ record: PreviousVersionRecord,
2202
+ nowMs = this.#now(),
2203
+ ): boolean {
2204
+ return (
2161
2205
  nowMs - record.createdAtMs >
2162
2206
  previousVersionMaxAgeMs(this.#config.previousVersionContext)
2163
- ) {
2164
- this.#discardPreviousVersion();
2165
- return;
2166
- }
2167
- if (this.#previousVersionCoverageComplete()) {
2168
- this.#discardPreviousVersion();
2169
- }
2207
+ );
2170
2208
  }
2171
2209
 
2172
2210
  /**
@@ -2177,18 +2215,13 @@ export class SyncClient {
2177
2215
  #reconcilePreviousVersionAtBoot(): void {
2178
2216
  if (!this.#previousVersionExists()) return;
2179
2217
  const record = this.#readPreviousVersionRecord();
2180
- let discard =
2181
- record === undefined || record.currentVersion !== this.#schema.version;
2182
2218
  if (
2183
- !discard &&
2184
- record !== undefined &&
2185
- this.#previousVersion !== undefined &&
2186
- this.#now() - record.createdAtMs >
2187
- previousVersionMaxAgeMs(this.#config.previousVersionContext)
2188
- ) {
2189
- discard = true;
2190
- }
2191
- if (discard) this.#dropPreviousVersion();
2219
+ record === undefined ||
2220
+ record.currentVersion !== this.#schema.version ||
2221
+ (this.#previousVersion !== undefined &&
2222
+ this.#previousVersionExpired(record))
2223
+ )
2224
+ this.#dropPreviousVersion();
2192
2225
  }
2193
2226
 
2194
2227
  // -- live-query invalidation ----------------------------------------------
@@ -2365,15 +2398,15 @@ export class SyncClient {
2365
2398
  )
2366
2399
  : 0;
2367
2400
  const pressure =
2368
- this.#config.blobCacheMaxBytes !== undefined &&
2369
- blobBytes > this.#config.blobCacheMaxBytes;
2401
+ blobBytes > (this.#config.limits?.blobCacheMaxBytes ?? Infinity);
2402
+ const size = (value: unknown) => Math.max(0, Number(value ?? 0));
2370
2403
  return {
2371
2404
  status: pressure ? 'pressure' : 'healthy',
2372
2405
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
2373
- pendingOutboxBytesApprox: Math.max(0, Number(sums?.outbox ?? 0)),
2374
- retainedOutcomeBytesApprox: Math.max(0, Number(sums?.bytes ?? 0)),
2375
- retainedOutcomeEntries: Math.max(0, Number(sums?.entries ?? 0)),
2376
- blobCacheBytesApprox: Math.max(0, blobBytes),
2406
+ pendingOutboxBytesApprox: size(sums?.outbox),
2407
+ retainedOutcomeBytesApprox: size(sums?.bytes),
2408
+ retainedOutcomeEntries: size(sums?.entries),
2409
+ blobCacheBytesApprox: size(blobBytes),
2377
2410
  ...(pressure
2378
2411
  ? { pressureReasonCode: 'client.blob_cache_over_limit' as const }
2379
2412
  : {}),
@@ -2647,7 +2680,7 @@ export class SyncClient {
2647
2680
 
2648
2681
  /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
2649
2682
  #enforceBlobCacheCap(): void {
2650
- const cap = this.#config.blobCacheMaxBytes;
2683
+ const cap = this.#config.limits?.blobCacheMaxBytes;
2651
2684
  if (cap === undefined) return;
2652
2685
  enforceBlobCacheCap(this.#db, this.#schema, cap);
2653
2686
  }
@@ -2680,8 +2713,7 @@ export class SyncClient {
2680
2713
  cached.byteLength !== cached.bytes.byteLength ||
2681
2714
  (await computeBlobId(cached.bytes)) !== pending.blobId
2682
2715
  ) {
2683
- throw new ClientSyncError(
2684
- 'sync.local_corrupt',
2716
+ throw localStateCorrupt(
2685
2717
  'Pending blob upload body is missing or corrupt',
2686
2718
  );
2687
2719
  }
@@ -2802,67 +2834,68 @@ export class SyncClient {
2802
2834
  ): Promise<CurrentBaseProof> {
2803
2835
  this.#requireActive();
2804
2836
  requireRoundBudget(maxRounds);
2805
- const { clientCommitId, sequence } = outcome;
2806
- const provable = (
2807
- candidate: CommitOutcome | undefined,
2808
- ): candidate is CommitOutcome & {
2809
- readonly retainedRows: readonly RetainedCommitRow[];
2810
- } =>
2811
- candidate !== undefined &&
2812
- candidate.sequence === sequence &&
2813
- candidate.resolution === 'active' &&
2814
- (candidate.status === 'conflict' || candidate.status === 'rejected') &&
2815
- candidate.operations !== undefined &&
2816
- candidate.retainedRows !== undefined &&
2817
- candidate.operations.length === candidate.retainedRows.length &&
2818
- candidate.retainedRows.length > 0;
2819
2837
  let initial: CommitOutcome | undefined;
2820
2838
  try {
2821
- initial = readCommitOutcome(this.#db, clientCommitId);
2839
+ initial = readCommitOutcome(this.#db, outcome.clientCommitId);
2822
2840
  } catch {
2823
- return { proven: false, reason: 'snapshot_failed' };
2841
+ return unproven('snapshot_failed');
2824
2842
  }
2825
- if (!provable(initial))
2826
- return { proven: false, reason: 'outcome_unavailable' };
2827
- if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2843
+ if (!provable(initial, outcome.sequence))
2844
+ return unproven('outcome_unavailable');
2845
+ if (!this.#transportEnabled) return unproven('offline');
2828
2846
  await this.#opChain;
2829
- if (!this.#transportEnabled) return { proven: false, reason: 'offline' };
2830
- const epoch = this.#transportEpoch;
2831
- const registrationEpoch = this.#registrationEpoch;
2832
- const securityEpoch = this.#securityEpoch;
2833
- let before: UnitRecord[];
2847
+ if (!this.#transportEnabled) return unproven('offline');
2848
+ let start: DriveStart;
2834
2849
  try {
2835
- before = loadUnits(this.#db);
2850
+ start = this.#driveStart();
2836
2851
  } catch {
2837
- return { proven: false, reason: 'snapshot_failed' };
2852
+ return unproven('snapshot_failed');
2838
2853
  }
2839
2854
  let report: SyncIdleResult;
2840
2855
  try {
2841
2856
  report = await this.syncUntilIdle(maxRounds);
2842
2857
  } catch {
2843
- return {
2844
- proven: false,
2845
- reason:
2846
- !this.#transportEnabled || epoch !== this.#transportEpoch
2847
- ? 'offline'
2848
- : registrationEpoch !== this.#registrationEpoch
2849
- ? 'missing_coverage'
2850
- : 'sync_failed',
2851
- };
2858
+ return unproven(
2859
+ !this.#transportEnabled || start.epoch !== this.#transportEpoch
2860
+ ? 'offline'
2861
+ : start.registrationEpoch !== this.#registrationEpoch
2862
+ ? 'missing_coverage'
2863
+ : 'sync_failed',
2864
+ );
2852
2865
  }
2866
+ return this.#provenBase(outcome, start, report);
2867
+ }
2868
+
2869
+ /** The drive state a §7.2.1 proof compares against after the drive. */
2870
+ #driveStart(): DriveStart {
2871
+ return {
2872
+ before: loadUnits(this.#db),
2873
+ epoch: this.#transportEpoch,
2874
+ registrationEpoch: this.#registrationEpoch,
2875
+ securityEpoch: this.#securityEpoch,
2876
+ };
2877
+ }
2878
+
2879
+ /** §7.2.1: the proof after a completed drive that began at `start`. */
2880
+ #provenBase(
2881
+ {
2882
+ clientCommitId,
2883
+ sequence,
2884
+ }: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>,
2885
+ { before, epoch, registrationEpoch, securityEpoch }: DriveStart,
2886
+ report: SyncIdleResult,
2887
+ ): CurrentBaseProof {
2853
2888
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
2854
- return { proven: false, reason: 'offline' };
2889
+ return unproven('offline');
2855
2890
  if (registrationEpoch !== this.#registrationEpoch)
2856
- return { proven: false, reason: 'missing_coverage' };
2891
+ return unproven('missing_coverage');
2857
2892
  if (
2858
2893
  this.#securityLifecycle !== 'active' ||
2859
2894
  securityEpoch !== this.#securityEpoch
2860
2895
  )
2861
- return { proven: false, reason: 'sync_failed' };
2862
- if (report.schemaFloor !== undefined)
2863
- return { proven: false, reason: 'schema_floor' };
2864
- if (report.budgetExhausted)
2865
- return { proven: false, reason: 'budget_exhausted' };
2896
+ return unproven('sync_failed');
2897
+ if (report.schemaFloor !== undefined) return unproven('schema_floor');
2898
+ if (report.budgetExhausted) return unproven('budget_exhausted');
2866
2899
  try {
2867
2900
  return this.#db.transaction(() => {
2868
2901
  const snapshot = this.#readSnapshot({
@@ -2872,12 +2905,10 @@ export class SyncClient {
2872
2905
  });
2873
2906
  const delivery = snapshot.deliveries[0];
2874
2907
  const current = readCommitOutcome(this.#db, clientCommitId);
2875
- if (delivery?.status !== 'known' || !provable(current))
2876
- return {
2877
- proven: false,
2878
- reason:
2879
- report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
2880
- };
2908
+ if (delivery?.status !== 'known' || !provable(current, sequence))
2909
+ return unproven(
2910
+ report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
2911
+ );
2881
2912
  const after = new Map(
2882
2913
  loadUnits(this.#db).map((unit) => [unit.id, unit]),
2883
2914
  );
@@ -2932,17 +2963,15 @@ export class SyncClient {
2932
2963
  (conflict) => !covered(row.table, conflict.serverRow),
2933
2964
  )
2934
2965
  ) {
2935
- return {
2936
- proven: false,
2937
- reason:
2938
- report.revoked.length > 0 ? 'revoked' : 'missing_coverage',
2939
- };
2966
+ return unproven(
2967
+ report.revoked.length > 0 ? 'revoked' : 'missing_coverage',
2968
+ );
2940
2969
  }
2941
2970
  }
2942
2971
  return { proven: true, rows: current.retainedRows };
2943
2972
  });
2944
2973
  } catch {
2945
- return { proven: false, reason: 'snapshot_failed' };
2974
+ return unproven('snapshot_failed');
2946
2975
  }
2947
2976
  }
2948
2977
 
@@ -2965,6 +2994,8 @@ export class SyncClient {
2965
2994
  throw outcomeNotFound();
2966
2995
  }
2967
2996
  if (current.resolution !== 'active') return current;
2997
+ if (current.replacementClientCommitId !== undefined)
2998
+ throw replacementPending();
2968
2999
  const replacement = input.replacementClientCommitId;
2969
3000
  if (input.resolution === 'superseded') {
2970
3001
  if (
@@ -2993,11 +3024,157 @@ export class SyncClient {
2993
3024
  );
2994
3025
  }
2995
3026
 
3027
+ return this.#resolveOutcome(input, current);
3028
+ }
3029
+
3030
+ /**
3031
+ * §7.2.2: record a decision against an active failure as a held
3032
+ * replacement commit, written once a later drive proves its base.
3033
+ */
3034
+ replaceCommitOutcome(input: ReplaceCommitOutcomeInput): string {
3035
+ this.#requireActive();
3036
+ const current = readCommitOutcome(this.#db, input.clientCommitId);
3037
+ if (current === undefined) throw outcomeNotFound();
3038
+ if (
3039
+ current.resolution === 'active' &&
3040
+ current.replacementClientCommitId !== undefined
3041
+ )
3042
+ throw replacementPending();
3043
+ if (!provable(current, input.sequence))
3044
+ throw invalidRequest('the outcome holds no complete retained aggregate');
3045
+ // Envelope operation i belongs to retained row i, so keep mine finds
3046
+ // every operation's row; a payload names no version for one.
3047
+ const operations = (
3048
+ input.replacement === undefined
3049
+ ? current.operations
3050
+ : this.#outboxOperations(input.replacement)
3051
+ ).map((operation) => {
3052
+ const row = current.retainedRows.find(
3053
+ (candidate) =>
3054
+ candidate.table === operation.table &&
3055
+ candidate.rowId === operation.rowId,
3056
+ );
3057
+ if (row === undefined) return operation;
3058
+ if (
3059
+ input.replacement !== undefined &&
3060
+ operation.baseVersion !== undefined
3061
+ )
3062
+ throw invalidRequest(
3063
+ 'a replacement takes the base version of a retained row',
3064
+ );
3065
+ return { ...operation, baseVersion: row.serverVersion ?? 0 };
3066
+ });
3067
+ const clientCommitId = crypto.randomUUID();
3068
+ this.#appendCommit(clientCommitId, operations, (batch) => {
3069
+ this.#db.exec(
3070
+ `UPDATE ${OUTCOMES_TABLE} SET replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'`,
3071
+ [clientCommitId, input.clientCommitId],
3072
+ );
3073
+ batch.outcomes();
3074
+ });
3075
+ return clientCommitId;
3076
+ }
3077
+
3078
+ /**
3079
+ * §7.2.2: at the idle point of a drive, write or refuse each decision that
3080
+ * was pending when the drive began. True when a replacement was written.
3081
+ */
3082
+ #settleDecisions(
3083
+ decisions: readonly PendingDecision[],
3084
+ start: DriveStart,
3085
+ report: SyncIdleResult,
3086
+ ): boolean {
3087
+ // A registration change during the drive says nothing about the base;
3088
+ // the decisions wait for the next drive.
3089
+ if (start.registrationEpoch !== this.#registrationEpoch) return false;
3090
+ let written = false;
3091
+ for (const decision of decisions) {
3092
+ const current = readCommitOutcome(this.#db, decision.clientCommitId);
3093
+ if (
3094
+ current?.resolution !== 'active' ||
3095
+ current.replacementClientCommitId !== decision.replacementClientCommitId
3096
+ )
3097
+ continue;
3098
+ // A replacement that already left the outbox has its own outcome.
3099
+ const commit = listOutbox(this.#db).find(
3100
+ (candidate) =>
3101
+ candidate.clientCommitId === decision.replacementClientCommitId,
3102
+ );
3103
+ const proof = commit && this.#provenBase(decision, start, report);
3104
+ const reason = !proof
3105
+ ? undefined
3106
+ : !proof.proven
3107
+ ? proof.reason
3108
+ : commit.operations.every((operation) => {
3109
+ const row = proof.rows.find(
3110
+ (candidate) =>
3111
+ candidate.table === operation.table &&
3112
+ candidate.rowId === operation.rowId,
3113
+ );
3114
+ return (
3115
+ row === undefined ||
3116
+ operation.baseVersion === (row.serverVersion ?? 0)
3117
+ );
3118
+ })
3119
+ ? undefined
3120
+ : 'base_moved';
3121
+ // These proof failures say nothing about the base; the next drive retries.
3122
+ if (
3123
+ /^(offline|sync_failed|budget_exhausted|snapshot_failed)$/.test(reason!)
3124
+ )
3125
+ continue;
3126
+ written ||= reason === undefined && commit !== undefined;
3127
+ this.#resolveOutcome(
3128
+ {
3129
+ clientCommitId: decision.clientCommitId,
3130
+ resolution: 'superseded',
3131
+ replacementClientCommitId: decision.replacementClientCommitId,
3132
+ },
3133
+ current,
3134
+ () =>
3135
+ reason !== undefined &&
3136
+ this.#dropIncompatibleCommit(
3137
+ commit!,
3138
+ 'the replacement could not be written on a proven base',
3139
+ REPLACEMENT_REFUSED_CODE,
3140
+ true,
3141
+ reason,
3142
+ ),
3143
+ );
3144
+ }
3145
+ return written;
3146
+ }
3147
+
3148
+ #resolveOutcome(
3149
+ input: ResolveCommitOutcomeInput,
3150
+ current: CommitOutcome,
3151
+ within?: () => void,
3152
+ ): CommitOutcome {
2996
3153
  const priorConflicts = this.#conflicts;
2997
3154
  const priorRejections = this.#rejections;
2998
3155
  return this.#applyBatch(
2999
3156
  (batch) => {
3000
- restoreFailedBases(this.#db, this.#schema);
3157
+ // Restore the server base under the retained rows, then replay what
3158
+ // stays and re-take later commits' before-images over that base, so
3159
+ // a later rollback cannot bring the released intent back.
3160
+ const scope = [
3161
+ ...new Set(
3162
+ this.#db
3163
+ .query(`SELECT tbl,id FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
3164
+ input.clientCommitId,
3165
+ ])
3166
+ .flatMap((row) => {
3167
+ const table = this.#schema.tables.get(String(row.tbl));
3168
+ return [
3169
+ ...(table !== undefined && hasUniqueIndex(table)
3170
+ ? [JSON.stringify([row.tbl])]
3171
+ : []),
3172
+ JSON.stringify([row.tbl, row.id]),
3173
+ ];
3174
+ }),
3175
+ ),
3176
+ ];
3177
+ restoreFailedBases(this.#db, this.#schema, scope);
3001
3178
  this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
3002
3179
  input.clientCommitId,
3003
3180
  ]);
@@ -3016,12 +3193,13 @@ export class SyncClient {
3016
3193
  (record) => record.clientCommitId !== input.clientCommitId,
3017
3194
  );
3018
3195
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
3019
- this.#replayOutbox();
3196
+ this.#replayOutbox(scope, false);
3020
3197
  for (const operation of current.operations ?? [])
3021
3198
  batch.table(operation.table);
3022
3199
  batch.outcomes();
3023
3200
  if (current.status === 'conflict') batch.conflicts();
3024
3201
  if (current.status === 'rejected') batch.rejections();
3202
+ within?.();
3025
3203
  return resolved;
3026
3204
  },
3027
3205
  undefined,
@@ -3158,9 +3336,7 @@ export class SyncClient {
3158
3336
  );
3159
3337
  if (registered) {
3160
3338
  this.#registrationEpoch += 1;
3161
- this.#setSyncNeeded(true);
3162
- this.#emitSyncIntent({ kind: 'interactive' });
3163
- this.#emitDiagnostics();
3339
+ this.#registrationChanged();
3164
3340
  }
3165
3341
  return ids;
3166
3342
  }
@@ -3179,7 +3355,11 @@ export class SyncClient {
3179
3355
  }
3180
3356
  deleteUnit(this.#db, id);
3181
3357
  this.#registrationEpoch += 1;
3182
- if (unit.status !== 'active') return;
3358
+ if (unit.status === 'active') this.#registrationChanged();
3359
+ }
3360
+
3361
+ /** A registration change owes an interactive pull. */
3362
+ #registrationChanged(): void {
3183
3363
  this.#setSyncNeeded(true);
3184
3364
  this.#emitSyncIntent({ kind: 'interactive' });
3185
3365
  this.#emitDiagnostics();
@@ -3458,6 +3638,12 @@ export class SyncClient {
3458
3638
  { clientCommitId: supplied },
3459
3639
  );
3460
3640
  const clientCommitId = supplied ?? crypto.randomUUID();
3641
+ this.#appendCommit(clientCommitId, this.#outboxOperations(mutations));
3642
+ return clientCommitId;
3643
+ }
3644
+
3645
+ /** §7.1: validate local mutations into their stored outbox operations. */
3646
+ #outboxOperations(mutations: readonly MutationInput[]): OutboxOperation[] {
3461
3647
  // §7.1: a patch reads the row as the commit's earlier operations leave
3462
3648
  // it. Keyed by `table rowId` (a table name holds no space): the JSON
3463
3649
  // values an earlier upsert wrote, or null after an earlier delete. A
@@ -3567,14 +3753,9 @@ export class SyncClient {
3567
3753
  if (refusal !== undefined)
3568
3754
  // §7.5: the same structured shape the native authoring APIs return — a
3569
3755
  // static message, and the dynamic cause in `details.legacyCause`.
3570
- throw new ClientSyncError(
3571
- 'sync.invalid_request',
3572
- 'the authoring request is invalid',
3573
- false,
3574
- {
3575
- legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
3576
- },
3577
- );
3756
+ throw invalidRequest('the authoring request is invalid', false, {
3757
+ legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
3758
+ });
3578
3759
  // §7.1 insert intent: a full-row write of a row the replica does not
3579
3760
  // show replays and encodes as a full row under every later schema.
3580
3761
  if (mutation.op !== 'patch') staged.set(`${table.name} ${pkValue}`, json);
@@ -3589,6 +3770,18 @@ export class SyncClient {
3589
3770
  insert: insert ? true : undefined,
3590
3771
  });
3591
3772
  });
3773
+ return operations;
3774
+ }
3775
+
3776
+ /**
3777
+ * Append one local commit and apply it optimistically; `within` adds its
3778
+ * own writes to the same transaction and change batch.
3779
+ */
3780
+ #appendCommit(
3781
+ clientCommitId: string,
3782
+ operations: readonly OutboxOperation[],
3783
+ within?: (batch: ChangeAccumulator) => void,
3784
+ ): void {
3592
3785
  // §5.11: a sealed row is read-only; a write could send NULL over
3593
3786
  // ciphertext this device cannot see.
3594
3787
  for (const operation of operations) {
@@ -3654,12 +3847,12 @@ export class SyncClient {
3654
3847
  }
3655
3848
  throw error;
3656
3849
  }
3850
+ within?.(batch);
3657
3851
  batch.status();
3658
3852
  });
3659
3853
  this.#needsPull = true;
3660
3854
  });
3661
3855
  this.#emitSyncIntent({ kind: 'interactive' });
3662
- return clientCommitId;
3663
3856
  }
3664
3857
 
3665
3858
  /** Host-facing mutation result with explicit network work intent (§7.5). */
@@ -3667,12 +3860,7 @@ export class SyncClient {
3667
3860
  mutations: readonly MutationInput[],
3668
3861
  options?: { readonly clientCommitId?: string },
3669
3862
  ): CommandResult<string> {
3670
- return {
3671
- value: this.mutate(mutations, options),
3672
- effects: {
3673
- sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
3674
- },
3675
- };
3863
+ return this.#commandResult(this.mutate(mutations, options));
3676
3864
  }
3677
3865
 
3678
3866
  /**
@@ -3756,7 +3944,15 @@ export class SyncClient {
3756
3944
  let result: LocalDataPurgeResult;
3757
3945
  try {
3758
3946
  result = this.#applyBatch((batch) => {
3759
- const targetsByTable = this.#localPurgeTargetsByTable(purge);
3947
+ const targetsByTable = new Map<
3948
+ string,
3949
+ CompiledLocalDataPurgeTarget[]
3950
+ >();
3951
+ for (const target of purge.targets)
3952
+ targetsByTable.set(target.table.name, [
3953
+ ...(targetsByTable.get(target.table.name) ?? []),
3954
+ target,
3955
+ ]);
3760
3956
  restoreFailedBases(this.#db, this.#schema);
3761
3957
  this.#dropRetainedRows(batch, (table, values) =>
3762
3958
  (targetsByTable.get(table) ?? []).some((target) =>
@@ -3847,36 +4043,21 @@ export class SyncClient {
3847
4043
  )
3848
4044
  batch.outcomes();
3849
4045
 
3850
- if (doomed.length > 0) {
3851
- // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
3852
- // never its operations, so no purged value survives in it.
3853
- for (const commit of doomed) {
3854
- const results: CommitOperationOutcome[] = commit.operations.map(
3855
- (_operation, opIndex) => {
3856
- const rejection: RejectionRecord = {
3857
- clientCommitId: commit.clientCommitId,
3858
- opIndex,
3859
- code: 'client.local_data_purged',
3860
- message:
3861
- 'the commit was dropped by an application-authorized local data purge',
3862
- retryable: false,
3863
- };
3864
- this.#rejections.push(rejection);
3865
- return { status: 'error', rejection };
3866
- },
3867
- );
3868
- recordCommitOutcome(this.#db, {
3869
- clientCommitId: commit.clientCommitId,
3870
- status: 'rejected',
3871
- recordedAtMs: this.#now(),
3872
- results,
3873
- });
3874
- }
3875
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
3876
- batch.status();
3877
- batch.rejections();
3878
- batch.outcomes();
3879
- }
4046
+ // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
4047
+ // never its operations, so no purged value survives in it.
4048
+ for (const { clientCommitId, operations } of doomed)
4049
+ this.#journalDrop(
4050
+ batch,
4051
+ clientCommitId,
4052
+ operations.map((_operation, opIndex) => ({
4053
+ clientCommitId,
4054
+ opIndex,
4055
+ code: 'client.local_data_purged',
4056
+ message:
4057
+ 'the commit was dropped by an application-authorized local data purge',
4058
+ retryable: false,
4059
+ })),
4060
+ );
3880
4061
  this.#replayOutbox();
3881
4062
  this.#deleteUnreferencedBlobs();
3882
4063
  setMeta(this.#db, metaKey, purge.canonicalPlan);
@@ -3976,7 +4157,6 @@ export class SyncClient {
3976
4157
 
3977
4158
  if (!priorUpgrading) this.#config.onUpgrading?.(true);
3978
4159
  this.#emitSyncNeeded('startup');
3979
- this.#emitSyncIntent({ kind: 'interactive' });
3980
4160
  return {
3981
4161
  alreadyApplied: false,
3982
4162
  retainedCommits: pending.length,
@@ -3984,18 +4164,6 @@ export class SyncClient {
3984
4164
  };
3985
4165
  }
3986
4166
 
3987
- #localPurgeTargetsByTable(
3988
- purge: CompiledLocalDataPurge,
3989
- ): Map<string, CompiledLocalDataPurgeTarget[]> {
3990
- const byTable = new Map<string, CompiledLocalDataPurgeTarget[]>();
3991
- for (const target of purge.targets) {
3992
- const targets = byTable.get(target.table.name) ?? [];
3993
- targets.push(target);
3994
- byTable.set(target.table.name, targets);
3995
- }
3996
- return byTable;
3997
- }
3998
-
3999
4167
  #localPurgeRowIds(purge: CompiledLocalDataPurge): Map<string, Set<string>> {
4000
4168
  const byTable = new Map<string, Set<string>>();
4001
4169
  for (const target of purge.targets) {
@@ -4026,8 +4194,13 @@ export class SyncClient {
4026
4194
  partial: Readonly<Record<string, unknown>>,
4027
4195
  options?: { readonly baseVersion?: number },
4028
4196
  ): CommandResult<string> {
4197
+ return this.#commandResult(this.patch(table, rowId, partial, options));
4198
+ }
4199
+
4200
+ /** A local write's result; an open transport gate owes interactive sync. */
4201
+ #commandResult<T>(value: T): CommandResult<T> {
4029
4202
  return {
4030
- value: this.patch(table, rowId, partial, options),
4203
+ value,
4031
4204
  effects: {
4032
4205
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
4033
4206
  },
@@ -4086,13 +4259,7 @@ export class SyncClient {
4086
4259
  // frames make a valid probe whose encoded size cancels out of the
4087
4260
  // per-commit delta measured against the canonical encoder.
4088
4261
  const baseBytes =
4089
- byteCap === undefined
4090
- ? 0
4091
- : encodeRequest({
4092
- wireVersion: PROTOCOL_WIRE_VERSION,
4093
- msgKind: 'request',
4094
- frames: [header, pull],
4095
- }).length;
4262
+ byteCap === undefined ? 0 : encodeRequestFrames([header, pull]).length;
4096
4263
  const pushFrames: RequestFrame[] = [];
4097
4264
  const outbox: OutboxCommit[] = [];
4098
4265
  const frameBytes: number[] = [];
@@ -4100,7 +4267,14 @@ export class SyncClient {
4100
4267
  let ops = 0;
4101
4268
  let bytes = 0;
4102
4269
  let processed = 0;
4270
+ // §7.2.2: a pending replacement holds itself and every later commit.
4271
+ const held = new Set(
4272
+ pendingDecisions(this.#db).map(
4273
+ (decision) => decision.replacementClientCommitId,
4274
+ ),
4275
+ );
4103
4276
  for (const commit of iterateOutbox(this.#db, throughSeq)) {
4277
+ if (held.has(commit.clientCommitId)) break;
4104
4278
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
4105
4279
  // commit that alone exceeds the operation cap is a typed capacity error
4106
4280
  // and stays queued; a later one defers with the complete suffix.
@@ -4189,11 +4363,7 @@ export class SyncClient {
4189
4363
  const frame =
4190
4364
  byteCap === undefined
4191
4365
  ? 0
4192
- : encodeRequest({
4193
- wireVersion: PROTOCOL_WIRE_VERSION,
4194
- msgKind: 'request',
4195
- frames: [header, pushFrame, pull],
4196
- }).length - baseBytes;
4366
+ : encodeRequestFrames([header, pushFrame, pull]).length - baseBytes;
4197
4367
  // The head is always encoded so the caller can report the full
4198
4368
  // projected request size with the final header and subscription bytes;
4199
4369
  // a later commit defers once it no longer fits.
@@ -4252,7 +4422,11 @@ export class SyncClient {
4252
4422
  const priorRejections = [...this.#rejections];
4253
4423
  this.#applyBatch(
4254
4424
  (batch) => {
4255
- if (this.#retainFailedCommits && code === 'client.encrypt_failed')
4425
+ if (
4426
+ this.#retainFailedCommits &&
4427
+ (code === 'client.encrypt_failed' ||
4428
+ code === REPLACEMENT_REFUSED_CODE)
4429
+ )
4256
4430
  retainFailedRows(
4257
4431
  this.#db,
4258
4432
  commit,
@@ -4265,27 +4439,22 @@ export class SyncClient {
4265
4439
  // the journal cannot carry keeps its durable commitId, code and a bounded
4266
4440
  // `details.reason` instead of an opaque rewritten value.
4267
4441
  const representable = commit.operations.every(isStoredOperation);
4268
- const rejection: RejectionRecord = definedObject({
4269
- clientCommitId: commit.clientCommitId,
4270
- opIndex: 0,
4271
- code,
4272
- message,
4273
- retryable: false,
4274
- ...(representable ? { operation: commit.operations[0] } : {}),
4275
- ...(reason === undefined ? {} : { details: { reason } }),
4276
- });
4277
- this.#rejections.push(rejection);
4278
- recordCommitOutcome(this.#db, {
4279
- clientCommitId: commit.clientCommitId,
4280
- status: 'rejected',
4281
- recordedAtMs: this.#now(),
4282
- results: [{ status: 'error', rejection }],
4283
- ...(representable ? { operations: commit.operations } : {}),
4284
- });
4285
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4286
- batch.status();
4287
- batch.rejections();
4288
- batch.outcomes();
4442
+ this.#journalDrop(
4443
+ batch,
4444
+ commit.clientCommitId,
4445
+ [
4446
+ definedObject({
4447
+ clientCommitId: commit.clientCommitId,
4448
+ opIndex: 0,
4449
+ code,
4450
+ message,
4451
+ retryable: false,
4452
+ operation: representable ? commit.operations[0] : undefined,
4453
+ details: reason === undefined ? undefined : { reason },
4454
+ }),
4455
+ ],
4456
+ representable ? commit.operations : undefined,
4457
+ );
4289
4458
  },
4290
4459
  undefined,
4291
4460
  (error) => {
@@ -4297,6 +4466,33 @@ export class SyncClient {
4297
4466
  );
4298
4467
  }
4299
4468
 
4469
+ /** §7.2: journal a dropped commit as rejected with these rejections. */
4470
+ #journalDrop(
4471
+ batch: ChangeAccumulator,
4472
+ clientCommitId: string,
4473
+ rejections: readonly RejectionRecord[],
4474
+ operations?: readonly OutboxOperation[],
4475
+ ): void {
4476
+ this.#rejections.push(...rejections);
4477
+ recordCommitOutcome(
4478
+ this.#db,
4479
+ definedObject({
4480
+ clientCommitId,
4481
+ status: 'rejected',
4482
+ recordedAtMs: this.#now(),
4483
+ results: rejections.map((rejection) => ({
4484
+ status: 'error' as const,
4485
+ rejection,
4486
+ })),
4487
+ operations,
4488
+ }),
4489
+ );
4490
+ pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4491
+ batch.status();
4492
+ batch.rejections();
4493
+ batch.outcomes();
4494
+ }
4495
+
4300
4496
  // -- sync -------------------------------------------------------------------
4301
4497
 
4302
4498
  /**
@@ -4402,39 +4598,25 @@ export class SyncClient {
4402
4598
  typeof code === 'string'
4403
4599
  ? this.#diagnosticCode(code)
4404
4600
  : 'client.unknown_failure';
4405
- const details =
4406
- typeof error === 'object' && error !== null && 'details' in error
4407
- ? error.details
4408
- : undefined;
4409
- const rawCause =
4410
- typeof details === 'object' &&
4411
- details !== null &&
4412
- 'causeKind' in details
4413
- ? details.causeKind
4414
- : undefined;
4415
- let causeKind: TransportCauseKind | undefined;
4416
- switch (rawCause) {
4417
- case 'network':
4418
- case 'connect':
4419
- case 'tls':
4420
- case 'io':
4421
- case 'request':
4422
- case 'protocol':
4423
- case 'timeout':
4424
- case 'round_deadline':
4425
- case 'aborted':
4426
- case 'body':
4427
- case 'status':
4428
- case 'redirect':
4429
- case 'unknown':
4430
- causeKind = rawCause;
4431
- }
4432
- const rawStatus =
4433
- typeof details === 'object' &&
4434
- details !== null &&
4435
- 'httpStatus' in details
4436
- ? details.httpStatus
4437
- : undefined;
4601
+ const rawCause = errorDetail(error, 'causeKind');
4602
+ const causeKind = (
4603
+ [
4604
+ 'network',
4605
+ 'connect',
4606
+ 'tls',
4607
+ 'io',
4608
+ 'request',
4609
+ 'protocol',
4610
+ 'timeout',
4611
+ 'round_deadline',
4612
+ 'aborted',
4613
+ 'body',
4614
+ 'status',
4615
+ 'redirect',
4616
+ 'unknown',
4617
+ ] as const
4618
+ ).find((kind) => kind === rawCause);
4619
+ const rawStatus = errorDetail(error, 'httpStatus');
4438
4620
  const httpStatus =
4439
4621
  (causeKind === 'status' ||
4440
4622
  causeKind === 'body' ||
@@ -4609,6 +4791,9 @@ export class SyncClient {
4609
4791
  cursor: unit.cursor,
4610
4792
  bootstrapState: unit.bootstrapState,
4611
4793
  }),
4794
+ ...(unit.restrict === undefined
4795
+ ? []
4796
+ : [{ type: 'RESTRICT' as const, ...unit.restrict }]),
4612
4797
  ],
4613
4798
  ),
4614
4799
  ];
@@ -4621,11 +4806,7 @@ export class SyncClient {
4621
4806
  // The fixed frames encode as envelope + fixed frames + END; each
4622
4807
  // admitted push frame adds its own (5 + payload). Trimming the tail
4623
4808
  // 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;
4809
+ const fixedBytes = encodeRequestFrames(fixedFrames).length;
4629
4810
  if (fixedBytes > byteCap)
4630
4811
  throw this.#pushCapacityError('bytes', byteCap, fixedBytes);
4631
4812
  let admittedBytes = 0;
@@ -4651,11 +4832,7 @@ export class SyncClient {
4651
4832
  ...pushFrames,
4652
4833
  ...fixedFrames.slice(lead.length),
4653
4834
  ];
4654
- const requestBytes = encodeRequest({
4655
- wireVersion: PROTOCOL_WIRE_VERSION,
4656
- msgKind: 'request',
4657
- frames,
4658
- });
4835
+ const requestBytes = encodeRequestFrames(frames);
4659
4836
  const responseBytes = await this.#roundTrip(requestBytes, signal);
4660
4837
  const message = decodeResponse(responseBytes);
4661
4838
  // §1.5: a complete, decodable response ends the report obligation.
@@ -4715,18 +4892,7 @@ export class SyncClient {
4715
4892
  // transport, `network` from a browser fetch) is not a round worth
4716
4893
  // backing off for. Stop without scheduling an intent or growing the
4717
4894
  // delay; the host's own connectivity signal re-arms the drive.
4718
- const details =
4719
- error instanceof ClientSyncError
4720
- ? error.details
4721
- : typeof error === 'object' && error !== null && 'details' in error
4722
- ? error.details
4723
- : undefined;
4724
- const causeKind =
4725
- typeof details === 'object' &&
4726
- details !== null &&
4727
- 'causeKind' in details
4728
- ? details.causeKind
4729
- : undefined;
4895
+ const causeKind = errorDetail(error, 'causeKind');
4730
4896
  const unreachable = causeKind === 'connect' || causeKind === 'network';
4731
4897
  // The round's work is still owed; the host's connectivity resume runs it.
4732
4898
  if (unreachable) this.#setSyncNeeded(true);
@@ -4789,17 +4955,18 @@ export class SyncClient {
4789
4955
  !(Number.isFinite(timeoutMs) && timeoutMs > 0)
4790
4956
  )
4791
4957
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
4792
- const key = `${maxRounds ?? 'default'}:${timeoutMs}`;
4958
+ const skipEmpty = typeof options === 'object' && options.skipEmpty === true;
4959
+ const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}`;
4793
4960
  const pending = this.#syncIdlePending.get(key);
4794
4961
  if (pending !== undefined) return pending;
4795
4962
  const previous = this.#syncIdleTail;
4796
4963
  let drive: Promise<SyncIdleResult>;
4797
4964
  if (previous === undefined) {
4798
- drive = this.#syncIdleRounds(maxRounds, timeoutMs);
4965
+ drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4799
4966
  } else {
4800
4967
  drive = previous.then(() => {
4801
4968
  this.#syncIdlePending.delete(key);
4802
- return this.#syncIdleRounds(maxRounds, timeoutMs);
4969
+ return this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
4803
4970
  });
4804
4971
  this.#syncIdlePending.set(key, drive);
4805
4972
  }
@@ -4818,6 +4985,7 @@ export class SyncClient {
4818
4985
  async #syncIdleRounds(
4819
4986
  maxRounds: number | undefined,
4820
4987
  timeoutMs: number,
4988
+ skipEmpty: boolean,
4821
4989
  ): Promise<SyncIdleResult> {
4822
4990
  const budget = maxRounds ?? 20;
4823
4991
  const aggregate = {
@@ -4835,6 +5003,24 @@ export class SyncClient {
4835
5003
  budgetExhausted,
4836
5004
  };
4837
5005
  };
5006
+ // §8.4: a replica without units, outbox work, or a server-side unit list
5007
+ // to clear has nothing to exchange; a host drive ends without a round.
5008
+ this.#requireActive();
5009
+ if (
5010
+ skipEmpty &&
5011
+ this.#schemaFloor === undefined &&
5012
+ !this.#hasStartupWork() &&
5013
+ loadUnits(this.#db).length === 0 &&
5014
+ (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined ||
5015
+ getMeta(this.#db, REGISTERED_DIGEST_KEY) ===
5016
+ bytesToHex(registrationDigest([])))
5017
+ ) {
5018
+ this.#setSyncNeeded(false);
5019
+ return result(false);
5020
+ }
5021
+ // §7.2.2: decisions pending when the drive began are settled at its end.
5022
+ const decisions = pendingDecisions(this.#db);
5023
+ const start = decisions.length > 0 ? this.#driveStart() : undefined;
4838
5024
  const states = () =>
4839
5025
  JSON.stringify(
4840
5026
  loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
@@ -4904,8 +5090,11 @@ export class SyncClient {
4904
5090
  aggregate.deferredCommits = last.deferredCommits ?? 0;
4905
5091
  aggregate.schemaFloor = last.schemaFloor;
4906
5092
  // A disabled transport or a schema floor ends the loop, not the budget.
4907
- if (!this.#transportEnabled || aggregate.schemaFloor)
5093
+ if (!this.#transportEnabled || aggregate.schemaFloor) {
5094
+ if (start !== undefined)
5095
+ this.#settleDecisions(decisions, start, result(false));
4908
5096
  return result(false);
5097
+ }
4909
5098
  if (
4910
5099
  maxRounds === undefined &&
4911
5100
  last.segmentRowsApplied > 0 &&
@@ -4921,6 +5110,11 @@ export class SyncClient {
4921
5110
  !aggregate.deferredCommits &&
4922
5111
  !this.#needsPull
4923
5112
  ) {
5113
+ if (
5114
+ start !== undefined &&
5115
+ this.#settleDecisions(decisions, start, result(false))
5116
+ )
5117
+ continue;
4924
5118
  return result(false);
4925
5119
  }
4926
5120
  }
@@ -5125,7 +5319,7 @@ export class SyncClient {
5125
5319
  // A superseded attempt leaves the successor's (or the deliberate
5126
5320
  // disconnect's) state alone.
5127
5321
  if (generation === this.#realtimeGeneration) {
5128
- this.#setRealtimeState('refused', realtimeErrorCode(error));
5322
+ this.#setRealtimeState('refused', thrownCode(error));
5129
5323
  }
5130
5324
  throw error;
5131
5325
  }
@@ -5248,14 +5442,12 @@ export class SyncClient {
5248
5442
  const event = parsed.event;
5249
5443
  if (event.event === 'hello') {
5250
5444
  if (event.data.requiresSync) {
5251
- this.#setSyncNeeded(true);
5252
5445
  this.#emitSyncNeeded('hello');
5253
5446
  }
5254
5447
  return;
5255
5448
  }
5256
5449
  if (event.event === 'sync') {
5257
5450
  // §8.3: any wake-up means "run a pull soon", never data.
5258
- this.#setSyncNeeded(true);
5259
5451
  this.#emitSyncNeeded(event.data.reason);
5260
5452
  return;
5261
5453
  }
@@ -5316,7 +5508,6 @@ export class SyncClient {
5316
5508
  )
5317
5509
  return;
5318
5510
  if (resetEpoch !== this.#localResetEpoch) {
5319
- this.#setSyncNeeded(true);
5320
5511
  this.#emitSyncNeeded('catchup-required');
5321
5512
  return;
5322
5513
  }
@@ -5326,7 +5517,6 @@ export class SyncClient {
5326
5517
  await this.#processResponse(message, [], undefined, 'delta');
5327
5518
  } catch {
5328
5519
  // A delta that cannot be applied is recovered by a pull (§8.3).
5329
- this.#setSyncNeeded(true);
5330
5520
  this.#emitSyncNeeded('catchup-required');
5331
5521
  }
5332
5522
  });
@@ -5436,11 +5626,12 @@ export class SyncClient {
5436
5626
 
5437
5627
  // §5.4/§5.5: queue every segment download of this response, so a paged
5438
5628
  // 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
5629
+ // trip per page. `limits.segmentPrefetch` downloads run at once, by
5630
+ // default four, the Rust native transport's pool size: enough to overlap
5631
+ // round trips, while the client holds that many bodies, the one being
5632
+ // applied and the rest ahead. An image starts only beside at most one
5633
+ // other body, so at most two are images (§5.3 client memory) whatever the
5634
+ // limit; later descriptors wait in order. The
5444
5635
  // loop takes each body out of the map before applying it and tops the
5445
5636
  // window up at the next descriptor. Eligibility mirrors the loop: a
5446
5637
  // descriptor outside an applied section or from an unconfigured
@@ -5452,7 +5643,7 @@ export class SyncClient {
5452
5643
  const prefetch = () => {
5453
5644
  for (
5454
5645
  let next;
5455
- prefetched.size < 4 &&
5646
+ prefetched.size < (this.#config.limits?.segmentPrefetch ?? 4) &&
5456
5647
  !(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
5457
5648
  (next = queued.shift());
5458
5649
  ) {
@@ -5593,11 +5784,17 @@ export class SyncClient {
5593
5784
  skip: false,
5594
5785
  }
5595
5786
  : undefined;
5596
- // §7.7: a section boundary ends the previous payload.
5787
+ // §7.7: a section boundary ends the previous payload; the same
5788
+ // snapshot takes the section's extent (§4.4).
5789
+ const extent = message.frames[index + 1];
5790
+ const stated =
5791
+ section !== undefined && extent?.type === 'UNIT_EXTENT';
5597
5792
  this.#progress.update({
5598
5793
  ...NO_PAYLOAD,
5599
5794
  phase: 'import',
5600
5795
  unitId: section?.unit.id,
5796
+ unitRowsTotal: stated ? extent.rowsTotal : undefined,
5797
+ unitRowsProcessed: stated ? extent.rowsDone : undefined,
5601
5798
  });
5602
5799
  break;
5603
5800
  }
@@ -5625,19 +5822,22 @@ export class SyncClient {
5625
5822
  // §5.6: rows an earlier attempt at this position applied. A
5626
5823
  // partly applied image already ran its table's first-page clear.
5627
5824
  appliedRows = section.unit.applied?.[frame.segmentId];
5628
- if (appliedRows !== undefined) {
5629
- section.seeded.add(frame.table);
5630
- if (appliedRows === frame.rowCount) break;
5631
- }
5825
+ if (appliedRows !== undefined) section.seeded.add(frame.table);
5826
+ const imported = appliedRows === frame.rowCount;
5632
5827
  this.#progress.update({
5633
5828
  ...NO_PAYLOAD,
5634
- phase: 'download',
5829
+ phase: imported ? 'import' : 'download',
5635
5830
  unitId,
5636
5831
  table: frame.table,
5637
5832
  segmentId: frame.segmentId,
5638
- bytesTotal: frame.byteLength,
5833
+ bytesTotal: imported ? undefined : frame.byteLength,
5639
5834
  rowsTotal: frame.rowCount,
5640
5835
  });
5836
+ if (imported) {
5837
+ // §7.7: an earlier attempt imported this payload.
5838
+ this.#progress.update({ rowsProcessed: frame.rowCount });
5839
+ break;
5840
+ }
5641
5841
  prefetch();
5642
5842
  const pending = prefetched.get(frame);
5643
5843
  prefetched.delete(frame);
@@ -5655,13 +5855,7 @@ export class SyncClient {
5655
5855
  // catching up with its cursor unpersisted, and the next
5656
5856
  // round's SUB_START settles it (revoked or a new bootstrap).
5657
5857
  // A host downloader may throw any error carrying the code.
5658
- if (
5659
- typeof error !== 'object' ||
5660
- error === null ||
5661
- !('code' in error) ||
5662
- error.code !== 'sync.forbidden'
5663
- )
5664
- throw error;
5858
+ if (thrownCode(error) !== 'sync.forbidden') throw error;
5665
5859
  section.skip = true;
5666
5860
  break;
5667
5861
  }
@@ -5748,6 +5942,10 @@ export class SyncClient {
5748
5942
  this.#localResetEpoch === resetEpoch
5749
5943
  ) {
5750
5944
  this.#finishSection(section, frame, summary);
5945
+ // §7.7: a completed bootstrap ends at what it imported.
5946
+ const processed = this.#progress.snapshot()?.unitRowsProcessed;
5947
+ if (frame.bootstrapState === undefined && processed !== undefined)
5948
+ this.#progress.update({ unitRowsTotal: processed });
5751
5949
  }
5752
5950
  section = undefined;
5753
5951
  // The counters stay: `complete` and `failed` report them.
@@ -5908,7 +6106,6 @@ export class SyncClient {
5908
6106
  if (deltaCursor >= 0) this.#sendAck(deltaCursor);
5909
6107
  // §8.2: an unapplied delta is a drop; a pull repairs it.
5910
6108
  if (deltaDropped) {
5911
- this.#setSyncNeeded(true);
5912
6109
  this.#emitSyncNeeded('catchup-required');
5913
6110
  }
5914
6111
  } else {
@@ -5990,13 +6187,7 @@ export class SyncClient {
5990
6187
  return true;
5991
6188
  }
5992
6189
  // rejected
5993
- const cacheMiss = frame.results.some(
5994
- (result) =>
5995
- result.status === 'error' &&
5996
- result.code === 'sync.idempotency_cache_miss' &&
5997
- result.retryable,
5998
- );
5999
- if (cacheMiss) {
6190
+ if (!isFinalPushResult(frame)) {
6000
6191
  // §6.3: a serving failure, not the commit's outcome — keep the
6001
6192
  // commit queued and retry the identical push later.
6002
6193
  summary.retryable.push(frame.clientCommitId);
@@ -6006,6 +6197,10 @@ export class SyncClient {
6006
6197
  for (const result of frame.results) {
6007
6198
  const operation = commit.operations[result.opIndex];
6008
6199
  if (result.status === 'conflict') {
6200
+ const columns =
6201
+ this.#schema.tables.get(operation?.table ?? '')?.columns ?? [];
6202
+ const values =
6203
+ columns.length === 0 ? [] : decodeRow(columns, result.serverRow);
6009
6204
  const conflict: ConflictRecord = definedObject({
6010
6205
  clientCommitId: frame.clientCommitId,
6011
6206
  opIndex: result.opIndex,
@@ -6014,11 +6209,21 @@ export class SyncClient {
6014
6209
  code: result.code,
6015
6210
  message: result.message,
6016
6211
  serverVersion: result.serverVersion,
6017
- serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
6018
- conflictColumns: this.#decodeConflictColumns(
6019
- operation?.table,
6020
- result.conflictColumns,
6212
+ serverRow: Object.fromEntries(
6213
+ columns.map((column, index) => [
6214
+ column.name,
6215
+ values[index] ?? null,
6216
+ ]),
6021
6217
  ),
6218
+ // §6.3: the presence-layout bitmap names the present columns whose
6219
+ // `column_version` exceeded `baseVersion`; a custom merge
6220
+ // recomputes exactly these (§6.5).
6221
+ conflictColumns: columns
6222
+ .filter(
6223
+ (_, index) =>
6224
+ ((result.conflictColumns[index >> 3] ?? 0) >> (index & 7)) & 1,
6225
+ )
6226
+ .map((column) => column.name),
6022
6227
  operation: operation,
6023
6228
  });
6024
6229
  this.#conflicts.push(conflict);
@@ -6097,41 +6302,6 @@ export class SyncClient {
6097
6302
  );
6098
6303
  }
6099
6304
 
6100
- #decodeServerRow(
6101
- tableName: string | undefined,
6102
- payload: Uint8Array,
6103
- ): Record<string, RowValue> {
6104
- if (tableName === undefined) return {};
6105
- const table = this.#schema.tables.get(tableName);
6106
- if (table === undefined) return {};
6107
- const values = decodeRow(table.columns, payload);
6108
- const record: Record<string, RowValue> = {};
6109
- table.columns.forEach((column, index) => {
6110
- record[column.name] = values[index] ?? null;
6111
- });
6112
- return record;
6113
- }
6114
-
6115
- /**
6116
- * §6.3 `conflictColumns`: decode the presence-layout bitmap into the names
6117
- * of the present columns whose `column_version` exceeded `baseVersion`. A
6118
- * custom merge recomputes exactly these columns (§6.5).
6119
- */
6120
- #decodeConflictColumns(
6121
- tableName: string | undefined,
6122
- bitmap: Uint8Array,
6123
- ): readonly string[] {
6124
- if (tableName === undefined) return [];
6125
- const table = this.#schema.tables.get(tableName);
6126
- if (table === undefined) return [];
6127
- const names: string[] = [];
6128
- table.columns.forEach((column, index) => {
6129
- const byte = bitmap[index >> 3] ?? 0;
6130
- if (((byte >> (index & 7)) & 1) === 1) names.push(column.name);
6131
- });
6132
- return names;
6133
- }
6134
-
6135
6305
  async #applyCommit(
6136
6306
  frame: CommitFrame,
6137
6307
  summary: MutableSummary,
@@ -6299,10 +6469,17 @@ export class SyncClient {
6299
6469
  // §3.3 owners matter only for rows the clear would reach, so a pair
6300
6470
  // with no matching local or retained row never reads the unit list.
6301
6471
  let owners: readonly ScopeMap[] | undefined;
6472
+ const clearFirst = !section.seeded.has(tableName);
6473
+ // §5.6: a first page outside the restriction is a whole bootstrap from a
6474
+ // server that predates RESTRICT; the restriction ends before the clear.
6475
+ if (clearFirst && unit.restrict?.tables.includes(tableName) === false)
6476
+ this.#db.exec(`UPDATE ${UNITS_TABLE} SET restriction=NULL WHERE id=?`, [
6477
+ unit.id,
6478
+ ]);
6302
6479
  try {
6303
6480
  summary.segmentRowsApplied += await apply(
6304
6481
  table,
6305
- !section.seeded.has(tableName),
6482
+ clearFirst,
6306
6483
  effective,
6307
6484
  () =>
6308
6485
  (owners ??=
@@ -6328,6 +6505,7 @@ export class SyncClient {
6328
6505
  ...current,
6329
6506
  status: 'failed',
6330
6507
  reasonCode: 'sync.scope_revoked',
6508
+ restrict: undefined,
6331
6509
  });
6332
6510
  for (const ref of windowRefs(this.#db, unit.id))
6333
6511
  batch.window(ref.baseKey, ref.value);
@@ -6401,8 +6579,7 @@ export class SyncClient {
6401
6579
  throw invalidRequest('segment exceeds its byteLength', true);
6402
6580
  }
6403
6581
  onProgress(bytes.byteLength);
6404
- const hash = await sha256Hex(bytes);
6405
- if (`sha256:${hash}` !== frame.segmentId) {
6582
+ if ((await computeBlobId(bytes)) !== frame.segmentId) {
6406
6583
  throw invalidRequest(
6407
6584
  'segment failed content-address verification (§5.1)',
6408
6585
  true,
@@ -6436,9 +6613,7 @@ export class SyncClient {
6436
6613
  saveUnit(this.#db, {
6437
6614
  ...unit,
6438
6615
  reasonCode: start.reasonCode,
6439
- cursor: -1,
6440
- bootstrapState: undefined,
6441
- seeded: [],
6616
+ ...UNIT_RESTART,
6442
6617
  });
6443
6618
  summary.resets.push(unit.id);
6444
6619
  return;
@@ -6474,10 +6649,8 @@ export class SyncClient {
6474
6649
  ...unit,
6475
6650
  status: failed ? 'failed' : 'revoked',
6476
6651
  reasonCode: failed ? 'sync.scope_revoked' : start.reasonCode,
6477
- cursor: -1,
6478
- bootstrapState: undefined,
6479
- seeded: [],
6480
6652
  echo: undefined,
6653
+ ...UNIT_RESTART,
6481
6654
  });
6482
6655
  if (revoked) summary.revoked.push(unit.id);
6483
6656
  if (failed) summary.failed.push(unit.id);
@@ -6489,14 +6662,18 @@ export class SyncClient {
6489
6662
  ...unit,
6490
6663
  reasonCode: undefined,
6491
6664
  echo: start.fenced,
6665
+ // §7.4.3: a rearm and a completed bootstrap end the restriction.
6492
6666
  ...(rearmed
6493
- ? { cursor: -1, bootstrapState: undefined, seeded: [] }
6667
+ ? UNIT_RESTART
6494
6668
  : start.bootstrap
6495
6669
  ? {
6496
6670
  cursor: end.nextCursor,
6497
6671
  bootstrapState: end.bootstrapState,
6498
6672
  seeded:
6499
6673
  end.bootstrapState === undefined ? [] : [...section.seeded],
6674
+ ...(end.bootstrapState === undefined
6675
+ ? { restrict: undefined }
6676
+ : {}),
6500
6677
  }
6501
6678
  : {}),
6502
6679
  });
@@ -6570,37 +6747,22 @@ export class SyncClient {
6570
6747
  ownsLocalRow(table, lastEffective, owners, op.values),
6571
6748
  ),
6572
6749
  );
6573
- for (const commit of doomed) {
6574
- const { clientCommitId } = commit;
6750
+ for (const { clientCommitId, operations } of doomed) {
6575
6751
  deleteOutboxCommit(this.#db, clientCommitId);
6576
- const results: CommitOperationOutcome[] = commit.operations.map(
6577
- (operation, opIndex) => {
6578
- const rejection: RejectionRecord = {
6579
- clientCommitId,
6580
- opIndex,
6581
- code: 'sync.scope_revoked',
6582
- message:
6583
- 'the commit was dropped because its effective scope was revoked',
6584
- retryable: false,
6585
- operation,
6586
- };
6587
- this.#rejections.push(rejection);
6588
- return { status: 'error', rejection };
6589
- },
6590
- );
6591
- recordCommitOutcome(this.#db, {
6752
+ this.#journalDrop(
6753
+ batch,
6592
6754
  clientCommitId,
6593
- status: 'rejected',
6594
- recordedAtMs: this.#now(),
6595
- results,
6596
- operations: commit.operations,
6597
- });
6598
- }
6599
- if (doomed.length > 0) {
6600
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
6601
- batch.status();
6602
- batch.rejections();
6603
- batch.outcomes();
6755
+ operations.map((operation, opIndex) => ({
6756
+ clientCommitId,
6757
+ opIndex,
6758
+ code: 'sync.scope_revoked',
6759
+ message:
6760
+ 'the commit was dropped because its effective scope was revoked',
6761
+ retryable: false,
6762
+ operation,
6763
+ })),
6764
+ operations,
6765
+ );
6604
6766
  }
6605
6767
  this.#replayOutbox(scope);
6606
6768
  this.#deleteUnreferencedBlobs();
@@ -6637,8 +6799,7 @@ export class SyncClient {
6637
6799
  }
6638
6800
  const syncVersion = row[SYNC_VERSION_COLUMN];
6639
6801
  if (typeof syncVersion !== 'number') {
6640
- throw new ClientSyncError(
6641
- 'sync.local_corrupt',
6802
+ throw localStateCorrupt(
6642
6803
  `local row ${operation.table}/${operation.rowId} has no sync version`,
6643
6804
  );
6644
6805
  }
@@ -6651,8 +6812,7 @@ export class SyncClient {
6651
6812
  onlyKeys?: ReadonlySet<string>,
6652
6813
  ): OutboxBeforeImage[] {
6653
6814
  return operations.flatMap((operation, opIndex) =>
6654
- onlyKeys &&
6655
- !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
6815
+ onlyKeys && !onlyKeys.has(rowKey(operation))
6656
6816
  ? []
6657
6817
  : [this.#captureBeforeImage(operation, opIndex)],
6658
6818
  );
@@ -6671,15 +6831,14 @@ export class SyncClient {
6671
6831
  return;
6672
6832
  }
6673
6833
  if (image.values === undefined || image.syncVersion === undefined) {
6674
- throw new ClientSyncError(
6675
- 'sync.local_corrupt',
6834
+ throw localStateCorrupt(
6676
6835
  `rollback image for ${operation.table}/${operation.rowId} is incomplete`,
6677
6836
  );
6678
6837
  }
6679
6838
  const values = table.columns.map((column) =>
6680
6839
  jsonToRowValue(image.values?.[column.name] ?? null),
6681
6840
  );
6682
- upsertLocalRow(this.#db, table, values, image.syncVersion, false);
6841
+ upsertLocalRow(this.#db, table, values, image.syncVersion);
6683
6842
  }
6684
6843
 
6685
6844
  #legacyUndoOptimisticRows(
@@ -6712,19 +6871,14 @@ export class SyncClient {
6712
6871
  const complete = commit.operations.every((_, index) =>
6713
6872
  imageByIndex.has(index),
6714
6873
  );
6715
- const affectedKeys = new Set(
6716
- commit.operations.map((operation) =>
6717
- JSON.stringify([operation.table, operation.rowId]),
6718
- ),
6719
- );
6874
+ const affectedKeys = new Set(commit.operations.map(rowKey));
6720
6875
  if (complete) {
6721
- const restored = new Set<string>();
6876
+ // The first operation on a row holds its pre-commit image.
6877
+ const unrestored = new Set(affectedKeys);
6722
6878
  commit.operations.forEach((operation, index) => {
6723
- const key = JSON.stringify([operation.table, operation.rowId]);
6724
- if (restored.has(key)) return;
6725
6879
  const image = imageByIndex.get(index);
6726
- if (image) this.#restoreBeforeImage(operation, image, batch);
6727
- restored.add(key);
6880
+ if (unrestored.delete(rowKey(operation)) && image)
6881
+ this.#restoreBeforeImage(operation, image, batch);
6728
6882
  });
6729
6883
  } else {
6730
6884
  // Pending commits written by older clients have no before-images.
@@ -6737,7 +6891,7 @@ export class SyncClient {
6737
6891
  for (const later of listOutbox(this.#db, [...affectedKeys])) {
6738
6892
  if (later.seq <= commit.seq) continue;
6739
6893
  const affectedOperations = later.operations.filter((operation) =>
6740
- affectedKeys.has(JSON.stringify([operation.table, operation.rowId])),
6894
+ affectedKeys.has(rowKey(operation)),
6741
6895
  );
6742
6896
  if (affectedOperations.length === 0) continue;
6743
6897
  replaceOutboxBeforeImages(
@@ -6771,14 +6925,8 @@ export class SyncClient {
6771
6925
  : this.#table(op.table);
6772
6926
  if (table === undefined) continue;
6773
6927
  let precise =
6774
- batch === undefined
6775
- ? false
6776
- : this.#recordStoredRowScopes(batch, table, op.rowId);
6777
- if (op.op === 'delete') {
6778
- if (batch !== undefined && !precise) batch.table(op.table);
6779
- deleteLocalRow(this.#db, table, op.rowId, false);
6780
- continue;
6781
- }
6928
+ batch !== undefined &&
6929
+ this.#recordStoredRowScopes(batch, table, op.rowId);
6782
6930
  // §7.1 overlay: apply the operation's PRESENT columns over the current
6783
6931
  // local row. A partial operation over an absent local row leaves it
6784
6932
  // absent — the server answers it with sync.row_deleted or
@@ -6788,20 +6936,21 @@ export class SyncClient {
6788
6936
  const full =
6789
6937
  op.insert === true ||
6790
6938
  table.columns.every((column) => column.name in opValues);
6939
+ const local =
6940
+ op.op === 'delete' ? undefined : this.#rowById(table, op.rowId);
6791
6941
  // An insert lacking a non-nullable column cannot encode (§7.4.4); it
6792
6942
  // stays hidden until the send-time drop classifies it.
6793
6943
  if (
6794
- op.insert === true &&
6795
- table.columns.some(
6796
- (column) => !column.nullable && opValues[column.name] === undefined,
6797
- )
6944
+ op.op === 'delete' ||
6945
+ (op.insert === true &&
6946
+ table.columns.some(
6947
+ (column) => !column.nullable && opValues[column.name] === undefined,
6948
+ )) ||
6949
+ (local === undefined && !full)
6798
6950
  ) {
6799
6951
  if (batch !== undefined && !precise) batch.table(op.table);
6800
- continue;
6801
- }
6802
- const local = this.#rowById(table, op.rowId);
6803
- if (local === undefined && !full) {
6804
- if (batch !== undefined && !precise) batch.table(op.table);
6952
+ if (op.op === 'delete')
6953
+ deleteLocalRow(this.#db, table, op.rowId, false);
6805
6954
  continue;
6806
6955
  }
6807
6956
  const values = table.columns.map((column) => {
@@ -6829,10 +6978,7 @@ export class SyncClient {
6829
6978
  values,
6830
6979
  );
6831
6980
  } catch {
6832
- throw new ClientSyncError(
6833
- 'sync.local_corrupt',
6834
- 'persisted optimistic row value is invalid',
6835
- );
6981
+ throw localStateCorrupt('persisted optimistic row value is invalid');
6836
6982
  }
6837
6983
  }
6838
6984
  // Record the row's scope keys from its scope columns (I2 refinement).
@@ -6867,7 +7013,7 @@ export class SyncClient {
6867
7013
  ).length
6868
7014
  )
6869
7015
  continue;
6870
- upsertLocalRow(this.#db, table, values, version, false);
7016
+ upsertLocalRow(this.#db, table, values, version);
6871
7017
  }
6872
7018
  }
6873
7019
 
@@ -6892,7 +7038,7 @@ export class SyncClient {
6892
7038
  );
6893
7039
  for (const op of commit.operations) {
6894
7040
  batch.table(op.table);
6895
- scope.push(JSON.stringify([op.table, op.rowId]));
7041
+ scope.push(rowKey(op));
6896
7042
  }
6897
7043
  }
6898
7044
  return scope;
@@ -7026,7 +7172,7 @@ export class SyncClient {
7026
7172
  commit.operations.filter(
7027
7173
  (op) =>
7028
7174
  scope === undefined ||
7029
- scope.includes(JSON.stringify([op.table, op.rowId])) ||
7175
+ scope.includes(rowKey(op)) ||
7030
7176
  scope.includes(JSON.stringify([op.table])),
7031
7177
  ),
7032
7178
  batch,