@syncular/client 0.86.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 (45) hide show
  1. package/README.md +3 -1
  2. package/dist/blob.d.ts +0 -4
  3. package/dist/blob.js +7 -22
  4. package/dist/client.d.ts +12 -1
  5. package/dist/client.js +441 -422
  6. package/dist/diagnostics.d.ts +2 -4
  7. package/dist/diagnostics.js +3 -17
  8. package/dist/encryption.js +2 -21
  9. package/dist/errors.d.ts +2 -0
  10. package/dist/errors.js +4 -0
  11. package/dist/failed-overlay.js +2 -2
  12. package/dist/local-purge.d.ts +1 -0
  13. package/dist/local-purge.js +1 -1
  14. package/dist/local-rebootstrap-receipt.js +2 -2
  15. package/dist/local-rebootstrap.js +1 -1
  16. package/dist/native-bridge.d.ts +6 -2
  17. package/dist/native-bridge.js +24 -11
  18. package/dist/outcomes.d.ts +11 -0
  19. package/dist/outcomes.js +19 -16
  20. package/dist/previous-version.js +23 -35
  21. package/dist/schema.js +14 -13
  22. package/dist/state.d.ts +16 -4
  23. package/dist/state.js +83 -44
  24. package/dist/worker-core.js +7 -8
  25. package/dist/worker-host.d.ts +5 -2
  26. package/dist/worker-host.js +9 -0
  27. package/dist/worker-protocol.d.ts +2 -1
  28. package/package.json +3 -3
  29. package/src/blob.ts +7 -24
  30. package/src/client.ts +615 -501
  31. package/src/diagnostics.ts +3 -19
  32. package/src/encryption.ts +7 -25
  33. package/src/errors.ts +5 -0
  34. package/src/failed-overlay.ts +2 -6
  35. package/src/local-purge.ts +1 -1
  36. package/src/local-rebootstrap-receipt.ts +2 -5
  37. package/src/local-rebootstrap.ts +1 -2
  38. package/src/native-bridge.ts +35 -13
  39. package/src/outcomes.ts +34 -25
  40. package/src/previous-version.ts +31 -40
  41. package/src/schema.ts +13 -13
  42. package/src/state.ts +107 -64
  43. package/src/worker-core.ts +9 -16
  44. package/src/worker-host.ts +17 -1
  45. package/src/worker-protocol.ts +2 -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,8 +160,8 @@ 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
  }
@@ -293,18 +317,16 @@ export class SyncClient {
293
317
  throw invalidRequest('transportEnabled must be a boolean');
294
318
  }
295
319
  this.#transportEnabled = config.transportEnabled !== false;
