@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/dist/client.js CHANGED
@@ -20,17 +20,17 @@ import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
21
21
  import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
22
22
  import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
23
- import { ClientSyncError, invalidRequest, classifySqliteFailure, isStableCode, REALTIME_LOST_CODE, RealtimeUnavailableError, transportFailed, } from './errors.js';
23
+ import { ClientSyncError, invalidRequest, classifySqliteFailure, isStableCode, REALTIME_LOST_CODE, RealtimeUnavailableError, transportFailed, localStateCorrupt, } from './errors.js';
24
24
  import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
25
25
  import { singleOwnerLock, } from './leader-lock.js';
26
26
  import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
27
27
  import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
28
28
  import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
29
29
  import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
30
- import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, scrubPurgedOutcomes, } from './outcomes.js';
30
+ import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, pendingDecisions, recordCommitOutcome, scrubPurgedOutcomes, } from './outcomes.js';
31
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
32
  import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, resetLocalReplica, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, stripSyncColumns, toSqlValue, } from './schema.js';
33
- import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, recordAppliedRows, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
33
+ import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, recordAppliedRows, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, saveUnit, saveUnitScopeSchema, UNITS_TABLE, setMeta, unitOwners, unitStateCorrupt, } from './state.js';
34
34
  import { deletePendingEviction, loadPendingEvictions, loadWindowUnits, savePendingEviction, windowBaseKey, windowRefs, WINDOWS_TABLE, windowUnitScopes, } from './window.js';
35
35
  /** Stable client-local error while protected operations are preflight-gated. */
36
36
  export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
@@ -55,6 +55,7 @@ const ACCEPT_SIGNED_URLS = 1 << 3;
55
55
  * Never a wire code (§10.3) — surfaced through the rejection channel.
56
56
  */
57
57
  const OUTBOX_INCOMPATIBLE_CODE = 'sync.outbox_incompatible';
58
+ const REPLACEMENT_REFUSED_CODE = 'sync.replacement_refused';
58
59
  /** §7.4.4: static text for a persisted commit the current codec refuses. */
59
60
  const LEGACY_VALUE_REFUSAL_MESSAGE = 'the persisted commit carries values the current codec refuses';
60
61
  /** §7.4.4: bounded reason on every intrinsic value drop. */
@@ -63,13 +64,36 @@ const INVALID_STORED_VALUES_REASON = 'invalid_stored_values';
63
64
  * `sync.too_many_operations` above it). The push half sends whole commits in
64
65
  * commit order up to this cap and defers the rest to the next round. */
65
66
  const MAX_OPS_PER_REQUEST = 500;
66
- async function sha256Hex(bytes) {
67
- const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
68
- return [...new Uint8Array(digest)]
69
- .map((b) => b.toString(16).padStart(2, '0'))
70
- .join('');
71
- }
72
67
  const invalidHostResponse = (message) => new ClientSyncError('client.invalid_host_response', message);
68
+ /** A field of the structured `details` any thrown value carries. */
69
+ const errorDetail = (error, key) => {
70
+ const details = typeof error === 'object' && error !== null && 'details' in error
71
+ ? error.details
72
+ : undefined;
73
+ return typeof details === 'object' && details !== null
74
+ ? details[key]
75
+ : undefined;
76
+ };
77
+ /** §4.6: the unit state a reset, revocation or rearm starts over from. */
78
+ const UNIT_RESTART = {
79
+ cursor: -1,
80
+ bootstrapState: undefined,
81
+ seeded: [],
82
+ restrict: undefined,
83
+ };
84
+ /** An overlay row key (`JSON [table,rowId]`). */
85
+ const rowKey = (operation) => JSON.stringify([operation.table, operation.rowId]);
86
+ const unproven = (reason) => ({ proven: false, reason });
87
+ const replacementPending = () => new ClientSyncError('client.replacement_pending', 'the outcome has a pending replacement', false);
88
+ /** §7.2.1: an active failure with a complete retained aggregate. */
89
+ const provable = (candidate, sequence) => candidate !== undefined &&
90
+ candidate.sequence === sequence &&
91
+ candidate.resolution === 'active' &&
92
+ (candidate.status === 'conflict' || candidate.status === 'rejected') &&
93
+ candidate.operations !== undefined &&
94
+ candidate.retainedRows !== undefined &&
95
+ candidate.operations.length === candidate.retainedRows.length &&
96
+ candidate.retainedRows.length > 0;
73
97
  const outcomeNotFound = () => new ClientSyncError('sync.outcome_not_found', 'no durable outcome exists for the commit');
74
98
  function emptySummary(pushed) {
75
99
  return {
@@ -136,11 +160,19 @@ function isFinalPushResult(frame) {
136
160
  result.code === 'sync.idempotency_cache_miss' &&
137
161
  result.retryable));
138
162
  }