296
- for (const [name, value] of [
297
- ['maxPushCommitsPerRequest', config.limits?.maxPushCommitsPerRequest],
298
- [
299
- 'maxPushOperationsPerRequest',
300
- config.limits?.maxPushOperationsPerRequest,
301
- ],
302
- ['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
303
- ['segmentPrefetch', config.limits?.segmentPrefetch],
320
+ for (const name of [
321
+ 'maxPushCommitsPerRequest',
322
+ 'maxPushOperationsPerRequest',
323
+ 'maxPushRequestBytes',
324
+ 'segmentPrefetch',
304
325
  ]) {
326
+ const value = config.limits?.[name];
305
327
  if (value !== undefined &&
306
328
  (!Number.isInteger(value) || value < 1 || value > 0xffffffff)) {
307
- throw new ClientSyncError('sync.invalid_request', '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 });
308
330
  }
309
331
  }
310
332
  if (config.securityPreflight === true && config.encryption !== undefined) {
@@ -389,31 +411,28 @@ export class SyncClient {
389
411
  try {
390
412
  const meta = this.#db.query("SELECT type FROM sqlite_master WHERE name = '_syncular_meta'")[0];
391
413
  if (meta !== undefined) {
392
- if (meta.type !== 'table')
393
- throw new Error('invalid metadata table');
394
- const rows = this.#db.query('SELECT value FROM _syncular_meta WHERE key = ?', [LOCAL_SCHEMA_VERSION_KEY]);
395
- // A duplicated marker cannot be resolved. Picking one row could
396
- // select an older version and drive a destructive reset over a
397
- // newer replica.
398
- 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))
399
433
  throw new Error('invalid schema marker');
400
- const row = rows[0];
401
- if (row === undefined &&
402
- this.#db.query("SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1").length > 0) {
403
- throw new Error('missing paired schema marker');
404
- }
405
- if (row !== undefined) {
406
- const value = row.value;
407
- const version = Number(value);
408
- if (typeof value !== 'string' ||
409
- !Number.isInteger(version) ||
410
- version < 1 ||
411
- version > 2147483647 ||
412
- String(version) !== value) {
413
- throw new Error('invalid schema marker');
414
- }
434
+ if (value !== undefined)
415
435
  marker = version;
416
- }
417
436
  }
418
437
  }
419
438
  catch (error) {
@@ -423,7 +442,7 @@ export class SyncClient {
423
442
  const failure = classifySqliteFailure(error);
424
443
  if (failure.code !== undefined)
425
444
  throw failure.error;
426
- 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');
427
446
  }
428
447
  if (marker !== undefined && marker > this.#schema.version) {
429
448
  throw new ClientSyncError('client.schema_downgrade', 'persisted local schema is newer than the requested schema', false, {
@@ -494,7 +513,6 @@ export class SyncClient {
494
513
  if (this.#securityLifecycle === 'active' && this.#hasStartupWork()) {
495
514
  this.#needsPull = true;
496
515
  this.#emitSyncNeeded('startup');
497
- this.#emitSyncIntent({ kind: 'interactive' });
498
516
  }
499
517
  // Console introspection is a no-op outside a dev page.
500
518
  this.#devtoolsUnregister = this.#config.devtools?.({
@@ -521,28 +539,19 @@ export class SyncClient {
521
539
  * marker, so the shape chosen here commits under that snapshot.
522
540
  */
523
541
  #detectAndResetSchema(marker) {
524
- if (marker === undefined) {
525
- // Fresh install: the tables just created match the running code.
526
- this.#db.transaction(() => {
527
- 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)
528
551
  setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
529
- setLocalSchemaDescriptor(this.#db, this.#schema);
530
- saveUnitScopeSchema(this.#db, this.#schema);
531
- });
532
- return;
533
- }
534
- if (marker === this.#schema.version) {
535
- // Same-version opens remain self-healing for absent tables/indexes, and
536
- // RFC 0005 D1 backfills the descriptor for a database first opened by
537
- // 0.22.0 or earlier WITHOUT a schema bump.
538
- this.#db.transaction(() => {
539
- ensureLocalSyncedSchema(this.#db, this.#schema);
540
- setLocalSchemaDescriptor(this.#db, this.#schema);
541
- saveUnitScopeSchema(this.#db, this.#schema);
542
- });
543
- return;
544
- }
545
- this.#runSchemaReset();
552
+ setLocalSchemaDescriptor(this.#db, this.#schema);
553
+ saveUnitScopeSchema(this.#db, this.#schema);
554
+ });
546
555
  }
547
556
  /**
548
557
  * §7.4.3 reset: whole-database local reset EXCEPT the outbox, clientId,
@@ -642,9 +651,7 @@ export class SyncClient {
642
651
  #runLogEpochReset(logEpoch) {
643
652
  if (getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined) {
644
653
  this.#applyBatch(() => setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch));
645
- this.#setSyncNeeded(true);
646
654
  this.#emitSyncNeeded('startup');
647
- this.#emitSyncIntent({ kind: 'interactive' });
648
655
  return [];
649
656
  }
650
657
  const units = loadUnits(this.#db);
@@ -675,9 +682,7 @@ export class SyncClient {
675
682
  throw error;
676
683
  });
677
684
  this.#localResetEpoch += 1;
678
- this.#setSyncNeeded(true);
679
685
  this.#emitSyncNeeded('startup');
680
- this.#emitSyncIntent({ kind: 'interactive' });
681
686
  return units.map((unit) => unit.id);
682
687
  }
683
688
  #setUpgrading(upgrading) {
@@ -719,36 +724,35 @@ export class SyncClient {
719
724
  this.#syncNeededListeners.clear();
720
725
  this.#syncIntentListeners.clear();
721
726
  }
727
+ /** Mark a pull as needed and tell the host; a startup wake also asks for
728
+ * an interactive round. */
722
729
  #emitSyncNeeded(reason) {
730
+ this.#setSyncNeeded(true);
723
731
  if (!this.#transportEnabled)
724
732
  return;
725
- try {
726
- this.#config.onSyncNeeded?.(reason);
727
- }
728
- catch {
729
- // An observer cannot alter sync correctness.
730
- }
731
- for (const listener of this.#syncNeededListeners) {
733
+ for (const listener of [
734
+ this.#config.onSyncNeeded,
735
+ ...this.#syncNeededListeners,
736
+ ]) {
732
737
  try {
733
- listener(reason);
738
+ listener?.(reason);
734
739
  }
735
740
  catch {
736
741
  // An observer cannot alter sync correctness.
737
742
  }
738
743
  }
744
+ if (reason === 'startup')
745
+ this.#emitSyncIntent({ kind: 'interactive' });
739
746
  }
740
747
  #emitSyncIntent(intent) {
741
748
  if (!this.#transportEnabled && intent.kind !== 'none')
742
749
  return;
743
- try {
744
- this.#config.onSyncIntent?.(intent);
745
- }
746
- catch {
747
- // An observer cannot alter sync correctness.
748
- }
749
- for (const listener of this.#syncIntentListeners) {
750
+ for (const listener of [
751
+ this.#config.onSyncIntent,
752
+ ...this.#syncIntentListeners,
753
+ ]) {
750
754
  try {
751
- listener(intent);
755
+ listener?.(intent);
752
756
  }
753
757
  catch {
754
758
  // An observer cannot alter sync correctness.
@@ -803,13 +807,11 @@ export class SyncClient {
803
807
  this.#syncOutstanding = false;
804
808
  })();
805
809
  this.#preflightBarrier = barrier;
806
- void barrier.then(() => {
810
+ const release = () => {
807
811
  if (this.#preflightBarrier === barrier)
808
812
  this.#preflightBarrier = undefined;
809
- }, () => {
810
- if (this.#preflightBarrier === barrier)
811
- this.#preflightBarrier = undefined;
812
- });
813
+ };
814
+ void barrier.then(release, release);
813
815
  return barrier;
814
816
  }
815
817
  /**
@@ -832,9 +834,7 @@ export class SyncClient {
832
834
  });
833
835
  await this.#serialize(() => this.#revealSealed());
834
836
  if (this.#hasStartupWork()) {
835
- this.#setSyncNeeded(true);
836
837
  this.#emitSyncNeeded('startup');
837
- this.#emitSyncIntent({ kind: 'interactive' });
838
838
  }
839
839
  }
840
840
  /** Persisted work an opened or activated replica owes one round (§8.4). */
@@ -949,7 +949,7 @@ export class SyncClient {
949
949
  return { state: 'unknown', id };
950
950
  const cursor = unit.cursor ?? replicaCursor(this.#db);
951
951
  if (!Number.isSafeInteger(cursor))
952
- throw new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
952
+ throw unitStateCorrupt();
953
953
  const active = unit.status === 'active';
954
954
  const pending = bootstrapping(unit);
955
955
  return definedObject({
@@ -1054,34 +1054,29 @@ export class SyncClient {
1054
1054
  return this.#previousVersionUnavailable(currentVersion, 'not-configured');
1055
1055
  }
1056
1056
  const record = this.#readPreviousVersionRecord();
1057
- const nowMs = this.#now();
1058
- if (this.#previousVersionLeaseInactive(nowMs)) {
1059
- this.#discardPreviousVersion();
1060
- return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
1061
- }
1062
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1063
- this.#discardPreviousVersion();
1064
- return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
1065
- }
1066
1057
  // Coverage completion is a live predicate: the container is normally
1067
1058
  // dropped by the sync path first, so a read can be the first observer.
1068
- if (this.#previousVersionCoverageComplete()) {
1069
- this.#discardPreviousVersion();
1070
- return this.#previousVersionUnavailable(currentVersion, 'coverage-complete');
1071
- }
1072
- if (record === undefined) {
1073
- const refusal = storedPreviousVersionRefusal(this.#db);
1074
- return this.#previousVersionUnavailable(currentVersion, refusal?.reason ?? 'no-previous-descriptor');
1075
- }
1076
- if (record.currentVersion !== currentVersion) {
1077
- this.#discardPreviousVersion();
1078
- return this.#previousVersionUnavailable(currentVersion, 'no-previous-descriptor');
1079
- }
1080
- if (nowMs - record.createdAtMs >
1081
- 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) {
1082
1074
  this.#discardPreviousVersion();
1083
- return this.#previousVersionUnavailable(currentVersion, 'expired');
1075
+ return this.#previousVersionUnavailable(currentVersion, ended);
1084
1076
  }
1077
+ if (record === undefined)
1078
+ return this.#previousVersionUnavailable(currentVersion, storedPreviousVersionRefusal(this.#db)?.reason ??
1079
+ 'no-previous-descriptor');
1085
1080
  const table = record.tables.find((entry) => entry.name === spec.table);
1086
1081
  if (table === undefined) {
1087
1082
  throw invalidRequest(`previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`);
@@ -1188,20 +1183,16 @@ export class SyncClient {
1188
1183
  return;
1189
1184
  }
1190
1185
  const record = this.#readPreviousVersionRecord();
1191
- if (record === undefined)
1192
- return;
1193
- if (loadUnits(this.#db).some((unit) => unit.status === 'revoked')) {
1194
- this.#discardPreviousVersion();
1195
- return;
1196
- }
1197
- if (nowMs - record.createdAtMs >
1198
- previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
1199
- this.#discardPreviousVersion();
1200
- return;
1201
- }
1202
- if (this.#previousVersionCoverageComplete()) {
1186
+ if (record !== undefined &&
1187
+ (loadUnits(this.#db).some((unit) => unit.status === 'revoked') ||
1188
+ this.#previousVersionExpired(record, nowMs) ||
1189
+ this.#previousVersionCoverageComplete()))
1203
1190
  this.#discardPreviousVersion();
1204
- }
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));
1205
1196
  }
1206
1197
  /**
1207
1198
  * RFC 0005 D9 boot hygiene: an orphan/stale container is discarded before any
@@ -1212,15 +1203,10 @@ export class SyncClient {
1212
1203
  if (!this.#previousVersionExists())
1213
1204
  return;
1214
1205
  const record = this.#readPreviousVersionRecord();
1215
- let discard = record === undefined || record.currentVersion !== this.#schema.version;
1216
- if (!discard &&
1217
- record !== undefined &&
1218
- this.#previousVersion !== undefined &&
1219
- this.#now() - record.createdAtMs >
1220
- previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
1221
- discard = true;
1222
- }
1223
- if (discard)
1206
+ if (record === undefined ||
1207
+ record.currentVersion !== this.#schema.version ||
1208
+ (this.#previousVersion !== undefined &&
1209
+ this.#previousVersionExpired(record)))
1224
1210
  this.#dropPreviousVersion();
1225
1211
  }
1226
1212
  // -- live-query invalidation ----------------------------------------------
@@ -1370,13 +1356,14 @@ export class SyncClient {
1370
1356
  ? Number(this.#db.query('SELECT COALESCE(SUM(byte_length),0)AS bytes FROM _syncular_blobs')[0]?.bytes ?? 0)
1371
1357
  : 0;
1372
1358
  const pressure = blobBytes > (this.#config.limits?.blobCacheMaxBytes ?? Infinity);
1359
+ const size = (value) => Math.max(0, Number(value ?? 0));
1373
1360
  return {
1374
1361
  status: pressure ? 'pressure' : 'healthy',
1375
1362
  databaseBytesApprox: Math.max(0, pageCount * pageSize),
1376
- pendingOutboxBytesApprox: Math.max(0, Number(sums?.outbox ?? 0)),
1377
- retainedOutcomeBytesApprox: Math.max(0, Number(sums?.bytes ?? 0)),
1378
- retainedOutcomeEntries: Math.max(0, Number(sums?.entries ?? 0)),
1379
- blobCacheBytesApprox: Math.max(0, blobBytes),
1363
+ pendingOutboxBytesApprox: size(sums?.outbox),
1364
+ retainedOutcomeBytesApprox: size(sums?.bytes),
1365
+ retainedOutcomeEntries: size(sums?.entries),
1366
+ blobCacheBytesApprox: size(blobBytes),
1380
1367
  ...(pressure
1381
1368
  ? { pressureReasonCode: 'client.blob_cache_over_limit' }
1382
1369
  : {}),
@@ -1646,7 +1633,7 @@ export class SyncClient {
1646
1633
  !Number.isSafeInteger(cached.byteLength) ||
1647
1634
  cached.byteLength !== cached.bytes.byteLength ||
1648
1635
  (await computeBlobId(cached.bytes)) !== pending.blobId) {
1649
- 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');
1650
1637
  }
1651
1638
  try {
1652
1639
  await this.#uploadOne(transport, pending.blobId, cached.bytes, pending.mediaType, signal);
@@ -1727,64 +1714,62 @@ export class SyncClient {
1727
1714
  async proveCurrentBase(outcome, maxRounds) {
1728
1715
  this.#requireActive();
1729
1716
  requireRoundBudget(maxRounds);
1730
- const { clientCommitId, sequence } = outcome;
1731
- const provable = (candidate) => candidate !== undefined &&
1732
- candidate.sequence === sequence &&
1733
- candidate.resolution === 'active' &&
1734
- (candidate.status === 'conflict' || candidate.status === 'rejected') &&
1735
- candidate.operations !== undefined &&
1736
- candidate.retainedRows !== undefined &&
1737
- candidate.operations.length === candidate.retainedRows.length &&
1738
- candidate.retainedRows.length > 0;
1739
1717
  let initial;
1740
1718
  try {
1741
- initial = readCommitOutcome(this.#db, clientCommitId);
1719
+ initial = readCommitOutcome(this.#db, outcome.clientCommitId);
1742
1720
  }
1743
1721
  catch {
1744
- return { proven: false, reason: 'snapshot_failed' };
1722
+ return unproven('snapshot_failed');
1745
1723
  }
1746
- if (!provable(initial))
1747
- return { proven: false, reason: 'outcome_unavailable' };
1724
+ if (!provable(initial, outcome.sequence))
1725
+ return unproven('outcome_unavailable');
1748
1726
  if (!this.#transportEnabled)
1749
- return { proven: false, reason: 'offline' };
1727
+ return unproven('offline');
1750
1728
  await this.#opChain;
1751
1729
  if (!this.#transportEnabled)
1752
- return { proven: false, reason: 'offline' };
1753
- const epoch = this.#transportEpoch;
1754
- const registrationEpoch = this.#registrationEpoch;
1755
- const securityEpoch = this.#securityEpoch;
1756
- let before;
1730
+ return unproven('offline');
1731
+ let start;
1757
1732
  try {
1758
- before = loadUnits(this.#db);
1733
+ start = this.#driveStart();
1759
1734
  }
1760
1735
  catch {
1761
- return { proven: false, reason: 'snapshot_failed' };
1736
+ return unproven('snapshot_failed');
1762
1737
  }
1763
1738
  let report;
1764
1739
  try {
1765
1740
  report = await this.syncUntilIdle(maxRounds);
1766
1741
  }
1767
1742
  catch {
1768
- return {
1769
- proven: false,
1770
- reason: !this.#transportEnabled || epoch !== this.#transportEpoch
1771
- ? 'offline'
1772
- : registrationEpoch !== this.#registrationEpoch
1773
- ? 'missing_coverage'
1774
- : 'sync_failed',
1775
- };
1743
+ return unproven(!this.#transportEnabled || start.epoch !== this.#transportEpoch
1744
+ ? 'offline'
1745
+ : start.registrationEpoch !== this.#registrationEpoch
1746
+ ? 'missing_coverage'
1747
+ : 'sync_failed');
1776
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) {
1777
1762
  if (!this.#transportEnabled || epoch !== this.#transportEpoch)
1778
- return { proven: false, reason: 'offline' };
1763
+ return unproven('offline');
1779
1764
  if (registrationEpoch !== this.#registrationEpoch)
1780
- return { proven: false, reason: 'missing_coverage' };
1765
+ return unproven('missing_coverage');
1781
1766
  if (this.#securityLifecycle !== 'active' ||
1782
1767
  securityEpoch !== this.#securityEpoch)
1783
- return { proven: false, reason: 'sync_failed' };
1768
+ return unproven('sync_failed');
1784
1769
  if (report.schemaFloor !== undefined)
1785
- return { proven: false, reason: 'schema_floor' };
1770
+ return unproven('schema_floor');
1786
1771
  if (report.budgetExhausted)
1787
- return { proven: false, reason: 'budget_exhausted' };
1772
+ return unproven('budget_exhausted');
1788
1773
  try {
1789
1774
  return this.#db.transaction(() => {
1790
1775
  const snapshot = this.#readSnapshot({
@@ -1794,11 +1779,8 @@ export class SyncClient {
1794
1779
  });
1795
1780
  const delivery = snapshot.deliveries[0];
1796
1781
  const current = readCommitOutcome(this.#db, clientCommitId);
1797
- if (delivery?.status !== 'known' || !provable(current))
1798
- return {
1799
- proven: false,
1800
- reason: report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable',
1801
- };
1782
+ if (delivery?.status !== 'known' || !provable(current, sequence))
1783
+ return unproven(report.revoked.length > 0 ? 'revoked' : 'outcome_unavailable');
1802
1784
  const after = new Map(loadUnits(this.#db).map((unit) => [unit.id, unit]));
1803
1785
  const complete = new Set(snapshot.units.flatMap((state) => state.state === 'known' && state.bootstrapComplete
1804
1786
  ? [state.id]
@@ -1835,17 +1817,14 @@ export class SyncClient {
1835
1817
  for (const row of current.retainedRows) {
1836
1818
  if (!covered(row.table, row.serverRow ?? row.localRow) ||
1837
1819
  row.uniqueConflicts?.some((conflict) => !covered(row.table, conflict.serverRow))) {
1838
- return {
1839
- proven: false,
1840
- reason: report.revoked.length > 0 ? 'revoked' : 'missing_coverage',
1841
- };
1820
+ return unproven(report.revoked.length > 0 ? 'revoked' : 'missing_coverage');
1842
1821
  }
1843
1822
  }
1844
1823
  return { proven: true, rows: current.retainedRows };
1845
1824
  });
1846
1825
  }
1847
1826
  catch {
1848
- return { proven: false, reason: 'snapshot_failed' };
1827
+ return unproven('snapshot_failed');
1849
1828
  }
1850
1829
  }
1851
1830
  /** Newest-first durable outcome journal. */
@@ -1867,6 +1846,8 @@ export class SyncClient {
1867
1846
  }
1868
1847
  if (current.resolution !== 'active')
1869
1848
  return current;
1849
+ if (current.replacementClientCommitId !== undefined)
1850
+ throw replacementPending();
1870
1851
  const replacement = input.replacementClientCommitId;
1871
1852
  if (input.resolution === 'superseded') {
1872
1853
  if (replacement === undefined ||
@@ -1886,10 +1867,109 @@ export class SyncClient {
1886
1867
  if (!allowed) {
1887
1868
  throw invalidRequest(`resolution ${input.resolution} is invalid for ${current.status} outcome`);
1888
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) {
1889
1951
  const priorConflicts = this.#conflicts;
1890
1952
  const priorRejections = this.#rejections;
1891
1953
  return this.#applyBatch((batch) => {
1892
- 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);
1893
1973
  this.#db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_id=?`, [
1894
1974
  input.clientCommitId,
1895
1975
  ]);
@@ -1900,7 +1980,7 @@ export class SyncClient {
1900
1980
  this.#conflicts = this.#conflicts.filter((record) => record.clientCommitId !== input.clientCommitId);
1901
1981
  this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== input.clientCommitId);
1902
1982
  pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
1903
- this.#replayOutbox();
1983
+ this.#replayOutbox(scope, false);
1904
1984
  for (const operation of current.operations ?? [])
1905
1985
  batch.table(operation.table);
1906
1986
  batch.outcomes();
@@ -1908,6 +1988,7 @@ export class SyncClient {
1908
1988
  batch.conflicts();
1909
1989
  if (current.status === 'rejected')
1910
1990
  batch.rejections();
1991
+ within?.();
1911
1992
  return resolved;
1912
1993
  }, undefined, (error) => {
1913
1994
  this.#conflicts = priorConflicts;
@@ -2021,9 +2102,7 @@ export class SyncClient {
2021
2102
  }));
2022
2103
  if (registered) {
2023
2104
  this.#registrationEpoch += 1;
2024
- this.#setSyncNeeded(true);
2025
- this.#emitSyncIntent({ kind: 'interactive' });
2026
- this.#emitDiagnostics();
2105
+ this.#registrationChanged();
2027
2106
  }
2028
2107
  return ids;
2029
2108
  }
@@ -2042,8 +2121,11 @@ export class SyncClient {
2042
2121
  }
2043
2122
  deleteUnit(this.#db, id);
2044
2123
  this.#registrationEpoch += 1;
2045
- if (unit.status !== 'active')
2046
- return;
2124
+ if (unit.status === 'active')
2125
+ this.#registrationChanged();
2126
+ }
2127
+ /** A registration change owes an interactive pull. */
2128
+ #registrationChanged() {
2047
2129
  this.#setSyncNeeded(true);
2048
2130
  this.#emitSyncIntent({ kind: 'interactive' });
2049
2131
  this.#emitDiagnostics();
@@ -2265,6 +2347,11 @@ export class SyncClient {
2265
2347
  readCommitOutcome(this.#db, supplied)))
2266
2348
  throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
2267
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) {
2268
2355
  // §7.1: a patch reads the row as the commit's earlier operations leave
2269
2356
  // it. Keyed by `table rowId` (a table name holds no space): the JSON
2270
2357
  // values an earlier upsert wrote, or null after an earlier delete. A
@@ -2351,7 +2438,7 @@ export class SyncClient {
2351
2438
  if (refusal !== undefined)
2352
2439
  // §7.5: the same structured shape the native authoring APIs return — a
2353
2440
  // static message, and the dynamic cause in `details.legacyCause`.
2354
- throw new ClientSyncError('sync.invalid_request', 'the authoring request is invalid', false, {
2441
+ throw invalidRequest('the authoring request is invalid', false, {
2355
2442
  legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
2356
2443
  });
2357
2444
  // §7.1 insert intent: a full-row write of a row the replica does not
@@ -2368,6 +2455,13 @@ export class SyncClient {
2368
2455
  insert: insert ? true : undefined,
2369
2456
  });
2370
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) {
2371
2465
  // §5.11: a sealed row is read-only; a write could send NULL over
2372
2466
  // ciphertext this device cannot see.
2373
2467
  for (const operation of operations) {
@@ -2417,21 +2511,16 @@ export class SyncClient {
2417
2511
  }
2418
2512
  throw error;
2419
2513
  }
2514
+ within?.(batch);
2420
2515
  batch.status();
2421
2516
  });
2422
2517
  this.#needsPull = true;
2423
2518
  });
2424
2519
  this.#emitSyncIntent({ kind: 'interactive' });
2425
- return clientCommitId;
2426
2520
  }
2427
2521
  /** Host-facing mutation result with explicit network work intent (§7.5). */
2428
2522
  mutateCommand(mutations, options) {
2429
- return {
2430
- value: this.mutate(mutations, options),
2431
- effects: {
2432
- sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2433
- },
2434
- };
2523
+ return this.#commandResult(this.mutate(mutations, options));
2435
2524
  }
2436
2525
  /**
2437
2526
  * Partial update over the §6.1 sparse wire: record one upsert whose
@@ -2504,7 +2593,12 @@ export class SyncClient {
2504
2593
  let result;
2505
2594
  try {
2506
2595
  result = this.#applyBatch((batch) => {
2507
- 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
+ ]);
2508
2602
  restoreFailedBases(this.#db, this.#schema);
2509
2603
  this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
2510
2604
  // Doomed detection runs to fixpoint, matching the Rust core's rule:
@@ -2566,33 +2660,16 @@ export class SyncClient {
2566
2660
  (values !== undefined &&
2567
2661
  localDataPurgeTargetMatches(target, values)))))
2568
2662
  batch.outcomes();
2569
- if (doomed.length > 0) {
2570
- // §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
2571
- // never its operations, so no purged value survives in it.
2572
- for (const commit of doomed) {
2573
- const results = commit.operations.map((_operation, opIndex) => {
2574
- const rejection = {
2575
- clientCommitId: commit.clientCommitId,
2576
- opIndex,
2577
- code: 'client.local_data_purged',
2578
- message: 'the commit was dropped by an application-authorized local data purge',
2579
- retryable: false,
2580
- };
2581
- this.#rejections.push(rejection);
2582
- return { status: 'error', rejection };
2583
- });
2584
- recordCommitOutcome(this.#db, {
2585
- clientCommitId: commit.clientCommitId,
2586
- status: 'rejected',
2587
- recordedAtMs: this.#now(),
2588
- results,
2589
- });
2590
- }
2591
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
2592
- batch.status();
2593
- batch.rejections();
2594
- batch.outcomes();
2595
- }
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
+ })));
2596
2673
  this.#replayOutbox();
2597
2674
  this.#deleteUnreferencedBlobs();
2598
2675
  setMeta(this.#db, metaKey, purge.canonicalPlan);
@@ -2686,22 +2763,12 @@ export class SyncClient {
2686
2763
  if (!priorUpgrading)
2687
2764
  this.#config.onUpgrading?.(true);
2688
2765
  this.#emitSyncNeeded('startup');
2689
- this.#emitSyncIntent({ kind: 'interactive' });
2690
2766
  return {
2691
2767
  alreadyApplied: false,
2692
2768
  retainedCommits: pending.length,
2693
2769
  resetSubscriptions,
2694
2770
  };
2695
2771
  }
2696
- #localPurgeTargetsByTable(purge) {
2697
- const byTable = new Map();
2698
- for (const target of purge.targets) {
2699
- const targets = byTable.get(target.table.name) ?? [];
2700
- targets.push(target);
2701
- byTable.set(target.table.name, targets);
2702
- }
2703
- return byTable;
2704
- }
2705
2772
  #localPurgeRowIds(purge) {
2706
2773
  const byTable = new Map();
2707
2774
  for (const target of purge.targets) {
@@ -2722,8 +2789,12 @@ export class SyncClient {
2722
2789
  }
2723
2790
  /** Host-facing patch result with explicit network work intent (§7.5). */
2724
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) {
2725
2796
  return {
2726
- value: this.patch(table, rowId, partial, options),
2797
+ value,
2727
2798
  effects: {
2728
2799
  sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
2729
2800
  },
@@ -2772,7 +2843,11 @@ export class SyncClient {
2772
2843
  let ops = 0;
2773
2844
  let bytes = 0;
2774
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));
2775
2848
  for (const commit of iterateOutbox(this.#db, throughSeq)) {
2849
+ if (held.has(commit.clientCommitId))
2850
+ break;
2776
2851
  // §6.1/§7.1: the commit-count and operation caps are hard. A first
2777
2852
  // commit that alone exceeds the operation cap is a typed capacity error
2778
2853
  // and stays queued; a later one defers with the complete suffix.
@@ -2869,7 +2944,9 @@ export class SyncClient {
2869
2944
  #dropIncompatibleCommit(commit, message, code = OUTBOX_INCOMPATIBLE_CODE, replay = true, reason, classifiedFailures) {
2870
2945
  const priorRejections = [...this.#rejections];
2871
2946
  this.#applyBatch((batch) => {
2872
- if (this.#retainFailedCommits && code === 'client.encrypt_failed')
2947
+ if (this.#retainFailedCommits &&
2948
+ (code === 'client.encrypt_failed' ||
2949
+ code === REPLACEMENT_REFUSED_CODE))
2873
2950
  retainFailedRows(this.#db, commit, listOutboxBeforeImages(this.#db, commit.clientCommitId));
2874
2951
  this.#rollbackFailedCommit(commit, batch, classifiedFailures);
2875
2952
  if (replay)
@@ -2879,27 +2956,17 @@ export class SyncClient {
2879
2956
  // the journal cannot carry keeps its durable commitId, code and a bounded
2880
2957
  // `details.reason` instead of an opaque rewritten value.
2881
2958
  const representable = commit.operations.every(isStoredOperation);
2882
- const rejection = definedObject({
2883
- clientCommitId: commit.clientCommitId,
2884
- opIndex: 0,
2885
- code,
2886
- message,
2887
- retryable: false,
2888
- ...(representable ? { operation: commit.operations[0] } : {}),
2889
- ...(reason === undefined ? {} : { details: { reason } }),
2890
- });
2891
- this.#rejections.push(rejection);
2892
- recordCommitOutcome(this.#db, {
2893
- clientCommitId: commit.clientCommitId,
2894
- status: 'rejected',
2895
- recordedAtMs: this.#now(),
2896
- results: [{ status: 'error', rejection }],
2897
- ...(representable ? { operations: commit.operations } : {}),
2898
- });
2899
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
2900
- batch.status();
2901
- batch.rejections();
2902
- 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);
2903
2970
  }, undefined, (error) => {
2904
2971
  // The drop's own outcome write or publication failed: mirror the
2905
2972
  // rollback so no rejection the journal did not keep stays in memory.
@@ -2907,6 +2974,24 @@ export class SyncClient {
2907
2974
  throw error;
2908
2975
  });
2909
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
+ }
2910
2995
  // -- sync -------------------------------------------------------------------
2911
2996
  /**
2912
2997
  * One combined push+pull round (§1.5, §7.2). The core owns one loop: a
@@ -2995,36 +3080,23 @@ export class SyncClient {
2995
3080
  const errorCode = typeof code === 'string'
2996
3081
  ? this.#diagnosticCode(code)
2997
3082
  : 'client.unknown_failure';
2998
- const details = typeof error === 'object' && error !== null && 'details' in error
2999
- ? error.details
3000
- : undefined;
3001
- const rawCause = typeof details === 'object' &&
3002
- details !== null &&
3003
- 'causeKind' in details
3004
- ? details.causeKind
3005
- : undefined;
3006
- let causeKind;
3007
- switch (rawCause) {
3008
- case 'network':
3009
- case 'connect':
3010
- case 'tls':
3011
- case 'io':
3012
- case 'request':
3013
- case 'protocol':
3014
- case 'timeout':
3015
- case 'round_deadline':
3016
- case 'aborted':
3017
- case 'body':
3018
- case 'status':
3019
- case 'redirect':
3020
- case 'unknown':
3021
- causeKind = rawCause;
3022
- }
3023
- const rawStatus = typeof details === 'object' &&
3024
- details !== null &&
3025
- 'httpStatus' in details
3026
- ? details.httpStatus
3027
- : 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');
3028
3100
  const httpStatus = (causeKind === 'status' ||
3029
3101
  causeKind === 'body' ||
3030
3102
  causeKind === 'redirect') &&
@@ -3179,6 +3251,9 @@ export class SyncClient {
3179
3251
  cursor: unit.cursor,
3180
3252
  bootstrapState: unit.bootstrapState,
3181
3253
  }),
3254
+ ...(unit.restrict === undefined
3255
+ ? []
3256
+ : [{ type: 'RESTRICT', ...unit.restrict }]),
3182
3257
  ]),
3183
3258
  ];
3184
3259
  // The header [+ the report frame] lead the request; PUSH_COMMIT frames
@@ -3265,16 +3340,7 @@ export class SyncClient {
3265
3340
  // transport, `network` from a browser fetch) is not a round worth
3266
3341
  // backing off for. Stop without scheduling an intent or growing the
3267
3342
  // delay; the host's own connectivity signal re-arms the drive.
3268
- const details = error instanceof ClientSyncError
3269
- ? error.details
3270
- : typeof error === 'object' && error !== null && 'details' in error
3271
- ? error.details
3272
- : undefined;
3273
- const causeKind = typeof details === 'object' &&
3274
- details !== null &&
3275
- 'causeKind' in details
3276
- ? details.causeKind
3277
- : undefined;
3343
+ const causeKind = errorDetail(error, 'causeKind');
3278
3344
  const unreachable = causeKind === 'connect' || causeKind === 'network';
3279
3345
  // The round's work is still owed; the host's connectivity resume runs it.
3280
3346
  if (unreachable)
@@ -3385,6 +3451,9 @@ export class SyncClient {
3385
3451
  this.#setSyncNeeded(false);
3386
3452
  return result(false);
3387
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;
3388
3457
  const states = () => JSON.stringify(loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]));
3389
3458
  const startedAtMs = this.#now();
3390
3459
  let completed = false;
@@ -3444,8 +3513,11 @@ export class SyncClient {
3444
3513
  aggregate.deferredCommits = last.deferredCommits ?? 0;
3445
3514
  aggregate.schemaFloor = last.schemaFloor;
3446
3515
  // A disabled transport or a schema floor ends the loop, not the budget.
3447
- if (!this.#transportEnabled || aggregate.schemaFloor)
3516
+ if (!this.#transportEnabled || aggregate.schemaFloor) {
3517
+ if (start !== undefined)
3518
+ this.#settleDecisions(decisions, start, result(false));
3448
3519
  return result(false);
3520
+ }
3449
3521
  if (maxRounds === undefined &&
3450
3522
  last.segmentRowsApplied > 0 &&
3451
3523
  last.bootstrapping.length > 0 &&
@@ -3457,6 +3529,9 @@ export class SyncClient {
3457
3529
  last.resets.length === 0 &&
3458
3530
  !aggregate.deferredCommits &&
3459
3531
  !this.#needsPull) {
3532
+ if (start !== undefined &&
3533
+ this.#settleDecisions(decisions, start, result(false)))
3534
+ continue;
3460
3535
  return result(false);
3461
3536
  }
3462
3537
  }
@@ -3633,7 +3708,7 @@ export class SyncClient {
3633
3708
  // A superseded attempt leaves the successor's (or the deliberate
3634
3709
  // disconnect's) state alone.
3635
3710
  if (generation === this.#realtimeGeneration) {
3636
- this.#setRealtimeState('refused', realtimeErrorCode(error));
3711
+ this.#setRealtimeState('refused', thrownCode(error));
3637
3712
  }
3638
3713
  throw error;
3639
3714
  }
@@ -3743,14 +3818,12 @@ export class SyncClient {
3743
3818
  const event = parsed.event;
3744
3819
  if (event.event === 'hello') {
3745
3820
  if (event.data.requiresSync) {
3746
- this.#setSyncNeeded(true);
3747
3821
  this.#emitSyncNeeded('hello');
3748
3822
  }
3749
3823
  return;
3750
3824
  }
3751
3825
  if (event.event === 'sync') {
3752
3826
  // §8.3: any wake-up means "run a pull soon", never data.
3753
- this.#setSyncNeeded(true);
3754
3827
  this.#emitSyncNeeded(event.data.reason);
3755
3828
  return;
3756
3829
  }
@@ -3813,7 +3886,6 @@ export class SyncClient {
3813
3886
  transportEpoch !== this.#transportEpoch)
3814
3887
  return;
3815
3888
  if (resetEpoch !== this.#localResetEpoch) {
3816
- this.#setSyncNeeded(true);
3817
3889
  this.#emitSyncNeeded('catchup-required');
3818
3890
  return;
3819
3891
  }
@@ -3824,7 +3896,6 @@ export class SyncClient {
3824
3896
  }
3825
3897
  catch {
3826
3898
  // A delta that cannot be applied is recovered by a pull (§8.3).
3827
- this.#setSyncNeeded(true);
3828
3899
  this.#emitSyncNeeded('catchup-required');
3829
3900
  }
3830
3901
  });
@@ -4100,10 +4171,7 @@ export class SyncClient {
4100
4171
  // catching up with its cursor unpersisted, and the next
4101
4172
  // round's SUB_START settles it (revoked or a new bootstrap).
4102
4173
  // A host downloader may throw any error carrying the code.
4103
- if (typeof error !== 'object' ||
4104
- error === null ||
4105
- !('code' in error) ||
4106
- error.code !== 'sync.forbidden')
4174
+ if (thrownCode(error) !== 'sync.forbidden')
4107
4175
  throw error;
4108
4176
  section.skip = true;
4109
4177
  break;
@@ -4298,7 +4366,6 @@ export class SyncClient {
4298
4366
  this.#sendAck(deltaCursor);
4299
4367
  // §8.2: an unapplied delta is a drop; a pull repairs it.
4300
4368
  if (deltaDropped) {
4301
- this.#setSyncNeeded(true);
4302
4369
  this.#emitSyncNeeded('catchup-required');
4303
4370
  }
4304
4371
  }
@@ -4366,10 +4433,7 @@ export class SyncClient {
4366
4433
  return true;
4367
4434
  }
4368
4435
  // rejected
4369
- const cacheMiss = frame.results.some((result) => result.status === 'error' &&
4370
- result.code === 'sync.idempotency_cache_miss' &&
4371
- result.retryable);
4372
- if (cacheMiss) {
4436
+ if (!isFinalPushResult(frame)) {
4373
4437
  // §6.3: a serving failure, not the commit's outcome — keep the
4374
4438
  // commit queued and retry the identical push later.
4375
4439
  summary.retryable.push(frame.clientCommitId);
@@ -4379,6 +4443,8 @@ export class SyncClient {
4379
4443
  for (const result of frame.results) {
4380
4444
  const operation = commit.operations[result.opIndex];
4381
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);
4382
4448
  const conflict = definedObject({
4383
4449
  clientCommitId: frame.clientCommitId,
4384
4450
  opIndex: result.opIndex,
@@ -4387,8 +4453,16 @@ export class SyncClient {
4387
4453
  code: result.code,
4388
4454
  message: result.message,
4389
4455
  serverVersion: result.serverVersion,
4390
- serverRow: this.#decodeServerRow(operation?.table, result.serverRow),
4391
- 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),
4392
4466
  operation: operation,
4393
4467
  });
4394
4468
  this.#conflicts.push(conflict);
@@ -4454,38 +4528,6 @@ export class SyncClient {
4454
4528
  #outboxCommitExists(clientCommitId) {
4455
4529
  return (this.#db.query(`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`, [clientCommitId]).length > 0);
4456
4530
  }
4457
- #decodeServerRow(tableName, payload) {
4458
- if (tableName === undefined)
4459
- return {};
4460
- const table = this.#schema.tables.get(tableName);
4461
- if (table === undefined)
4462
- return {};
4463
- const values = decodeRow(table.columns, payload);
4464
- const record = {};
4465
- table.columns.forEach((column, index) => {
4466
- record[column.name] = values[index] ?? null;
4467
- });
4468
- return record;
4469
- }
4470
- /**
4471
- * §6.3 `conflictColumns`: decode the presence-layout bitmap into the names
4472
- * of the present columns whose `column_version` exceeded `baseVersion`. A
4473
- * custom merge recomputes exactly these columns (§6.5).
4474
- */
4475
- #decodeConflictColumns(tableName, bitmap) {
4476
- if (tableName === undefined)
4477
- return [];
4478
- const table = this.#schema.tables.get(tableName);
4479
- if (table === undefined)
4480
- return [];
4481
- const names = [];
4482
- table.columns.forEach((column, index) => {
4483
- const byte = bitmap[index >> 3] ?? 0;
4484
- if (((byte >> (index & 7)) & 1) === 1)
4485
- names.push(column.name);
4486
- });
4487
- return names;
4488
- }
4489
4531
  async #applyCommit(frame, summary, source) {
4490
4532
  await applyCommitFrame(this.#db, this.#schema, frame, this.#encryption, (fn) => this.#applyBatch((batch) => {
4491
4533
  this.#recordCommitChanges(batch, frame);
@@ -4602,8 +4644,15 @@ export class SyncClient {
4602
4644
  // §3.3 owners matter only for rows the clear would reach, so a pair
4603
4645
  // with no matching local or retained row never reads the unit list.
4604
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
+ ]);
4605
4654
  try {
4606
- summary.segmentRowsApplied += await apply(table, !section.seeded.has(tableName), effective, () => (owners ??=
4655
+ summary.segmentRowsApplied += await apply(table, clearFirst, effective, () => (owners ??=
4607
4656
  this.#db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [table.name]).length > 0 || this.#scopedRowsExist(table, effective, [])
4608
4657
  ? unitOwners(loadUnits(this.#db), table, unit.id)
4609
4658
  : []));
@@ -4622,6 +4671,7 @@ export class SyncClient {
4622
4671
  ...current,
4623
4672
  status: 'failed',
4624
4673
  reasonCode: 'sync.scope_revoked',
4674
+ restrict: undefined,
4625
4675
  });
4626
4676
  for (const ref of windowRefs(this.#db, unit.id))
4627
4677
  batch.window(ref.baseKey, ref.value);
@@ -4674,8 +4724,7 @@ export class SyncClient {
4674
4724
  throw invalidRequest('segment exceeds its byteLength', true);
4675
4725
  }
4676
4726
  onProgress(bytes.byteLength);
4677
- const hash = await sha256Hex(bytes);
4678
- if (`sha256:${hash}` !== frame.segmentId) {
4727
+ if ((await computeBlobId(bytes)) !== frame.segmentId) {
4679
4728
  throw invalidRequest('segment failed content-address verification (§5.1)', true);
4680
4729
  }
4681
4730
  return bytes;
@@ -4703,9 +4752,7 @@ export class SyncClient {
4703
4752
  saveUnit(this.#db, {
4704
4753
  ...unit,
4705
4754
  reasonCode: start.reasonCode,
4706
- cursor: -1,
4707
- bootstrapState: undefined,
4708
- seeded: [],
4755
+ ...UNIT_RESTART,
4709
4756
  });
4710
4757
  summary.resets.push(unit.id);
4711
4758
  return;
@@ -4736,10 +4783,8 @@ export class SyncClient {
4736
4783
  ...unit,
4737
4784
  status: failed ? 'failed' : 'revoked',
4738
4785
  reasonCode: failed ? 'sync.scope_revoked' : start.reasonCode,
4739
- cursor: -1,
4740
- bootstrapState: undefined,
4741
- seeded: [],
4742
4786
  echo: undefined,
4787
+ ...UNIT_RESTART,
4743
4788
  });
4744
4789
  if (revoked)
4745
4790
  summary.revoked.push(unit.id);
@@ -4753,13 +4798,17 @@ export class SyncClient {
4753
4798
  ...unit,
4754
4799
  reasonCode: undefined,
4755
4800
  echo: start.fenced,
4801
+ // §7.4.3: a rearm and a completed bootstrap end the restriction.
4756
4802
  ...(rearmed
4757
- ? { cursor: -1, bootstrapState: undefined, seeded: [] }
4803
+ ? UNIT_RESTART
4758
4804
  : start.bootstrap
4759
4805
  ? {
4760
4806
  cursor: end.nextCursor,
4761
4807
  bootstrapState: end.bootstrapState,
4762
4808
  seeded: end.bootstrapState === undefined ? [] : [...section.seeded],
4809
+ ...(end.bootstrapState === undefined
4810
+ ? { restrict: undefined }
4811
+ : {}),
4763
4812
  }
4764
4813
  : {}),
4765
4814
  });
@@ -4808,34 +4857,16 @@ export class SyncClient {
4808
4857
  const doomed = listOutbox(this.#db).filter((commit) => commit.operations.some((op) => op.table === table.name &&
4809
4858
  op.values !== undefined &&
4810
4859
  ownsLocalRow(table, lastEffective, owners, op.values)));
4811
- for (const commit of doomed) {
4812
- const { clientCommitId } = commit;
4860
+ for (const { clientCommitId, operations } of doomed) {
4813
4861
  deleteOutboxCommit(this.#db, clientCommitId);
4814
- const results = commit.operations.map((operation, opIndex) => {
4815
- const rejection = {
4816
- clientCommitId,
4817
- opIndex,
4818
- code: 'sync.scope_revoked',
4819
- message: 'the commit was dropped because its effective scope was revoked',
4820
- retryable: false,
4821
- operation,
4822
- };
4823
- this.#rejections.push(rejection);
4824
- return { status: 'error', rejection };
4825
- });
4826
- recordCommitOutcome(this.#db, {
4862
+ this.#journalDrop(batch, clientCommitId, operations.map((operation, opIndex) => ({
4827
4863
  clientCommitId,
4828
- status: 'rejected',
4829
- recordedAtMs: this.#now(),
4830
- results,
4831
- operations: commit.operations,
4832
- });
4833
- }
4834
- if (doomed.length > 0) {
4835
- pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
4836
- batch.status();
4837
- batch.rejections();
4838
- 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);
4839
4870
  }
4840
4871
  this.#replayOutbox(scope);
4841
4872
  this.#deleteUnreferencedBlobs();
@@ -4866,14 +4897,13 @@ export class SyncClient {
4866
4897
  }
4867
4898
  const syncVersion = row[SYNC_VERSION_COLUMN];
4868
4899
  if (typeof syncVersion !== 'number') {
4869
- 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`);
4870
4901
  }
4871
4902
  return { opIndex, existed: true, syncVersion, values };
4872
4903
  }
4873
4904
  /** `onlyKeys` holds overlay row keys (`JSON [table,rowId]`). */
4874
4905
  #captureBeforeImages(operations, onlyKeys) {
4875
- return operations.flatMap((operation, opIndex) => onlyKeys &&
4876
- !onlyKeys.has(JSON.stringify([operation.table, operation.rowId]))
4906
+ return operations.flatMap((operation, opIndex) => onlyKeys && !onlyKeys.has(rowKey(operation))
4877
4907
  ? []
4878
4908
  : [this.#captureBeforeImage(operation, opIndex)]);
4879
4909
  }
@@ -4887,7 +4917,7 @@ export class SyncClient {
4887
4917
  return;
4888
4918
  }
4889
4919
  if (image.values === undefined || image.syncVersion === undefined) {
4890
- 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`);
4891
4921
  }
4892
4922
  const values = table.columns.map((column) => jsonToRowValue(image.values?.[column.name] ?? null));
4893
4923
  upsertLocalRow(this.#db, table, values, image.syncVersion);
@@ -4910,17 +4940,14 @@ export class SyncClient {
4910
4940
  const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
4911
4941
  const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
4912
4942
  const complete = commit.operations.every((_, index) => imageByIndex.has(index));
4913
- const affectedKeys = new Set(commit.operations.map((operation) => JSON.stringify([operation.table, operation.rowId])));
4943
+ const affectedKeys = new Set(commit.operations.map(rowKey));
4914
4944
  if (complete) {
4915
- const restored = new Set();
4945
+ // The first operation on a row holds its pre-commit image.
4946
+ const unrestored = new Set(affectedKeys);
4916
4947
  commit.operations.forEach((operation, index) => {
4917
- const key = JSON.stringify([operation.table, operation.rowId]);
4918
- if (restored.has(key))
4919
- return;
4920
4948
  const image = imageByIndex.get(index);
4921
- if (image)
4949
+ if (unrestored.delete(rowKey(operation)) && image)
4922
4950
  this.#restoreBeforeImage(operation, image, batch);
4923
- restored.add(key);
4924
4951
  });
4925
4952
  }
4926
4953
  else {
@@ -4934,7 +4961,7 @@ export class SyncClient {
4934
4961
  for (const later of listOutbox(this.#db, [...affectedKeys])) {
4935
4962
  if (later.seq <= commit.seq)
4936
4963
  continue;
4937
- 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)));
4938
4965
  if (affectedOperations.length === 0)
4939
4966
  continue;
4940
4967
  replaceOutboxBeforeImages(this.#db, later, this.#captureBeforeImages(later.operations, affectedKeys));
@@ -4960,15 +4987,8 @@ export class SyncClient {
4960
4987
  : this.#table(op.table);
4961
4988
  if (table === undefined)
4962
4989
  continue;
4963
- let precise = batch === undefined
4964
- ? false
4965
- : this.#recordStoredRowScopes(batch, table, op.rowId);
4966
- if (op.op === 'delete') {
4967
- if (batch !== undefined && !precise)
4968
- batch.table(op.table);
4969
- deleteLocalRow(this.#db, table, op.rowId, false);
4970
- continue;
4971
- }
4990
+ let precise = batch !== undefined &&
4991
+ this.#recordStoredRowScopes(batch, table, op.rowId);
4972
4992
  // §7.1 overlay: apply the operation's PRESENT columns over the current
4973
4993
  // local row. A partial operation over an absent local row leaves it
4974
4994
  // absent — the server answers it with sync.row_deleted or
@@ -4977,18 +4997,17 @@ export class SyncClient {
4977
4997
  const opValues = op.values ?? {};
4978
4998
  const full = op.insert === true ||
4979
4999
  table.columns.every((column) => column.name in opValues);
5000
+ const local = op.op === 'delete' ? undefined : this.#rowById(table, op.rowId);
4980
5001
  // An insert lacking a non-nullable column cannot encode (§7.4.4); it
4981
5002
  // stays hidden until the send-time drop classifies it.
4982
- if (op.insert === true &&
4983
- table.columns.some((column) => !column.nullable && opValues[column.name] === undefined)) {
4984
- if (batch !== undefined && !precise)
4985
- batch.table(op.table);
4986
- continue;
4987
- }
4988
- const local = this.#rowById(table, op.rowId);
4989
- 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)) {
4990
5007
  if (batch !== undefined && !precise)
4991
5008
  batch.table(op.table);
5009
+ if (op.op === 'delete')
5010
+ deleteLocalRow(this.#db, table, op.rowId, false);
4992
5011
  continue;
4993
5012
  }
4994
5013
  const values = table.columns.map((column) => {
@@ -5011,7 +5030,7 @@ export class SyncClient {
5011
5030
  })), values);
5012
5031
  }
5013
5032
  catch {
5014
- throw new ClientSyncError('sync.local_corrupt', 'persisted optimistic row value is invalid');
5033
+ throw localStateCorrupt('persisted optimistic row value is invalid');
5015
5034
  }
5016
5035
  }
5017
5036
  // Record the row's scope keys from its scope columns (I2 refinement).
@@ -5052,7 +5071,7 @@ export class SyncClient {
5052
5071
  this.#rejections = this.#rejections.filter((record) => record.clientCommitId !== commit.clientCommitId);
5053
5072
  for (const op of commit.operations) {
5054
5073
  batch.table(op.table);
5055
- scope.push(JSON.stringify([op.table, op.rowId]));
5074
+ scope.push(rowKey(op));
5056
5075
  }
5057
5076
  }
5058
5077
  return scope;
@@ -5161,7 +5180,7 @@ export class SyncClient {
5161
5180
  if (rebased !== undefined && outbox.has(commit))
5162
5181
  replaceOutboxBeforeImages(this.#db, commit, this.#captureBeforeImages(commit.operations, rebased));
5163
5182
  this.#applyOperationsLocally(commit.operations.filter((op) => scope === undefined ||
5164
- scope.includes(JSON.stringify([op.table, op.rowId])) ||
5183
+ scope.includes(rowKey(op)) ||
5165
5184
  scope.includes(JSON.stringify([op.table]))), batch, true);
5166
5185
  }
5167
5186
  };