139
- /** The stable `code` of a thrown realtime transport error, when it has one. */
140
- function realtimeErrorCode(error) {
163
+ /** The stable `code` a thrown value carries, when it has one. */
164
+ function thrownCode(error) {
141
165
  const code = error?.code;
142
166
  return typeof code === 'string' ? code : undefined;
143
167
  }
168
+ /** Encodes a request in the current wire version. */
169
+ function encodeRequestFrames(frames) {
170
+ return encodeRequest({
171
+ wireVersion: PROTOCOL_WIRE_VERSION,
172
+ msgKind: 'request',
173
+ frames,
174
+ });
175
+ }
144
176
  /** §7.7: progress fields of a payload; no payload is current. */
145
177
  const NO_PAYLOAD = {
146
178
  table: undefined,
@@ -285,17 +317,16 @@ export class SyncClient {
285
317
  throw invalidRequest('transportEnabled must be a boolean');
286
318
  }
287
319
  this.#transportEnabled = config.transportEnabled !== false;
288
- for (const [name, value] of [
289
- ['maxPushCommitsPerRequest', config.limits?.maxPushCommitsPerRequest],
290
- [
291
- 'maxPushOperationsPerRequest',
292
- config.limits?.maxPushOperationsPerRequest,
293
- ],
294
- ['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
320
+ for (const name of [
321
+ 'maxPushCommitsPerRequest',
322
+ 'maxPushOperationsPerRequest',
323
+ 'maxPushRequestBytes',
324
+ 'segmentPrefetch',
295
325
  ]) {
326
+ const value = config.limits?.[name];
296
327
  if (value !== undefined &&
297
328
  (!Number.isInteger(value) || value < 1 || value > 0xffffffff)) {
298
- throw new ClientSyncError('sync.invalid_request', 'push limit must be an integer in 1..=4294967295', false, { limit: name });
329
+ throw invalidRequest('limit must be an integer in 1..=4294967295', false, { limit: name });
299
330
  }
300
331
  }
301
332
  if (config.securityPreflight === true && config.encryption !== undefined) {
@@ -380,31 +411,28 @@ export class SyncClient {
380
411
  try {
381
412
  const meta = this.#db.query("SELECT type FROM sqlite_master WHERE name = '_syncular_meta'")[0];
382
413
  if (meta !== undefined) {
383
- if (meta.type !== 'table')
384
- throw new Error('invalid metadata table');
385
- const rows = this.#db.query('SELECT value FROM _syncular_meta WHERE key = ?', [LOCAL_SCHEMA_VERSION_KEY]);
386
- // A duplicated marker cannot be resolved. Picking one row could
387
- // select an older version and drive a destructive reset over a
388
- // newer replica.
389
- if (rows.length > 1)
414
+ const rows = meta.type === 'table'
415
+ ? this.#db.query('SELECT value FROM _syncular_meta WHERE key = ?', [LOCAL_SCHEMA_VERSION_KEY])
416
+ : undefined;
417
+ const value = rows?.[0]?.value;
418
+ const version = Number(value);
419
+ // The catch below turns each refusal into `sync.local_corrupt`.
420
+ if (rows === undefined ||
421
+ // A duplicated marker cannot be resolved. Picking one row could
422
+ // select an older version and drive a destructive reset over a
423
+ // newer replica.
424
+ rows.length > 1 ||
425
+ (value === undefined
426
+ ? // A descriptor without its paired marker.
427
+ this.#db.query("SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1").length > 0
428
+ : typeof value !== 'string' ||
429
+ !Number.isInteger(version) ||
430
+ version < 1 ||
431
+ version > 2147483647 ||
432
+ String(version) !== value))
390
433
  throw new Error('invalid schema marker');
391
- const row = rows[0];
392
- if (row === undefined &&
393
- this.#db.query("SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1").length > 0) {
394
- throw new Error('missing paired schema marker');
395
- }
396
- if (row !== undefined) {
397
- const value = row.value;
398
- const version = Number(value);
399
- if (typeof value !== 'string' ||
400
- !Number.isInteger(version) ||
401
- version < 1 ||
402
- version > 2147483647 ||
403
- String(version) !== value) {
404
- throw new Error('invalid schema marker');
405
- }
434
+ if (value !== undefined)
406
435
  marker = version;
407
- }
408
436
  }
409
437
  }
410
438
  catch (error) {
@@ -414,7 +442,7 @@ export class SyncClient {
414
442
  const failure = classifySqliteFailure(error);
415
443
  if (failure.code !== undefined)
416
444
  throw failure.error;
417
- throw new ClientSyncError('sync.local_corrupt', 'persisted local schema marker is unreadable or invalid');
445
+ throw localStateCorrupt('persisted local schema marker is unreadable or invalid');
418
446
  }
419
447
  if (marker !== undefined && marker > this.#schema.version) {
420
448
  throw new ClientSyncError('client.schema_downgrade', 'persisted local schema is newer than the requested schema', false, {
@@ -485,7 +513,6 @@ export class SyncClient {
485
513
  if (this.#securityLifecycle === 'active' && this.#hasStartupWork()) {
486
514
  this.#needsPull = true;
487
515
  this.#emitSyncNeeded('startup');
488
- this.#emitSyncIntent({ kind: 'interactive' });
489
516
  }
490
517
  // Console introspection is a no-op outside a dev page.
491
518
  this.#devtoolsUnregister = this.#config.devtools?.({
@@ -512,28 +539,19 @@ export class SyncClient {
512
539
  * marker, so the shape chosen here commits under that snapshot.
513
540
  */
514
541
  #detectAndResetSchema(marker) {
515
- if (marker === undefined) {
516
- // Fresh install: the tables just created match the running code.
517
- this.#db.transaction(() => {
518
- ensureLocalSyncedSchema(this.#db, this.#schema);
542
+ if (marker !== undefined && marker !== this.#schema.version)
543
+ return this.#runSchemaReset();
544
+ // A fresh install's tables just created match the running code. Same-version
545
+ // opens remain self-healing for absent tables/indexes, and RFC 0005 D1
546
+ // backfills the descriptor for a database first opened by 0.22.0 or
547
+ // earlier WITHOUT a schema bump.
548
+ this.#db.transaction(() => {
549
+ ensureLocalSyncedSchema(this.#db, this.#schema);
550
+ if (marker === undefined)
519
551
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
520
- setLocalSchemaDescriptor(this.#db, this.#schema);
521
- saveUnitScopeSchema(this.#db, this.#schema);
522
- });
523
- return;
524
- }
525
- if (marker === this.#schema.version) {
526
- // Same-version opens remain self-healing for absent tables/indexes, and
527
- // RFC 0005 D1 backfills the descriptor for a database first opened by
528
- // 0.22.0 or earlier WITHOUT a schema bump.
529
- this.#db.transaction(() => {
530
- ensureLocalSyncedSchema(this.#db, this.#schema);
531
- setLocalSchemaDescriptor(this.#db, this.#schema);
532
- saveUnitScopeSchema(this.#db, this.#schema);
533
- });
534
- return;
535
- }
536
- this.#runSchemaReset();
552
+ setLocalSchemaDescriptor(this.#db, this.#schema);
553
+ saveUnitScopeSchema(this.#db, this.#schema);
554
+ });
537
555
  }
538
556
  /**
539
557
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
@@ -633,9 +651,7 @@ export class SyncClient {
633
651
  #runLogEpochReset(logEpoch) {
634
652
  if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
635
653
  this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
636
- this.#setSyncNeeded(true);
637
654
  this.#emitSyncNeeded('startup');
638
- this.#emitSyncIntent({ kind: 'interactive' });
639
655
  return [];
640
656
  }
641
657
  const units = loadUnits(this.#db);
@@ -666,9 +682,7 @@ export class SyncClient {
666
682
  throw error;
667
683
  });
668
684
  this.#localResetEpoch += 1;
669
- this.#setSyncNeeded(true);
670
685
  this.#emitSyncNeeded('startup');
671
- this.#emitSyncIntent({ kind: 'interactive' });
672
686
  return units.map((unit) => unit.id);
673
687
  }
674
688
  #setUpgrading(upgrading) {
@@ -710,36 +724,35 @@ export class SyncClient {
710
724
  this.#syncNeededListeners.clear();
711
725
  this.#syncIntentListeners.clear();
712
726
  }
727
+ /** Mark a pull as needed and tell the host; a startup wake also asks for
728
+ * an interactive round. */
713
729
  #emitSyncNeeded(reason) {
730
+ this.#setSyncNeeded(true);
714
731
  if (!this.#transportEnabled)
715
732
  return;
716
- try {
717
- this.#config.onSyncNeeded?.(reason);
718
- }
719
- catch {
720
- // An observer cannot alter sync correctness.
721
- }
722
- for (const listener of this.#syncNeededListeners) {
733
+ for (const listener of [
734
+ this.#config.onSyncNeeded,
735
+ ...this.#syncNeededListeners,
736
+ ]) {
723
737
  try {
724
- listener(reason);
738
+ listener?.(reason);
725
739
  }
726
740
  catch {
727
741
  // An observer cannot alter sync correctness.
728
742
  }
729
743
  }
744
+ if (reason === 'startup')
745
+ this.#emitSyncIntent({ kind: 'interactive' });
730
746
  }
731
747
  #emitSyncIntent(intent) {
732
748
  if (!this.#transportEnabled && intent.kind !== 'none')
733
749
  return;
734
- try {
735
- this.#config.onSyncIntent?.(intent);
736
- }
737
- catch {
738
- // An observer cannot alter sync correctness.
739
- }
740
- for (const listener of this.#syncIntentListeners) {
750
+ for (const listener of [
751
+ this.#config.onSyncIntent,
752
+ ...this.#syncIntentListeners,
753
+ ]) {
741
754
  try {
742
- listener(intent);
755
+ listener?.(intent);
743
756
  }
744
757
  catch {
745
758
  // An observer cannot alter sync correctness.
@@ -794,13 +807,11 @@ export class SyncClient {
794
807
  this.#syncOutstanding = false;
795
808
  })();
796
809
  this.#preflightBarrier = barrier;
797
- void barrier.then(() => {
798
- if (this.#preflightBarrier === barrier)
799
- this.#preflightBarrier = undefined;
800
- }, () => {
810
+ const release = () => {
801
811
  if (this.#preflightBarrier === barrier)
802
812
  this.#preflightBarrier = undefined;
803
- });
813
+ };
814
+ void barrier.then(release, release);
804
815
  return barrier;
805
816
  }
806
817
  /**
@@ -823,9 +834,7 @@ export class SyncClient {
823
834
  });
824
835
  await this.#serialize(() => this.#revealSealed());
825
836
  if (this.#hasStartupWork()) {
826
- this.#setSyncNeeded(true);
827
837
  this.#emitSyncNeeded('startup');
828
- this.#emitSyncIntent({ kind: 'interactive' });
829
838
  }
830
839
  }
831
840
  /** Persisted work an opened or activated replica owes one round (§8.4). */
@@ -940,7 +949,7 @@ export class SyncClient {
940
949
  return { state: 'unknown', id };
941
950
  const cursor = unit.cursor ?? replicaCursor(this.#db);
942
951
  if (!Number.isSafeInteger(cursor))
943
- throw new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
952
+ throw unitStateCorrupt();
944
953
  const active = unit.status === 'active';
945
954
  const pending = bootstrapping(unit);
946
955
  return definedObject({
@@ -1045,34 +1054,29 @@ export class SyncClient {
1045
1054
  return this.#previousVersionUnavailable(currentVersion, 'not-configured');
1046
1055
  }
1047
1056
  const record = this.#readPreviousVersionRecord();
1048
- const nowMs = this.#now();
1049
- if (this.#previousVersionLeaseInactive(nowMs)) {
1050
- this.#discardPreviousVersion();
1051
- return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1052
- }
1053
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1054
- this.#discardPreviousVersion();
1055
- return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1056
- }
1057
1057
  // Coverage completion is a live predicate: the container is normally
1058
1058
  // dropped by the sync path first, so a read can be the first observer.
1059
- if (this.#previousVersionCoverageComplete()) {
1060
- this.#discardPreviousVersion();
1061
- return this.#previousVersionUnavailable(currentVersion, 'coverage-complete');
1062
- }
1063
- if (record === undefined) {
1064
- const refusal = storedPreviousVersionRefusal(this.#db);
1065
- return this.#previousVersionUnavailable(currentVersion, refusal?.reason ?? 'no-previous-descriptor');
1066
- }
1067
- if (record.currentVersion !== currentVersion) {
1068
- this.#discardPreviousVersion();
1069
- return this.#previousVersionUnavailable(currentVersion, 'no-previous-descriptor');
1070
- }
1071
- if (nowMs - record.createdAtMs >
1072
- previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
1059
+ const nowMs = this.#now();
1060
+ const ended = this.#previousVersionLeaseInactive(nowMs)
1061
+ ? 'lease-inactive'
1062
+ : loadUnits(this.#db).some((unit) => unit.status === 'revoked')
1063
+ ? 'scope-revoked'
1064
+ : this.#previousVersionCoverageComplete()
1065
+ ? 'coverage-complete'
1066
+ : record === undefined
1067
+ ? undefined
1068
+ : record.currentVersion !== currentVersion
1069
+ ? 'no-previous-descriptor'
1070
+ : this.#previousVersionExpired(record, nowMs)
1071
+ ? 'expired'
1072
+ : undefined;
1073
+ if (ended !== undefined) {
1073
1074
  this.#discardPreviousVersion();
1074
- return this.#previousVersionUnavailable(currentVersion, 'expired');
1075
+ return this.#previousVersionUnavailable(currentVersion, ended);
1075
1076
  }
1077
+ if (record === undefined)
1078
+ return this.#previousVersionUnavailable(currentVersion, storedPreviousVersionRefusal(this.#db)?.reason ??
1079
+ 'no-previous-descriptor');
1076
1080
  const table = record.tables.find((entry) => entry.name === spec.table);
1077
1081
  if (table === undefined) {
1078
1082
  throw invalidRequest(`previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`);
@@ -1179,20 +1183,16 @@ export class SyncClient {
1179
1183
  return;
1180
1184
  }
1181
1185
  const record = this.#readPreviousVersionRecord();
1182
- if (record === undefined)
1183
- return;
1184
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1186
+ if (record !== undefined &&
1187
+ (loadUnits(this.#db).some((unit) => unit.status === 'revoked') ||
1188
+ this.#previousVersionExpired(record, nowMs) ||
1189
+ this.#previousVersionCoverageComplete()))
1185
1190
  this.#discardPreviousVersion();
1186
- return;
1187
- }
1188
- if (nowMs - record.createdAtMs >
1189
- previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
1190
- this.#discardPreviousVersion();
1191
- return;
1192
- }
1193
- if (this.#previousVersionCoverageComplete()) {
1194
- this.#discardPreviousVersion();
1195
- }
1191
+ }
1192
+ /** RFC 0005 D7: the container outlived `previousVersionContext.maxAgeMs`. */
1193
+ #previousVersionExpired(record, nowMs = this.#now()) {
1194
+ return (nowMs - record.createdAtMs >
1195
+ previousVersionMaxAgeMs(this.#config.previousVersionContext));
1196
1196
  }
1197
1197
  /**
1198
1198
  * RFC 0005 D9 boot hygiene: an orphan/stale container is discarded before any
@@ -1203,15 +1203,10 @@ export class SyncClient {
1203
1203
  if (!this.#previousVersionExists())
1204
1204
  return;
1205
1205
  const record = this.#readPreviousVersionRecord();
1206
- let discard = record === undefined || record.currentVersion !== this.#schema.version;
1207
- if (!discard &&
1208
- record !== undefined &&
1209
- this.#previousVersion !== undefined &&
1210
- this.#now() - record.createdAtMs >
1211
- previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
1212
- discard = true;
1213
- }
1214
- if (discard)
1206
+ if (record === undefined ||
1207
+ record.currentVersion !== this.#schema.version ||
1208
+ (this.#previousVersion !== undefined &&
1209
+ this.#previousVersionExpired(record)))
1215
1210
  this.#dropPreviousVersion();
1216
1211
  }
1217
1212
  // -- live-query invalidation ----------------------------------------------
@@ -1360,15 +1355,15 @@ export class SyncClient {
1360
1355
  const blobBytes = this.#hasBlobs
1361
1356
  ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
1362
1357
  : 0;
1363
- const pressure = this.#config.blobCacheMaxBytes !== undefined &&
1364
- blobBytes > this.#config.blobCacheMaxBytes;
1358
+ const pressure = blobBytes > (this.#config.limits?.blobCacheMaxBytes ?? Infinity);
1359
+ const size = (value) => Math.max(0, Number(value ?? 0));
1365
1360
  return {
1366
1361
  status: pressure ? 'pressure' : 'healthy',
1367
1362
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
1368
- pendingOutboxBytesApprox: Math.max(0, Number(sums?.outbox ?? 0)),
1369
- retainedOutcomeBytesApprox: Math.max(0, Number(sums?.bytes ?? 0)),
1370
- retainedOutcomeEntries: Math.max(0, Number(sums?.entries ?? 0)),
1371
- blobCacheBytesApprox: Math.max(0, blobBytes),
1363
+ pendingOutboxBytesApprox: size(sums?.outbox),
1364
+ retainedOutcomeBytesApprox: size(sums?.bytes),
1365
+ retainedOutcomeEntries: size(sums?.entries),
1366
+ blobCacheBytesApprox: size(blobBytes),
1372
1367
  ...(pressure
1373
1368
  ? { pressureReasonCode: 'client.blob_cache_over_limit' }
1374
1369
  : {}),
@@ -1609,7 +1604,7 @@ export class SyncClient {
1609
1604
  }
1610
1605
  /** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
1611
1606
  #enforceBlobCacheCap() {
1612
- const cap = this.#config.blobCacheMaxBytes;
1607
+ const cap = this.#config.limits?.blobCacheMaxBytes;
1613
1608
  if (cap === undefined)
1614
1609
  return;
1615
1610
  enforceBlobCacheCap(this.#db, this.#schema, cap);
@@ -1638,7 +1633,7 @@ export class SyncClient {
1638
1633
  !Number.isSafeInteger(cached.byteLength) ||
1639
1634
  cached.byteLength !== cached.bytes.byteLength ||
1640
1635
  (await computeBlobId(cached.bytes)) !== pending.blobId) {
1641
- throw new ClientSyncError('sync.local_corrupt', 'Pending blob upload body is missing or corrupt');
1636
+ throw localStateCorrupt('Pending blob upload body is missing or corrupt');
1642
1637
  }
1643
1638
  try {
1644
1639
  await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType, signal);
@@ -1719,64 +1714,62 @@ export class SyncClient {
1719
1714
  async proveCurrentBase(outcome, maxRounds) {
1720
1715
  this.#requireActive();
1721
1716
  requireRoundBudget(maxRounds);
1722
- const { clientCommitId, sequence } = outcome;
1723
- const provable = (candidate) => candidate !== undefined &&
1724
- candidate.sequence === sequence &&
1725
- candidate.resolution === 'active' &&
1726
- (candidate.status === 'conflict' || candidate.status === 'rejected') &&
1727
- candidate.operations !== undefined &&
1728
- candidate.retainedRows !== undefined &&
1729
- candidate.operations.length === candidate.retainedRows.length &&
1730
- candidate.retainedRows.length > 0;
1731
1717
  let initial;
1732
1718
  try {
1733
- initial = readCommitOutcome(this.#db, clientCommitId);
1719
+ initial = readCommitOutcome(this.#db, outcome.clientCommitId);
1734
1720
  }
1735
1721
  catch {
1736
- return { proven: false, reason: 'snapshot_failed' };
1722
+ return unproven('snapshot_failed');
1737
1723
  }
1738
- if (!provable(initial))
1739
- return { proven: false, reason: 'outcome_unavailable' };
1724
+ if (!provable(initial, outcome.sequence))
1725
+ return unproven('outcome_unavailable');
1740
1726
  if (!this.#transportEnabled)
1741
- return { proven: false, reason: 'offline' };
1727
+ return unproven('offline');
1742
1728
  await this.#opChain;
1743
1729
  if (!this.#transportEnabled)
1744
- return { proven: false, reason: 'offline' };
1745
- const epoch = this.#transportEpoch;
1746
- const registrationEpoch = this.#registrationEpoch;
1747
- const securityEpoch = this.#securityEpoch;
1748
- let before;
1730
+ return unproven('offline');
1731
+ let start;
1749
1732
  try {
1750
- before = loadUnits(this.#db);
1733
+ start = this.#driveStart();
1751
1734
  }
1752
1735
  catch {
1753
- return { proven: false, reason: 'snapshot_failed' };
1736
+ return unproven('snapshot_failed');
1754
1737
  }
1755
1738
  let report;
1756
1739
  try {
1757
1740
  report = await this.syncUntilIdle(maxRounds);
1758
1741
  }
1759
1742
  catch {
1760
- return {
1761
- proven: false,
1762
- reason: !this.#transportEnabled || epoch !== this.#transportEpoch
1763
- ? 'offline'
1764
- : registrationEpoch !== this.#registrationEpoch
1765
- ? 'missing_coverage'
1766
- : 'sync_failed',
1767
- };
1743
+ return unproven(!this.#transportEnabled || start.epoch !== this.#transportEpoch
1744
+ ? 'offline'
1745
+ : start.registrationEpoch !== this.#registrationEpoch
1746
+ ? 'missing_coverage'
1747
+ : 'sync_failed');
1768
1748
  }
1749
+ return this.#provenBase(outcome, start, report);
1750
+ }
1751
+ /** The drive state a §7.2.1 proof compares against after the drive. */
1752
+ #driveStart() {
1753
+ return {
1754
+ before: loadUnits(this.#db),
1755
+ epoch: this.#transportEpoch,
1756
+ registrationEpoch: this.#registrationEpoch,
1757
+ securityEpoch: this.#securityEpoch,
1758
+ };
1759
+ }
1760
+ /** §7.2.1: the proof after a completed drive that began at `start`. */
1761
+ #provenBase({ clientCommitId, sequence, }, { before, epoch, registrationEpoch, securityEpoch }, report) {
1769
1762
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
1770
- return { proven: false, reason: 'offline' };
1763
+ return unproven('offline');
1771
1764
  if (registrationEpoch !== this.#registrationEpoch)
1772
- return { proven: false, reason: 'missing_coverage' };
1765
+ return unproven('missing_coverage');
1773
1766
  if (this.#securityLifecycle !== 'active' ||
1774
1767
  securityEpoch !== this.#securityEpoch)
1775
- return { proven: false, reason: 'sync_failed' };
1768
+ return unproven('sync_failed');
1776
1769
  if (report.schemaFloor !== undefined)
1777
- return { proven: false, reason: 'schema_floor' };
1770
+ return unproven('schema_floor');
1778
1771
  if (report.budgetExhausted)
1779
- return { proven: false, reason: 'budget_exhausted' };
1772
+ return unproven('budget_exhausted');
1780
1773
  try {
1781
1774
  return this.#db.transaction(() => {
1782
1775
  const snapshot = this.#readSnapshot({
@@ -1786,11 +1779,8 @@ export class SyncClient {
1786
1779
  });
1787
1780
  const delivery = snapshot.deliveries[0];
1788
1781
  const current = readCommitOutcome(this.#db, clientCommitId);
1789
- if (delivery?.status !== 'known' || !provable(current))
1790
- return {
1791
- proven: false,
1792
- reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
1793
- };
1782
+ if (delivery?.status !== 'known' || !provable(current, sequence))
1783
+ return unproven(report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable');
1794
1784
  const after = new Map(loadUnits(this.#db).map((unit) => [unit.id, unit]));
1795
1785
  const complete = new Set(snapshot.units.flatMap((state) => state.state === 'known' && state.bootstrapComplete
1796
1786
  ? [state.id]
@@ -1827,17 +1817,14 @@ export class SyncClient {
1827
1817
  for (const row of current.retainedRows) {
1828
1818
  if (!covered(row.table, row.serverRow ?? row.localRow) ||
1829
1819
  row.uniqueConflicts?.some((conflict) => !covered(row.table, conflict.serverRow))) {
1830
- return {
1831
- proven: false,
1832
- reason: report.revoked.length > 0 ? 'revoked' : 'missing_coverage',
1833
- };
1820
+ return unproven(report.revoked.length > 0 ? 'revoked' : 'missing_coverage');
1834
1821
  }
1835
1822
  }
1836
1823
  return { proven: true, rows: current.retainedRows };
1837
1824
  });
1838
1825
  }
1839
1826
  catch {
1840
- return { proven: false, reason: 'snapshot_failed' };
1827
+ return unproven('snapshot_failed');
1841
1828
  }
1842
1829
  }
1843
1830
  /** Newest-first durable outcome journal. */
@@ -1859,6 +1846,8 @@ export class SyncClient {
1859
1846
  }
1860
1847
  if (current.resolution !== 'active')
1861
1848
  return current;
1849
+ if (current.replacementClientCommitId !== undefined)
1850
+ throw replacementPending();
1862
1851
  const replacement = input.replacementClientCommitId;
1863
1852
  if (input.resolution === 'superseded') {
1864
1853
  if (replacement === undefined ||
@@ -1878,10 +1867,109 @@ export class SyncClient {
1878
1867
  if (!allowed) {
1879
1868
  throw invalidRequest(`resolution ${input.resolution} is invalid for ${current.status} outcome`);
1880
1869
  }
1870
+ return this.#resolveOutcome(input, current);
1871
+ }
1872
+ /**
1873
+ * §7.2.2: record a decision against an active failure as a held
1874
+ * replacement commit, written once a later drive proves its base.
1875
+ */
1876
+ replaceCommitOutcome(input) {
1877
+ this.#requireActive();
1878
+ const current = readCommitOutcome(this.#db, input.clientCommitId);
1879
+ if (current === undefined)
1880
+ throw outcomeNotFound();
1881
+ if (current.resolution === 'active' &&
1882
+ current.replacementClientCommitId !== undefined)
1883
+ throw replacementPending();
1884
+ if (!provable(current, input.sequence))
1885
+ throw invalidRequest('the outcome holds no complete retained aggregate');
1886
+ // Envelope operation i belongs to retained row i, so keep mine finds
1887
+ // every operation's row; a payload names no version for one.
1888
+ const operations = (input.replacement === undefined
1889
+ ? current.operations
1890
+ : this.#outboxOperations(input.replacement)).map((operation) => {
1891
+ const row = current.retainedRows.find((candidate) => candidate.table === operation.table &&
1892
+ candidate.rowId === operation.rowId);
1893
+ if (row === undefined)
1894
+ return operation;
1895
+ if (input.replacement !== undefined &&
1896
+ operation.baseVersion !== undefined)
1897
+ throw invalidRequest('a replacement takes the base version of a retained row');
1898
+ return { ...operation, baseVersion: row.serverVersion ?? 0 };
1899
+ });
1900
+ const clientCommitId = crypto.randomUUID();
1901
+ this.#appendCommit(clientCommitId, operations, (batch) => {
1902
+ this.#db.exec(`UPDATE ${OUTCOMES_TABLE} SET replacement_client_commit_id=? WHERE client_commit_id=? AND resolution='active'`, [clientCommitId, input.clientCommitId]);
1903
+ batch.outcomes();
1904
+ });
1905
+ return clientCommitId;
1906
+ }
1907
+ /**
1908
+ * §7.2.2: at the idle point of a drive, write or refuse each decision that
1909
+ * was pending when the drive began. True when a replacement was written.
1910
+ */
1911
+ #settleDecisions(decisions, start, report) {
1912
+ // A registration change during the drive says nothing about the base;
1913
+ // the decisions wait for the next drive.
1914
+ if (start.registrationEpoch !== this.#registrationEpoch)
1915
+ return false;
1916
+ let written = false;
1917
+ for (const decision of decisions) {
1918
+ const current = readCommitOutcome(this.#db, decision.clientCommitId);
1919
+ if (current?.resolution !== 'active' ||
1920
+ current.replacementClientCommitId !== decision.replacementClientCommitId)
1921
+ continue;
1922
+ // A replacement that already left the outbox has its own outcome.
1923
+ const commit = listOutbox(this.#db).find((candidate) => candidate.clientCommitId === decision.replacementClientCommitId);
1924
+ const proof = commit && this.#provenBase(decision, start, report);
1925
+ const reason = !proof
1926
+ ? undefined
1927
+ : !proof.proven
1928
+ ? proof.reason
1929
+ : commit.operations.every((operation) => {
1930
+ const row = proof.rows.find((candidate) => candidate.table === operation.table &&
1931
+ candidate.rowId === operation.rowId);
1932
+ return (row === undefined ||
1933
+ operation.baseVersion === (row.serverVersion ?? 0));
1934
+ })
1935
+ ? undefined
1936
+ : 'base_moved';
1937
+ // These proof failures say nothing about the base; the next drive retries.
1938
+ if (/^(offline|sync_failed|budget_exhausted|snapshot_failed)$/.test(reason))
1939
+ continue;
1940
+ written ||= reason === undefined && commit !== undefined;
1941
+ this.#resolveOutcome({
1942
+ clientCommitId: decision.clientCommitId,
1943
+ resolution: 'superseded',
1944
+ replacementClientCommitId: decision.replacementClientCommitId,
1945
+ }, current, () => reason !== undefined &&
1946
+ this.#dropIncompatibleCommit(commit, 'the replacement could not be written on a proven base', REPLACEMENT_REFUSED_CODE, true, reason));
1947
+ }
1948
+ return written;
1949
+ }
1950
+ #resolveOutcome(input, current, within) {
1881
1951
  const priorConflicts = this.#conflicts;
1882
1952
  const priorRejections = this.#rejections;
1883
1953
  return this.#applyBatch((batch) => {
1884
- restoreFailedBases(this.#db, this.#schema);
1954
+ // Restore the server base under the retained rows, then replay what
1955
+ // stays and re-take later commits' before-images over that base, so
1956
+ // a later rollback cannot bring the released intent back.
1957
+ const scope = [
1958
+ ...new Set(this.#db
1959
+ .query(`SELECT tbl,id FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
1960
+ input.clientCommitId,
1961
+ ])
1962
+ .flatMap((row) => {
1963
+ const table = this.#schema.tables.get(String(row.tbl));
1964
+ return [
1965
+ ...(table !== undefined && hasUniqueIndex(table)
1966
+ ? [JSON.stringify([row.tbl])]
1967
+ : []),
1968
+ JSON.stringify([row.tbl, row.id]),
1969
+ ];
1970
+ })),
1971
+ ];
1972
+ restoreFailedBases(this.#db, this.#schema, scope);
1885
1973
  this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
1886
1974
  input.clientCommitId,
1887
1975
  ]);
@@ -1892,7 +1980,7 @@ export class SyncClient {
1892
1980
  this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== input.clientCommitId);
1893
1981
  this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== input.clientCommitId);
1894
1982
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
1895
- this.#replayOutbox();
1983
+ this.#replayOutbox(scope, false);
1896
1984
  for (const operation of current.operations ?? [])
1897
1985
  batch.table(operation.table);
1898
1986
  batch.outcomes();
@@ -1900,6 +1988,7 @@ export class SyncClient {
1900
1988
  batch.conflicts();
1901
1989
  if (current.status === 'rejected')
1902
1990
  batch.rejections();
1991
+ within?.();
1903
1992
  return resolved;
1904
1993
  }, undefined, (error) => {
1905
1994
  this.#conflicts = priorConflicts;
@@ -2013,9 +2102,7 @@ export class SyncClient {
2013
2102
  }));
2014
2103
  if (registered) {
2015
2104
  this.#registrationEpoch += 1;
2016
- this.#setSyncNeeded(true);
2017
- this.#emitSyncIntent({ kind: 'interactive' });
2018
- this.#emitDiagnostics();
2105
+ this.#registrationChanged();
2019
2106
  }
2020
2107
  return ids;
2021
2108
  }
@@ -2034,8 +2121,11 @@ export class SyncClient {
2034
2121
  }
2035
2122
  deleteUnit(this.#db, id);
2036
2123
  this.#registrationEpoch += 1;
2037
- if (unit.status !== 'active')
2038
- return;
2124
+ if (unit.status === 'active')
2125
+ this.#registrationChanged();
2126
+ }
2127
+ /** A registration change owes an interactive pull. */
2128
+ #registrationChanged() {
2039
2129
  this.#setSyncNeeded(true);
2040
2130
  this.#emitSyncIntent({ kind: 'interactive' });
2041
2131
  this.#emitDiagnostics();
@@ -2257,6 +2347,11 @@ export class SyncClient {
2257
2347
  readCommitOutcome(this.#db, supplied)))
2258
2348
  throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
2259
2349
  const clientCommitId = supplied ?? crypto.randomUUID();
2350
+ this.#appendCommit(clientCommitId, this.#outboxOperations(mutations));
2351
+ return clientCommitId;
2352
+ }
2353
+ /** §7.1: validate local mutations into their stored outbox operations. */
2354
+ #outboxOperations(mutations) {
2260
2355
  // §7.1: a patch reads the row as the commit's earlier operations leave
2261
2356
  // it. Keyed by `table rowId` (a table name holds no space): the JSON
2262
2357
  // values an earlier upsert wrote, or null after an earlier delete. A
@@ -2343,7 +2438,7 @@ export class SyncClient {
2343
2438
  if (refusal !== undefined)
2344
2439
  // §7.5: the same structured shape the native authoring APIs return — a
2345
2440
  // static message, and the dynamic cause in `details.legacyCause`.
2346
- throw new ClientSyncError('sync.invalid_request', 'the authoring request is invalid', false, {
2441
+ throw invalidRequest('the authoring request is invalid', false, {
2347
2442
  legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
2348
2443
  });
2349
2444
  // §7.1 insert intent: a full-row write of a row the replica does not
@@ -2360,6 +2455,13 @@ export class SyncClient {
2360
2455
  insert: insert ? true : undefined,
2361
2456
  });
2362
2457
  });
2458
+ return operations;
2459
+ }
2460
+ /**
2461
+ * Append one local commit and apply it optimistically; `within` adds its
2462
+ * own writes to the same transaction and change batch.
2463
+ */
2464
+ #appendCommit(clientCommitId, operations, within) {
2363
2465
  // §5.11: a sealed row is read-only; a write could send NULL over
2364
2466
  // ciphertext this device cannot see.
2365
2467
  for (const operation of operations) {
@@ -2409,21 +2511,16 @@ export class SyncClient {
2409
2511
  }
2410
2512
  throw error;
2411
2513
  }
2514
+ within?.(batch);
2412
2515
  batch.status();
2413
2516
  });
2414
2517
  this.#needsPull = true;
2415
2518
  });
2416
2519
  this.#emitSyncIntent({ kind: 'interactive' });
2417
- return clientCommitId;
2418
2520
  }
2419
2521
  /** Host-facing mutation result with explicit network work intent (§7.5). */
2420
2522
  mutateCommand(mutations, options) {
2421
- return {
2422
- value: this.mutate(mutations, options),
2423
- effects: {
2424
- sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2425
- },
2426
- };
2523
+ return this.#commandResult(this.mutate(mutations, options));
2427
2524
  }
2428
2525
  /**
2429
2526
  * Partial update over the §6.1 sparse wire: record one upsert whose
@@ -2496,7 +2593,12 @@ export class SyncClient {
2496
2593
  let result;
2497
2594
  try {
2498
2595
  result = this.#applyBatch((batch) => {
2499
- const targetsByTable = this.#localPurgeTargetsByTable(purge);
2596
+ const targetsByTable = new Map();
2597
+ for (const target of purge.targets)
2598
+ targetsByTable.set(target.table.name, [
2599
+ ...(targetsByTable.get(target.table.name) ?? []),
2600
+ target,
2601
+ ]);
2500
2602
  restoreFailedBases(this.#db, this.#schema);
2501
2603
  this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
2502
2604
  // Doomed detection runs to fixpoint, matching the Rust core's rule:
@@ -2558,33 +2660,16 @@ export class SyncClient {
2558
2660
  (values !== undefined &&
2559
2661
  localDataPurgeTargetMatches(target, values)))))
2560
2662
  batch.outcomes();
2561
- if (doomed.length > 0) {
2562
- // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
2563
- // never its operations, so no purged value survives in it.
2564
- for (const commit of doomed) {
2565
- const results = commit.operations.map((_operation, opIndex) => {
2566
- const rejection = {
2567
- clientCommitId: commit.clientCommitId,
2568
- opIndex,
2569
- code: 'client.local_data_purged',
2570
- message: 'the commit was dropped by an application-authorized local data purge',
2571
- retryable: false,
2572
- };
2573
- this.#rejections.push(rejection);
2574
- return { status: 'error', rejection };
2575
- });
2576
- recordCommitOutcome(this.#db, {
2577
- clientCommitId: commit.clientCommitId,
2578
- status: 'rejected',
2579
- recordedAtMs: this.#now(),
2580
- results,
2581
- });
2582
- }
2583
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
2584
- batch.status();
2585
- batch.rejections();
2586
- batch.outcomes();
2587
- }
2663
+ // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
2664
+ // never its operations, so no purged value survives in it.
2665
+ for (const { clientCommitId, operations } of doomed)
2666
+ this.#journalDrop(batch, clientCommitId, operations.map((_operation, opIndex) => ({
2667
+ clientCommitId,
2668
+ opIndex,
2669
+ code: 'client.local_data_purged',
2670
+ message: 'the commit was dropped by an application-authorized local data purge',
2671
+ retryable: false,
2672
+ })));
2588
2673
  this.#replayOutbox();
2589
2674
  this.#deleteUnreferencedBlobs();
2590
2675
  setMeta(this.#db, metaKey, purge.canonicalPlan);
@@ -2678,22 +2763,12 @@ export class SyncClient {
2678
2763
  if (!priorUpgrading)
2679
2764
  this.#config.onUpgrading?.(true);
2680
2765
  this.#emitSyncNeeded('startup');
2681
- this.#emitSyncIntent({ kind: 'interactive' });
2682
2766
  return {
2683
2767
  alreadyApplied: false,
2684
2768
  retainedCommits: pending.length,
2685
2769
  resetSubscriptions,
2686
2770
  };
2687
2771
  }
2688
- #localPurgeTargetsByTable(purge) {
2689
- const byTable = new Map();
2690
- for (const target of purge.targets) {
2691
- const targets = byTable.get(target.table.name) ?? [];
2692
- targets.push(target);
2693
- byTable.set(target.table.name, targets);
2694
- }
2695
- return byTable;
2696
- }
2697
2772
  #localPurgeRowIds(purge) {
2698
2773
  const byTable = new Map();
2699
2774
  for (const target of purge.targets) {
@@ -2714,8 +2789,12 @@ export class SyncClient {
2714
2789
  }
2715
2790
  /** Host-facing patch result with explicit network work intent (§7.5). */
2716
2791
  patchCommand(table, rowId, partial, options) {
2792
+ return this.#commandResult(this.patch(table, rowId, partial, options));
2793
+ }
2794
+ /** A local write's result; an open transport gate owes interactive sync. */
2795
+ #commandResult(value) {
2717
2796
  return {
2718
- value: this.patch(table, rowId, partial, options),
2797
+ value,
2719
2798
  effects: {
2720
2799
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2721
2800
  },
@@ -2756,13 +2835,7 @@ export class SyncClient {
2756
2835
  // A request must start with REQ_HEADER and carry PULL_HEADER; those two
2757
2836
  // frames make a valid probe whose encoded size cancels out of the
2758
2837
  // per-commit delta measured against the canonical encoder.
2759
- const baseBytes = byteCap === undefined
2760
- ? 0
2761
- : encodeRequest({
2762
- wireVersion: PROTOCOL_WIRE_VERSION,
2763
- msgKind: 'request',
2764
- frames: [header, pull],
2765
- }).length;
2838
+ const baseBytes = byteCap === undefined ? 0 : encodeRequestFrames([header, pull]).length;
2766
2839
  const pushFrames = [];
2767
2840
  const outbox = [];
2768
2841
  const frameBytes = [];
@@ -2770,7 +2843,11 @@ export class SyncClient {
2770
2843
  let ops = 0;
2771
2844
  let bytes = 0;
2772
2845
  let processed = 0;
2846
+ // §7.2.2: a pending replacement holds itself and every later commit.
2847
+ const held = new Set(pendingDecisions(this.#db).map((decision) => decision.replacementClientCommitId));
2773
2848
  for (const commit of iterateOutbox(this.#db, throughSeq)) {
2849
+ if (held.has(commit.clientCommitId))
2850
+ break;
2774
2851
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
2775
2852
  // commit that alone exceeds the operation cap is a typed capacity error
2776
2853
  // and stays queued; a later one defers with the complete suffix.
@@ -2830,11 +2907,7 @@ export class SyncClient {
2830
2907
  }
2831
2908
  const frame = byteCap === undefined
2832
2909
  ? 0
2833
- : encodeRequest({
2834
- wireVersion: PROTOCOL_WIRE_VERSION,
2835
- msgKind: 'request',
2836
- frames: [header, pushFrame, pull],
2837
- }).length - baseBytes;
2910
+ : encodeRequestFrames([header, pushFrame, pull]).length - baseBytes;
2838
2911
  // The head is always encoded so the caller can report the full
2839
2912
  // projected request size with the final header and subscription bytes;
2840
2913
  // a later commit defers once it no longer fits.
@@ -2871,7 +2944,9 @@ export class SyncClient {
2871
2944
  #dropIncompatibleCommit(commit, message, code = OUTBOX_INCOMPATIBLE_CODE, replay = true, reason, classifiedFailures) {
2872
2945
  const priorRejections = [...this.#rejections];
2873
2946
  this.#applyBatch((batch) => {
2874
- if (this.#retainFailedCommits && code === 'client.encrypt_failed')
2947
+ if (this.#retainFailedCommits &&
2948
+ (code === 'client.encrypt_failed' ||
2949
+ code === REPLACEMENT_REFUSED_CODE))
2875
2950
  retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId));
2876
2951
  this.#rollbackFailedCommit(commit, batch, classifiedFailures);
2877
2952
  if (replay)
@@ -2881,27 +2956,17 @@ export class SyncClient {
2881
2956
  // the journal cannot carry keeps its durable commitId, code and a bounded
2882
2957
  // `details.reason` instead of an opaque rewritten value.
2883
2958
  const representable = commit.operations.every(isStoredOperation);
2884
- const rejection = definedObject({
2885
- clientCommitId: commit.clientCommitId,
2886
- opIndex: 0,
2887
- code,
2888
- message,
2889
- retryable: false,
2890
- ...(representable ? { operation: commit.operations[0] } : {}),
2891
- ...(reason === undefined ? {} : { details: { reason } }),
2892
- });
2893
- this.#rejections.push(rejection);
2894
- recordCommitOutcome(this.#db, {
2895
- clientCommitId: commit.clientCommitId,
2896
- status: 'rejected',
2897
- recordedAtMs: this.#now(),
2898
- results: [{ status: 'error', rejection }],
2899
- ...(representable ? { operations: commit.operations } : {}),
2900
- });
2901
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
2902
- batch.status();
2903
- batch.rejections();
2904
- batch.outcomes();
2959
+ this.#journalDrop(batch, commit.clientCommitId, [
2960
+ definedObject({
2961
+ clientCommitId: commit.clientCommitId,
2962
+ opIndex: 0,
2963
+ code,
2964
+ message,
2965
+ retryable: false,
2966
+ operation: representable ? commit.operations[0] : undefined,
2967
+ details: reason === undefined ? undefined : { reason },
2968
+ }),
2969
+ ], representable ? commit.operations : undefined);
2905
2970
  }, undefined, (error) => {
2906
2971
  // The drop's own outcome write or publication failed: mirror the
2907
2972
  // rollback so no rejection the journal did not keep stays in memory.
@@ -2909,6 +2974,24 @@ export class SyncClient {
2909
2974
  throw error;
2910
2975
  });
2911
2976
  }
2977
+ /** §7.2: journal a dropped commit as rejected with these rejections. */
2978
+ #journalDrop(batch, clientCommitId, rejections, operations) {
2979
+ this.#rejections.push(...rejections);
2980
+ recordCommitOutcome(this.#db, definedObject({
2981
+ clientCommitId,
2982
+ status: 'rejected',
2983
+ recordedAtMs: this.#now(),
2984
+ results: rejections.map((rejection) => ({
2985
+ status: 'error',
2986
+ rejection,
2987
+ })),
2988
+ operations,
2989
+ }));
2990
+ pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
2991
+ batch.status();
2992
+ batch.rejections();
2993
+ batch.outcomes();
2994
+ }
2912
2995
  // -- sync -------------------------------------------------------------------
2913
2996
  /**
2914
2997
  * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
@@ -2997,36 +3080,23 @@ export class SyncClient {
2997
3080
  const errorCode = typeof code === 'string'
2998
3081
  ? this.#diagnosticCode(code)
2999
3082
  : 'client.unknown_failure';
3000
- const details = typeof error === 'object' && error !== null && 'details' in error
3001
- ? error.details
3002
- : undefined;
3003
- const rawCause = typeof details === 'object' &&
3004
- details !== null &&
3005
- 'causeKind' in details
3006
- ? details.causeKind
3007
- : undefined;
3008
- let causeKind;
3009
- switch (rawCause) {
3010
- case 'network':
3011
- case 'connect':
3012
- case 'tls':
3013
- case 'io':
3014
- case 'request':
3015
- case 'protocol':
3016
- case 'timeout':
3017
- case 'round_deadline':
3018
- case 'aborted':
3019
- case 'body':
3020
- case 'status':
3021
- case 'redirect':
3022
- case 'unknown':
3023
- causeKind = rawCause;
3024
- }
3025
- const rawStatus = typeof details === 'object' &&
3026
- details !== null &&
3027
- 'httpStatus' in details
3028
- ? details.httpStatus
3029
- : undefined;
3083
+ const rawCause = errorDetail(error, 'causeKind');
3084
+ const causeKind = [
3085
+ 'network',
3086
+ 'connect',
3087
+ 'tls',
3088
+ 'io',
3089
+ 'request',
3090
+ 'protocol',
3091
+ 'timeout',
3092
+ 'round_deadline',
3093
+ 'aborted',
3094
+ 'body',
3095
+ 'status',
3096
+ 'redirect',
3097
+ 'unknown',
3098
+ ].find((kind) => kind === rawCause);
3099
+ const rawStatus = errorDetail(error, 'httpStatus');
3030
3100
  const httpStatus = (causeKind === 'status' ||
3031
3101
  causeKind === 'body' ||
3032
3102
  causeKind === 'redirect') &&
@@ -3181,6 +3251,9 @@ export class SyncClient {
3181
3251
  cursor: unit.cursor,
3182
3252
  bootstrapState: unit.bootstrapState,
3183
3253
  }),
3254
+ ...(unit.restrict === undefined
3255
+ ? []
3256
+ : [{ type: 'RESTRICT', ...unit.restrict }]),
3184
3257
  ]),
3185
3258
  ];
3186
3259
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
@@ -3192,11 +3265,7 @@ export class SyncClient {
3192
3265
  // The fixed frames encode as envelope + fixed frames + END; each
3193
3266
  // admitted push frame adds its own (5 + payload). Trimming the tail
3194
3267
  // re-fits the request to the final registration state.
3195
- const fixedBytes = encodeRequest({
3196
- wireVersion: PROTOCOL_WIRE_VERSION,
3197
- msgKind: 'request',
3198
- frames: fixedFrames,
3199
- }).length;
3268
+ const fixedBytes = encodeRequestFrames(fixedFrames).length;
3200
3269
  if (fixedBytes > byteCap)
3201
3270
  throw this.#pushCapacityError('bytes', byteCap, fixedBytes);
3202
3271
  let admittedBytes = 0;
@@ -3218,11 +3287,7 @@ export class SyncClient {
3218
3287
  ...pushFrames,
3219
3288
  ...fixedFrames.slice(lead.length),
3220
3289
  ];
3221
- const requestBytes = encodeRequest({
3222
- wireVersion: PROTOCOL_WIRE_VERSION,
3223
- msgKind: 'request',
3224
- frames,
3225
- });
3290
+ const requestBytes = encodeRequestFrames(frames);
3226
3291
  const responseBytes = await this.#roundTrip(requestBytes, signal);
3227
3292
  const message = decodeResponse(responseBytes);
3228
3293
  // §1.5: a complete, decodable response ends the report obligation.
@@ -3275,16 +3340,7 @@ export class SyncClient {
3275
3340
  // transport, `network` from a browser fetch) is not a round worth
3276
3341
  // backing off for. Stop without scheduling an intent or growing the
3277
3342
  // delay; the host's own connectivity signal re-arms the drive.
3278
- const details = error instanceof ClientSyncError
3279
- ? error.details
3280
- : typeof error === 'object' && error !== null && 'details' in error
3281
- ? error.details
3282
- : undefined;
3283
- const causeKind = typeof details === 'object' &&
3284
- details !== null &&
3285
- 'causeKind' in details
3286
- ? details.causeKind
3287
- : undefined;
3343
+ const causeKind = errorDetail(error, 'causeKind');
3288
3344
  const unreachable = causeKind === 'connect' || causeKind === 'network';
3289
3345
  // The round's work is still owed; the host's connectivity resume runs it.
3290
3346
  if (unreachable)
@@ -3339,19 +3395,20 @@ export class SyncClient {
3339
3395
  if (timeoutMs !== Number.POSITIVE_INFINITY &&
3340
3396
  !(Number.isFinite(timeoutMs) && timeoutMs > 0))
3341
3397
  throw invalidRequest('timeoutMs must be a positive number or Infinity');
3342
- const key = `${maxRounds ?? 'default'}:${timeoutMs}`;
3398
+ const skipEmpty = typeof options === 'object' && options.skipEmpty === true;
3399
+ const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}`;
3343
3400
  const pending = this.#syncIdlePending.get(key);
3344
3401
  if (pending !== undefined)
3345
3402
  return pending;
3346
3403
  const previous = this.#syncIdleTail;
3347
3404
  let drive;
3348
3405
  if (previous === undefined) {
3349
- drive = this.#syncIdleRounds(maxRounds, timeoutMs);
3406
+ drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
3350
3407
  }
3351
3408
  else {
3352
3409
  drive = previous.then(() => {
3353
3410
  this.#syncIdlePending.delete(key);
3354
- return this.#syncIdleRounds(maxRounds, timeoutMs);
3411
+ return this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
3355
3412
  });
3356
3413
  this.#syncIdlePending.set(key, drive);
3357
3414
  }
@@ -3364,7 +3421,7 @@ export class SyncClient {
3364
3421
  return drive;
3365
3422
  }
3366
3423
  /** The rounds loop of one idle drive; `syncUntilIdle` owns coalescing. */
3367
- async #syncIdleRounds(maxRounds, timeoutMs) {
3424
+ async #syncIdleRounds(maxRounds, timeoutMs, skipEmpty) {
3368
3425
  const budget = maxRounds ?? 20;
3369
3426
  const aggregate = {
3370
3427
  ...emptySummary(0),
@@ -3381,6 +3438,22 @@ export class SyncClient {
3381
3438
  budgetExhausted,
3382
3439
  };
3383
3440
  };
3441
+ // §8.4: a replica without units, outbox work, or a server-side unit list
3442
+ // to clear has nothing to exchange; a host drive ends without a round.
3443
+ this.#requireActive();
3444
+ if (skipEmpty &&
3445
+ this.#schemaFloor === undefined &&
3446
+ !this.#hasStartupWork() &&
3447
+ loadUnits(this.#db).length === 0 &&
3448
+ (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined ||
3449
+ getMeta(this.#db, REGISTERED_DIGEST_KEY) ===
3450
+ bytesToHex(registrationDigest([])))) {
3451
+ this.#setSyncNeeded(false);
3452
+ return result(false);
3453
+ }
3454
+ // §7.2.2: decisions pending when the drive began are settled at its end.
3455
+ const decisions = pendingDecisions(this.#db);
3456
+ const start = decisions.length > 0 ? this.#driveStart() : undefined;
3384
3457
  const states = () => JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3385
3458
  const startedAtMs = this.#now();
3386
3459
  let completed = false;
@@ -3440,8 +3513,11 @@ export class SyncClient {
3440
3513
  aggregate.deferredCommits = last.deferredCommits ?? 0;
3441
3514
  aggregate.schemaFloor = last.schemaFloor;
3442
3515
  // A disabled transport or a schema floor ends the loop, not the budget.
3443
- if (!this.#transportEnabled || aggregate.schemaFloor)
3516
+ if (!this.#transportEnabled || aggregate.schemaFloor) {
3517
+ if (start !== undefined)
3518
+ this.#settleDecisions(decisions, start, result(false));
3444
3519
  return result(false);
3520
+ }
3445
3521
  if (maxRounds === undefined &&
3446
3522
  last.segmentRowsApplied > 0 &&
3447
3523
  last.bootstrapping.length > 0 &&
@@ -3453,6 +3529,9 @@ export class SyncClient {
3453
3529
  last.resets.length === 0 &&
3454
3530
  !aggregate.deferredCommits &&
3455
3531
  !this.#needsPull) {
3532
+ if (start !== undefined &&
3533
+ this.#settleDecisions(decisions, start, result(false)))
3534
+ continue;
3456
3535
  return result(false);
3457
3536
  }
3458
3537
  }
@@ -3629,7 +3708,7 @@ export class SyncClient {
3629
3708
  // A superseded attempt leaves the successor's (or the deliberate
3630
3709
  // disconnect's) state alone.
3631
3710
  if (generation === this.#realtimeGeneration) {
3632
- this.#setRealtimeState('refused', realtimeErrorCode(error));
3711
+ this.#setRealtimeState('refused', thrownCode(error));
3633
3712
  }
3634
3713
  throw error;
3635
3714
  }
@@ -3739,14 +3818,12 @@ export class SyncClient {
3739
3818
  const event = parsed.event;
3740
3819
  if (event.event === 'hello') {
3741
3820
  if (event.data.requiresSync) {
3742
- this.#setSyncNeeded(true);
3743
3821
  this.#emitSyncNeeded('hello');
3744
3822
  }
3745
3823
  return;
3746
3824
  }
3747
3825
  if (event.event === 'sync') {
3748
3826
  // §8.3: any wake-up means "run a pull soon", never data.
3749
- this.#setSyncNeeded(true);
3750
3827
  this.#emitSyncNeeded(event.data.reason);
3751
3828
  return;
3752
3829
  }
@@ -3809,7 +3886,6 @@ export class SyncClient {
3809
3886
  transportEpoch !== this.#transportEpoch)
3810
3887
  return;
3811
3888
  if (resetEpoch !== this.#localResetEpoch) {
3812
- this.#setSyncNeeded(true);
3813
3889
  this.#emitSyncNeeded('catchup-required');
3814
3890
  return;
3815
3891
  }
@@ -3820,7 +3896,6 @@ export class SyncClient {
3820
3896
  }
3821
3897
  catch {
3822
3898
  // A delta that cannot be applied is recovered by a pull (§8.3).
3823
- this.#setSyncNeeded(true);
3824
3899
  this.#emitSyncNeeded('catchup-required');
3825
3900
  }
3826
3901
  });
@@ -3904,11 +3979,12 @@ export class SyncClient {
3904
3979
  let receivers = [];
3905
3980
  // §5.4/§5.5: queue every segment download of this response, so a paged
3906
3981
  // bootstrap overlaps its page fetches instead of paying one blocking round
3907
- // trip per page. At most four downloads run at once, the Rust native
3908
- // transport's pool size: enough to overlap round trips, while the client
3909
- // holds at most four bodies, the one being applied and three ahead. An
3910
- // image starts only beside at most one other body, so at most two are
3911
- // images (§5.3 client memory); later descriptors wait in order. The
3982
+ // trip per page. `limits.segmentPrefetch` downloads run at once, by
3983
+ // default four, the Rust native transport's pool size: enough to overlap
3984
+ // round trips, while the client holds that many bodies, the one being
3985
+ // applied and the rest ahead. An image starts only beside at most one
3986
+ // other body, so at most two are images (§5.3 client memory) whatever the
3987
+ // limit; later descriptors wait in order. The
3912
3988
  // loop takes each body out of the map before applying it and tops the
3913
3989
  // window up at the next descriptor. Eligibility mirrors the loop: a
3914
3990
  // descriptor outside an applied section or from an unconfigured
@@ -3918,7 +3994,7 @@ export class SyncClient {
3918
3994
  const queued = [];
3919
3995
  const prefetched = new Map();
3920
3996
  const prefetch = () => {
3921
- for (let next; prefetched.size < 4 &&
3997
+ for (let next; prefetched.size < (this.#config.limits?.segmentPrefetch ?? 4) &&
3922
3998
  !(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
3923
3999
  (next = queued.shift());) {
3924
4000
  const [frame, scopes] = next;
@@ -4031,11 +4107,16 @@ export class SyncClient {
4031
4107
  skip: false,
4032
4108
  }
4033
4109
  : undefined;
4034
- // §7.7: a section boundary ends the previous payload.
4110
+ // §7.7: a section boundary ends the previous payload; the same
4111
+ // snapshot takes the section's extent (§4.4).
4112
+ const extent = message.frames[index + 1];
4113
+ const stated = section !== undefined && extent?.type === 'UNIT_EXTENT';
4035
4114
  this.#progress.update({
4036
4115
  ...NO_PAYLOAD,
4037
4116
  phase: 'import',
4038
4117
  unitId: section?.unit.id,
4118
+ unitRowsTotal: stated ? extent.rowsTotal : undefined,
4119
+ unitRowsProcessed: stated ? extent.rowsDone : undefined,
4039
4120
  });
4040
4121
  break;
4041
4122
  }
@@ -4059,20 +4140,23 @@ export class SyncClient {
4059
4140
  // §5.6: rows an earlier attempt at this position applied. A
4060
4141
  // partly applied image already ran its table's first-page clear.
4061
4142
  appliedRows = section.unit.applied?.[frame.segmentId];
4062
- if (appliedRows !== undefined) {
4143
+ if (appliedRows !== undefined)
4063
4144
  section.seeded.add(frame.table);
4064
- if (appliedRows === frame.rowCount)
4065
- break;
4066
- }
4145
+ const imported = appliedRows === frame.rowCount;
4067
4146
  this.#progress.update({
4068
4147
  ...NO_PAYLOAD,
4069
- phase: 'download',
4148
+ phase: imported ? 'import' : 'download',
4070
4149
  unitId,
4071
4150
  table: frame.table,
4072
4151
  segmentId: frame.segmentId,
4073
- bytesTotal: frame.byteLength,
4152
+ bytesTotal: imported ? undefined : frame.byteLength,
4074
4153
  rowsTotal: frame.rowCount,
4075
4154
  });
4155
+ if (imported) {
4156
+ // §7.7: an earlier attempt imported this payload.
4157
+ this.#progress.update({ rowsProcessed: frame.rowCount });
4158
+ break;
4159
+ }
4076
4160
  prefetch();
4077
4161
  const pending = prefetched.get(frame);
4078
4162
  prefetched.delete(frame);
@@ -4087,10 +4171,7 @@ export class SyncClient {
4087
4171
  // catching up with its cursor unpersisted, and the next
4088
4172
  // round's SUB_START settles it (revoked or a new bootstrap).
4089
4173
  // A host downloader may throw any error carrying the code.
4090
- if (typeof error !== 'object' ||
4091
- error === null ||
4092
- !('code' in error) ||
4093
- error.code !== 'sync.forbidden')
4174
+ if (thrownCode(error) !== 'sync.forbidden')
4094
4175
  throw error;
4095
4176
  section.skip = true;
4096
4177
  break;
@@ -4135,6 +4216,10 @@ export class SyncClient {
4135
4216
  !section.skip &&
4136
4217
  this.#localResetEpoch === resetEpoch) {
4137
4218
  this.#finishSection(section, frame, summary);
4219
+ // §7.7: a completed bootstrap ends at what it imported.
4220
+ const processed = this.#progress.snapshot()?.unitRowsProcessed;
4221
+ if (frame.bootstrapState === undefined && processed !== undefined)
4222
+ this.#progress.update({ unitRowsTotal: processed });
4138
4223
  }
4139
4224
  section = undefined;
4140
4225
  // The counters stay: `complete` and `failed` report them.
@@ -4281,7 +4366,6 @@ export class SyncClient {
4281
4366
  this.#sendAck(deltaCursor);
4282
4367
  // §8.2: an unapplied delta is a drop; a pull repairs it.
4283
4368
  if (deltaDropped) {
4284
- this.#setSyncNeeded(true);
4285
4369
  this.#emitSyncNeeded('catchup-required');
4286
4370
  }
4287
4371
  }
@@ -4349,10 +4433,7 @@ export class SyncClient {
4349
4433
  return true;
4350
4434
  }
4351
4435
  // rejected
4352
- const cacheMiss = frame.results.some((result) => result.status === 'error' &&
4353
- result.code === 'sync.idempotency_cache_miss' &&
4354
- result.retryable);
4355
- if (cacheMiss) {
4436
+ if (!isFinalPushResult(frame)) {
4356
4437
  // §6.3: a serving failure, not the commit's outcome — keep the
4357
4438
  // commit queued and retry the identical push later.
4358
4439
  summary.retryable.push(frame.clientCommitId);
@@ -4362,6 +4443,8 @@ export class SyncClient {
4362
4443
  for (const result of frame.results) {
4363
4444
  const operation = commit.operations[result.opIndex];
4364
4445
  if (result.status === 'conflict') {
4446
+ const columns = this.#schema.tables.get(operation?.table ?? '')?.columns ?? [];
4447
+ const values = columns.length === 0 ? [] : decodeRow(columns, result.serverRow);
4365
4448
  const conflict = definedObject({
4366
4449
  clientCommitId: frame.clientCommitId,
4367
4450
  opIndex: result.opIndex,
@@ -4370,8 +4453,16 @@ export class SyncClient {
4370
4453
  code: result.code,
4371
4454
  message: result.message,
4372
4455
  serverVersion: result.serverVersion,
4373
- serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
4374
- conflictColumns: this.#decodeConflictColumns(operation?.table, result.conflictColumns),
4456
+ serverRow: Object.fromEntries(columns.map((column, index) => [
4457
+ column.name,
4458
+ values[index] ?? null,
4459
+ ])),
4460
+ // §6.3: the presence-layout bitmap names the present columns whose
4461
+ // `column_version` exceeded `baseVersion`; a custom merge
4462
+ // recomputes exactly these (§6.5).
4463
+ conflictColumns: columns
4464
+ .filter((_, index) => ((result.conflictColumns[index >> 3] ?? 0) >> (index & 7)) & 1)
4465
+ .map((column) => column.name),
4375
4466
  operation: operation,
4376
4467
  });
4377
4468
  this.#conflicts.push(conflict);
@@ -4437,38 +4528,6 @@ export class SyncClient {
4437
4528
  #outboxCommitExists(clientCommitId) {
4438
4529
  return (this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [clientCommitId]).length > 0);
4439
4530
  }
4440
- #decodeServerRow(tableName, payload) {
4441
- if (tableName === undefined)
4442
- return {};
4443
- const table = this.#schema.tables.get(tableName);
4444
- if (table === undefined)
4445
- return {};
4446
- const values = decodeRow(table.columns, payload);
4447
- const record = {};
4448
- table.columns.forEach((column, index) => {
4449
- record[column.name] = values[index] ?? null;
4450
- });
4451
- return record;
4452
- }
4453
- /**
4454
- * §6.3 `conflictColumns`: decode the presence-layout bitmap into the names
4455
- * of the present columns whose `column_version` exceeded `baseVersion`. A
4456
- * custom merge recomputes exactly these columns (§6.5).
4457
- */
4458
- #decodeConflictColumns(tableName, bitmap) {
4459
- if (tableName === undefined)
4460
- return [];
4461
- const table = this.#schema.tables.get(tableName);
4462
- if (table === undefined)
4463
- return [];
4464
- const names = [];
4465
- table.columns.forEach((column, index) => {
4466
- const byte = bitmap[index >> 3] ?? 0;
4467
- if (((byte >> (index & 7)) & 1) === 1)
4468
- names.push(column.name);
4469
- });
4470
- return names;
4471
- }
4472
4531
  async #applyCommit(frame, summary, source) {
4473
4532
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4474
4533
  this.#recordCommitChanges(batch, frame);
@@ -4585,8 +4644,15 @@ export class SyncClient {
4585
4644
  // §3.3 owners matter only for rows the clear would reach, so a pair
4586
4645
  // with no matching local or retained row never reads the unit list.
4587
4646
  let owners;
4647
+ const clearFirst = !section.seeded.has(tableName);
4648
+ // §5.6: a first page outside the restriction is a whole bootstrap from a
4649
+ // server that predates RESTRICT; the restriction ends before the clear.
4650
+ if (clearFirst && unit.restrict?.tables.includes(tableName) === false)
4651
+ this.#db.exec(`UPDATE ${UNITS_TABLE} SET restriction=NULL WHERE id=?`, [
4652
+ unit.id,
4653
+ ]);
4588
4654
  try {
4589
- summary.segmentRowsApplied += await apply(table, !section.seeded.has(tableName), effective, () => (owners ??=
4655
+ summary.segmentRowsApplied += await apply(table, clearFirst, effective, () => (owners ??=
4590
4656
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [table.name]).length > 0 || this.#scopedRowsExist(table, effective, [])
4591
4657
  ? unitOwners(loadUnits(this.#db), table, unit.id)
4592
4658
  : []));
@@ -4605,6 +4671,7 @@ export class SyncClient {
4605
4671
  ...current,
4606
4672
  status: 'failed',
4607
4673
  reasonCode: 'sync.scope_revoked',
4674
+ restrict: undefined,
4608
4675
  });
4609
4676
  for (const ref of windowRefs(this.#db, unit.id))
4610
4677
  batch.window(ref.baseKey, ref.value);
@@ -4657,8 +4724,7 @@ export class SyncClient {
4657
4724
  throw invalidRequest('segment exceeds its byteLength', true);
4658
4725
  }
4659
4726
  onProgress(bytes.byteLength);
4660
- const hash = await sha256Hex(bytes);
4661
- if (`sha256:${hash}` !== frame.segmentId) {
4727
+ if ((await computeBlobId(bytes)) !== frame.segmentId) {
4662
4728
  throw invalidRequest('segment failed content-address verification (§5.1)', true);
4663
4729
  }
4664
4730
  return bytes;
@@ -4686,9 +4752,7 @@ export class SyncClient {
4686
4752
  saveUnit(this.#db, {
4687
4753
  ...unit,
4688
4754
  reasonCode: start.reasonCode,
4689
- cursor: -1,
4690
- bootstrapState: undefined,
4691
- seeded: [],
4755
+ ...UNIT_RESTART,
4692
4756
  });
4693
4757
  summary.resets.push(unit.id);
4694
4758
  return;
@@ -4719,10 +4783,8 @@ export class SyncClient {
4719
4783
  ...unit,
4720
4784
  status: failed ? 'failed' : 'revoked',
4721
4785
  reasonCode: failed ? 'sync.scope_revoked' : start.reasonCode,
4722
- cursor: -1,
4723
- bootstrapState: undefined,
4724
- seeded: [],
4725
4786
  echo: undefined,
4787
+ ...UNIT_RESTART,
4726
4788
  });
4727
4789
  if (revoked)
4728
4790
  summary.revoked.push(unit.id);
@@ -4736,13 +4798,17 @@ export class SyncClient {
4736
4798
  ...unit,
4737
4799
  reasonCode: undefined,
4738
4800
  echo: start.fenced,
4801
+ // §7.4.3: a rearm and a completed bootstrap end the restriction.
4739
4802
  ...(rearmed
4740
- ? { cursor: -1, bootstrapState: undefined, seeded: [] }
4803
+ ? UNIT_RESTART
4741
4804
  : start.bootstrap
4742
4805
  ? {
4743
4806
  cursor: end.nextCursor,
4744
4807
  bootstrapState: end.bootstrapState,
4745
4808
  seeded: end.bootstrapState === undefined ? [] : [...section.seeded],
4809
+ ...(end.bootstrapState === undefined
4810
+ ? { restrict: undefined }
4811
+ : {}),
4746
4812
  }
4747
4813
  : {}),
4748
4814
  });
@@ -4791,34 +4857,16 @@ export class SyncClient {
4791
4857
  const doomed = listOutbox(this.#db).filter((commit) => commit.operations.some((op) => op.table === table.name &&
4792
4858
  op.values !== undefined &&
4793
4859
  ownsLocalRow(table, lastEffective, owners, op.values)));
4794
- for (const commit of doomed) {
4795
- const { clientCommitId } = commit;
4860
+ for (const { clientCommitId, operations } of doomed) {
4796
4861
  deleteOutboxCommit(this.#db, clientCommitId);
4797
- const results = commit.operations.map((operation, opIndex) => {
4798
- const rejection = {
4799
- clientCommitId,
4800
- opIndex,
4801
- code: 'sync.scope_revoked',
4802
- message: 'the commit was dropped because its effective scope was revoked',
4803
- retryable: false,
4804
- operation,
4805
- };
4806
- this.#rejections.push(rejection);
4807
- return { status: 'error', rejection };
4808
- });
4809
- recordCommitOutcome(this.#db, {
4862
+ this.#journalDrop(batch, clientCommitId, operations.map((operation, opIndex) => ({
4810
4863
  clientCommitId,
4811
- status: 'rejected',
4812
- recordedAtMs: this.#now(),
4813
- results,
4814
- operations: commit.operations,
4815
- });
4816
- }
4817
- if (doomed.length > 0) {
4818
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4819
- batch.status();
4820
- batch.rejections();
4821
- batch.outcomes();
4864
+ opIndex,
4865
+ code: 'sync.scope_revoked',
4866
+ message: 'the commit was dropped because its effective scope was revoked',
4867
+ retryable: false,
4868
+ operation,
4869
+ })), operations);
4822
4870
  }
4823
4871
  this.#replayOutbox(scope);
4824
4872
  this.#deleteUnreferencedBlobs();
@@ -4849,14 +4897,13 @@ export class SyncClient {
4849
4897
  }
4850
4898
  const syncVersion = row[SYNC_VERSION_COLUMN];
4851
4899
  if (typeof syncVersion !== 'number') {
4852
- throw new ClientSyncError('sync.local_corrupt', `local row ${operation.table}/${operation.rowId} has no sync version`);
4900
+ throw localStateCorrupt(`local row ${operation.table}/${operation.rowId} has no sync version`);
4853
4901
  }
4854
4902
  return { opIndex, existed: true, syncVersion, values };
4855
4903
  }
4856
4904
  /** `onlyKeys` holds overlay row keys (`JSON [table,rowId]`). */
4857
4905
  #captureBeforeImages(operations, onlyKeys) {
4858
- return operations.flatMap((operation, opIndex) => onlyKeys &&
4859
- !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
4906
+ return operations.flatMap((operation, opIndex) => onlyKeys && !onlyKeys.has(rowKey(operation))
4860
4907
  ? []
4861
4908
  : [this.#captureBeforeImage(operation, opIndex)]);
4862
4909
  }
@@ -4870,10 +4917,10 @@ export class SyncClient {
4870
4917
  return;
4871
4918
  }
4872
4919
  if (image.values === undefined || image.syncVersion === undefined) {
4873
- throw new ClientSyncError('sync.local_corrupt', `rollback image for ${operation.table}/${operation.rowId} is incomplete`);
4920
+ throw localStateCorrupt(`rollback image for ${operation.table}/${operation.rowId} is incomplete`);
4874
4921
  }
4875
4922
  const values = table.columns.map((column) => jsonToRowValue(image.values?.[column.name] ?? null));
4876
- upsertLocalRow(this.#db, table, values, image.syncVersion, false);
4923
+ upsertLocalRow(this.#db, table, values, image.syncVersion);
4877
4924
  }
4878
4925
  #legacyUndoOptimisticRows(commit, batch) {
4879
4926
  for (const operation of commit.operations) {
@@ -4893,17 +4940,14 @@ export class SyncClient {
4893
4940
  const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
4894
4941
  const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
4895
4942
  const complete = commit.operations.every((_, index) => imageByIndex.has(index));
4896
- const affectedKeys = new Set(commit.operations.map((operation) => JSON.stringify([operation.table, operation.rowId])));
4943
+ const affectedKeys = new Set(commit.operations.map(rowKey));
4897
4944
  if (complete) {
4898
- const restored = new Set();
4945
+ // The first operation on a row holds its pre-commit image.
4946
+ const unrestored = new Set(affectedKeys);
4899
4947
  commit.operations.forEach((operation, index) => {
4900
- const key = JSON.stringify([operation.table, operation.rowId]);
4901
- if (restored.has(key))
4902
- return;
4903
4948
  const image = imageByIndex.get(index);
4904
- if (image)
4949
+ if (unrestored.delete(rowKey(operation)) && image)
4905
4950
  this.#restoreBeforeImage(operation, image, batch);
4906
- restored.add(key);
4907
4951
  });
4908
4952
  }
4909
4953
  else {
@@ -4917,7 +4961,7 @@ export class SyncClient {
4917
4961
  for (const later of listOutbox(this.#db, [...affectedKeys])) {
4918
4962
  if (later.seq <= commit.seq)
4919
4963
  continue;
4920
- const affectedOperations = later.operations.filter((operation) => affectedKeys.has(JSON.stringify([operation.table, operation.rowId])));
4964
+ const affectedOperations = later.operations.filter((operation) => affectedKeys.has(rowKey(operation)));
4921
4965
  if (affectedOperations.length === 0)
4922
4966
  continue;
4923
4967
  replaceOutboxBeforeImages(this.#db, later, this.#captureBeforeImages(later.operations, affectedKeys));
@@ -4943,15 +4987,8 @@ export class SyncClient {
4943
4987
  : this.#table(op.table);
4944
4988
  if (table === undefined)
4945
4989
  continue;
4946
- let precise = batch === undefined
4947
- ? false
4948
- : this.#recordStoredRowScopes(batch, table, op.rowId);
4949
- if (op.op === 'delete') {
4950
- if (batch !== undefined && !precise)
4951
- batch.table(op.table);
4952
- deleteLocalRow(this.#db, table, op.rowId, false);
4953
- continue;
4954
- }
4990
+ let precise = batch !== undefined &&
4991
+ this.#recordStoredRowScopes(batch, table, op.rowId);
4955
4992
  // §7.1 overlay: apply the operation's PRESENT columns over the current
4956
4993
  // local row. A partial operation over an absent local row leaves it
4957
4994
  // absent — the server answers it with sync.row_deleted or
@@ -4960,18 +4997,17 @@ export class SyncClient {
4960
4997
  const opValues = op.values ?? {};
4961
4998
  const full = op.insert === true ||
4962
4999
  table.columns.every((column) => column.name in opValues);
5000
+ const local = op.op === 'delete' ? undefined : this.#rowById(table, op.rowId);
4963
5001
  // An insert lacking a non-nullable column cannot encode (§7.4.4); it
4964
5002
  // stays hidden until the send-time drop classifies it.
4965
- if (op.insert === true &&
4966
- table.columns.some((column) => !column.nullable && opValues[column.name] === undefined)) {
4967
- if (batch !== undefined && !precise)
4968
- batch.table(op.table);
4969
- continue;
4970
- }
4971
- const local = this.#rowById(table, op.rowId);
4972
- if (local === undefined && !full) {
5003
+ if (op.op === 'delete' ||
5004
+ (op.insert === true &&
5005
+ table.columns.some((column) => !column.nullable && opValues[column.name] === undefined)) ||
5006
+ (local === undefined && !full)) {
4973
5007
  if (batch !== undefined && !precise)
4974
5008
  batch.table(op.table);
5009
+ if (op.op === 'delete')
5010
+ deleteLocalRow(this.#db, table, op.rowId, false);
4975
5011
  continue;
4976
5012
  }
4977
5013
  const values = table.columns.map((column) => {
@@ -4994,7 +5030,7 @@ export class SyncClient {
4994
5030
  })), values);
4995
5031
  }
4996
5032
  catch {
4997
- throw new ClientSyncError('sync.local_corrupt', 'persisted optimistic row value is invalid');
5033
+ throw localStateCorrupt('persisted optimistic row value is invalid');
4998
5034
  }
4999
5035
  }
5000
5036
  // Record the row's scope keys from its scope columns (I2 refinement).
@@ -5021,7 +5057,7 @@ export class SyncClient {
5021
5057
  values[index] ?? null,
5022
5058
  ]))).length)
5023
5059
  continue;
5024
- upsertLocalRow(this.#db, table, values, version, false);
5060
+ upsertLocalRow(this.#db, table, values, version);
5025
5061
  }
5026
5062
  }
5027
5063
  /** Re-apply every pending outbox commit on top of server state (§7.1). */
@@ -5035,7 +5071,7 @@ export class SyncClient {
5035
5071
  this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
5036
5072
  for (const op of commit.operations) {
5037
5073
  batch.table(op.table);
5038
- scope.push(JSON.stringify([op.table, op.rowId]));
5074
+ scope.push(rowKey(op));
5039
5075
  }
5040
5076
  }
5041
5077
  return scope;
@@ -5144,7 +5180,7 @@ export class SyncClient {
5144
5180
  if (rebased !== undefined && outbox.has(commit))
5145
5181
  replaceOutboxBeforeImages(this.#db, commit, this.#captureBeforeImages(commit.operations, rebased));
5146
5182
  this.#applyOperationsLocally(commit.operations.filter((op) => scope === undefined ||
5147
- scope.includes(JSON.stringify([op.table, op.rowId])) ||
5183
+ scope.includes(rowKey(op)) ||
5148
5184
  scope.includes(JSON.stringify([op.table]))), batch, true);
5149
5185
  }
5150
5186
  };