@syncular/client 0.82.3 → 0.84.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -409,7 +409,9 @@ stop, pending outbox, offline transport, and storage pressure/unreadability.
409
409
  Failed progress and `lastRound` diagnostics expose an optional bounded
410
410
  `causeKind` and HTTP status. Worker leaders and followers receive the same
411
411
  evidence. A new progress attempt clears its failure fields; a successful round
412
- replaces the failed last round. `host.connectivity` describes the latest
412
+ replaces the failed last round. `lastRound.epoch` and `lastRound.attempt`
413
+ identify the round and match its progress events; count rounds by that pair
414
+ instead of `completedAtMs`. `host.connectivity` describes the latest
413
415
  endpoint observation and does not prove the device's network state.
414
416
  `queryFailures` retains at most 256 failed owned snapshot reads until each query
415
417
  reads successfully. An entry contains only its stable PHI-free owner id,
@@ -836,9 +838,11 @@ const stop = client.onProgress((progress) => {
836
838
  stop();
837
839
  ```
838
840
 
839
- Each snapshot identifies the round with `attempt`, and the current payload with
841
+ Each snapshot identifies the round with `epoch` and `attempt`, and the current payload with
840
842
  `unitId`, `table`, and optional `segmentId`. Counters reset for each
841
- payload; `syncUntilIdle` starts a new attempt for each round. `phase` is `request`,
843
+ payload; `syncUntilIdle` starts a new attempt for each round. `epoch` is random per
844
+ client core; a new core (a Worker handover, a reload) counts attempts from 1
845
+ under a new `epoch`. `phase` is `request`,
842
846
  `download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
843
847
  totals remain absent. A new attempt clears prior errors and counters.
844
848
 
package/dist/client.d.ts CHANGED
@@ -564,9 +564,6 @@ export declare class SyncClient {
564
564
  * dismissed. The transition is one-way and survives restart.
565
565
  */
566
566
  resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
567
- /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
568
- * `undefined` if no lease is held. Negative once expired. */
569
- leaseRemainingMs(now?: number): number | undefined;
570
567
  /** True when syncing is stopped pending a client upgrade. */
571
568
  get stopped(): boolean;
572
569
  /**
package/dist/client.js CHANGED
@@ -201,6 +201,8 @@ export class SyncClient {
201
201
  /** §7.8: restarts the running drive's round bound when rows apply. */
202
202
  #roundProgressed;
203
203
  #progressAttempt = 0;
204
+ /** §7.6: scopes `#progressAttempt`; a new core gets a new epoch. */
205
+ #epoch = crypto.randomUUID();
204
206
  /**
205
207
  * True from the synchronous entry of `sync()` until its serialized round
206
208
  * settles — the "one loop owns the database" guard that rejects a
@@ -1905,12 +1907,6 @@ export class SyncClient {
1905
1907
  throw error;
1906
1908
  });
1907
1909
  }
1908
- /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
1909
- * `undefined` if no lease is held. Negative once expired. */
1910
- leaseRemainingMs(now = this.#now()) {
1911
- const expiresAtMs = this.#leaseState?.expiresAtMs;
1912
- return expiresAtMs === undefined ? undefined : expiresAtMs - now;
1913
- }
1914
1910
  /** True when syncing is stopped pending a client upgrade. */
1915
1911
  get stopped() {
1916
1912
  return this.#schemaFloor !== undefined;
@@ -2261,12 +2257,19 @@ export class SyncClient {
2261
2257
  readCommitOutcome(this.#db, supplied)))
2262
2258
  throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
2263
2259
  const clientCommitId = supplied ?? crypto.randomUUID();
2260
+ // §7.1: a patch reads the row as the commit's earlier operations leave
2261
+ // it. Keyed by `table rowId` (a table name holds no space): the JSON
2262
+ // values an earlier upsert wrote, or null after an earlier delete. A
2263
+ // patch changes neither presence nor a scope column, so it records
2264
+ // nothing.
2265
+ const staged = new Map();
2264
2266
  const operations = mutations.map((mutation) => {
2265
2267
  const table = this.#table(mutation.table);
2266
2268
  if (mutation.op === 'delete') {
2267
2269
  // §2.4: the server rejects a rowId holding U+0000.
2268
2270
  if (mutation.rowId.includes('\u0000'))
2269
2271
  throw invalidRequest('rowId holds U+0000');
2272
+ staged.set(`${table.name} ${mutation.rowId}`, null);
2270
2273
  return definedObject({
2271
2274
  table: mutation.table,
2272
2275
  rowId: mutation.rowId,
@@ -2284,8 +2287,13 @@ export class SyncClient {
2284
2287
  const scopeColumns = new Set(table.scopeColumnByVariable.values());
2285
2288
  const pkColumn = table.columns[table.primaryKeyIndex];
2286
2289
  const pkValue = requireRowId(normalized.get(pkColumn.name));
2287
- const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, pkValue)])[0];
2288
- if (!local)
2290
+ // The base: an earlier operation's JSON values, else the stored row.
2291
+ const key = `${table.name} ${pkValue}`;
2292
+ const base = staged.get(key);
2293
+ const stored = staged.has(key)
2294
+ ? undefined
2295
+ : this.#rowById(table, pkValue);
2296
+ if (!base && !stored)
2289
2297
  throw new ClientSyncError('sync.row_missing', 'a sparse patch requires a local row');
2290
2298
  for (const column of table.columns) {
2291
2299
  if (!normalized.has(column.name))
@@ -2294,7 +2302,8 @@ export class SyncClient {
2294
2302
  // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
2295
2303
  // server accepts a present scope column whose value equals the
2296
2304
  // stored row and applies it as a no-op, so a decoded envelope
2297
- // round-trips. The local row is the only value the client can
2305
+ // round-trips. The local row, as the commit's earlier operations
2306
+ // leave it, is the only value the client can
2298
2307
  // prove equality against; when the row is absent locally the
2299
2308
  // client cannot prove equality against the server's stored row
2300
2309
  // and fails closed. A primary key that is also a scope column
@@ -2302,7 +2311,9 @@ export class SyncClient {
2302
2311
  // by construction the row id being patched (§6.1), so its value is
2303
2312
  // proven equal already.
2304
2313
  if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
2305
- if (!Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
2314
+ if (!Object.is(stored
2315
+ ? rowValueToJson(fromSqlValue(column, stored[column.name] ?? null))
2316
+ : base?.[column.name], rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
2306
2317
  throw invalidRequest('patch cannot write a scope column (§3.4)', false, at);
2307
2318
  }
2308
2319
  continue;
@@ -2337,8 +2348,9 @@ export class SyncClient {
2337
2348
  });
2338
2349
  // §7.1 insert intent: a full-row write of a row the replica does not
2339
2350
  // show replays and encodes as a full row under every later schema.
2340
- const insert = mutation.op !== 'patch' &&
2341
- this.#db.query(`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=? LIMIT 1`, [pkSqlValue(table, pkValue)]).length === 0;
2351
+ if (mutation.op !== 'patch')
2352
+ staged.set(`${table.name} ${pkValue}`, json);
2353
+ const insert = mutation.op !== 'patch' && !this.#rowById(table, pkValue, '1');
2342
2354
  return definedObject({
2343
2355
  table: mutation.table,
2344
2356
  rowId: pkValue,
@@ -2354,7 +2366,7 @@ export class SyncClient {
2354
2366
  const table = this.#table(operation.table);
2355
2367
  if (!table.hasEncryptedColumns)
2356
2368
  continue;
2357
- const keyId = this.#db.query(`SELECT ${quoteIdent(SEALED_KEY_COLUMN)} AS k FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0]?.k;
2369
+ const keyId = this.#rowById(table, operation.rowId, `${quoteIdent(SEALED_KEY_COLUMN)} AS k`)?.k;
2358
2370
  if (typeof keyId === 'string')
2359
2371
  throw new ClientSyncError('client.encryption_key_missing', 'the row is sealed under a key this device does not hold', false, { table: table.name, keyId });
2360
2372
  }
@@ -2781,7 +2793,7 @@ export class SyncClient {
2781
2793
  const selector = this.#encryption?.keyIdColumns?.[table.name];
2782
2794
  if (selector === undefined)
2783
2795
  return undefined;
2784
- const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
2796
+ const row = this.#rowById(table, rowId, `${quoteIdent(selector)} AS value`);
2785
2797
  const value = row?.value;
2786
2798
  return typeof value === 'string' && value.length > 0
2787
2799
  ? value
@@ -2955,22 +2967,36 @@ export class SyncClient {
2955
2967
  this.#syncOutstanding = true;
2956
2968
  this.#beginDiagnosticsDeferral();
2957
2969
  const startedAtMs = this.#now();
2958
- return this.#serialize(() => this.#runSync(signal))
2959
- .then((summary) => {
2970
+ // `#syncOutstanding` keeps this the attempt `#runSync` starts (§7.6).
2971
+ const attempt = this.#progressAttempt + 1;
2972
+ const round = () => {
2960
2973
  const completedAtMs = this.#now();
2961
- this.#lastRound = {
2962
- status: 'succeeded',
2974
+ return {
2975
+ epoch: this.#epoch,
2976
+ attempt,
2963
2977
  startedAtMs,
2964
2978
  completedAtMs,
2965
2979
  durationMs: Math.max(0, completedAtMs - startedAtMs),
2980
+ };
2981
+ };
2982
+ return this.#serialize(() => this.#runSync(signal))
2983
+ .then((summary) => {
2984
+ this.#lastRound = {
2985
+ status: 'succeeded',
2986
+ ...round(),
2966
2987
  counters: this.#diagnosticRoundCounters(summary),
2967
2988
  };
2968
2989
  this.#emitDiagnostics();
2969
2990
  return summary;
2970
2991
  }, (caught) => {
2971
2992
  const error = classifySqliteFailure(caught).error;
2972
- const completedAtMs = this.#now();
2993
+ // A gate refusal starts no attempt and records no round.
2994
+ if (this.#progressAttempt !== attempt)
2995
+ throw error;
2973
2996
  const code = error.code;
2997
+ const errorCode = typeof code === 'string'
2998
+ ? this.#diagnosticCode(code)
2999
+ : 'client.unknown_failure';
2974
3000
  const details = typeof error === 'object' && error !== null && 'details' in error
2975
3001
  ? error.details
2976
3002
  : undefined;
@@ -3012,24 +3038,18 @@ export class SyncClient {
3012
3038
  : undefined;
3013
3039
  this.#progress.update(definedObject({
3014
3040
  state: 'failed',
3015
- errorCode: typeof code === 'string'
3016
- ? this.#diagnosticCode(code)
3017
- : 'client.unknown_failure',
3041
+ errorCode,
3018
3042
  retryDelayMs: this.#roundRetryDelayMs,
3019
3043
  causeKind,
3020
3044
  httpStatus,
3021
3045
  }));
3022
- this.#lastRound = {
3046
+ this.#lastRound = definedObject({
3023
3047
  status: 'failed',
3024
- startedAtMs,
3025
- completedAtMs,
3026
- durationMs: Math.max(0, completedAtMs - startedAtMs),
3027
- errorCode: typeof code === 'string'
3028
- ? this.#diagnosticCode(code)
3029
- : 'client.unknown_failure',
3030
- ...(causeKind !== undefined ? { causeKind } : {}),
3031
- ...(httpStatus !== undefined ? { httpStatus } : {}),
3032
- };
3048
+ ...round(),
3049
+ errorCode,
3050
+ causeKind,
3051
+ httpStatus,
3052
+ });
3033
3053
  this.#emitDiagnostics();
3034
3054
  throw error;
3035
3055
  })
@@ -3063,6 +3083,7 @@ export class SyncClient {
3063
3083
  this.#requireTransport();
3064
3084
  this.#roundRetryDelayMs = undefined;
3065
3085
  this.#progress.emit({
3086
+ epoch: this.#epoch,
3066
3087
  attempt: ++this.#progressAttempt,
3067
3088
  state: 'running',
3068
3089
  phase: 'request',
@@ -4489,7 +4510,7 @@ export class SyncClient {
4489
4510
  const mappings = [...table.scopeColumnByVariable].filter(([variable]) => table.scopePrefixByVariable.has(variable));
4490
4511
  if (mappings.length === 0)
4491
4512
  return false;
4492
- const row = this.#db.query(`SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
4513
+ const row = this.#rowById(table, rowId, mappings.map(([, column]) => quoteIdent(column)).join());
4493
4514
  if (row === undefined)
4494
4515
  return false;
4495
4516
  let recorded = false;
@@ -4819,7 +4840,7 @@ export class SyncClient {
4819
4840
  ...table.columns.map((column) => quoteIdent(column.name)),
4820
4841
  quoteIdent(SYNC_VERSION_COLUMN),
4821
4842
  ];
4822
- const row = this.#db.query(`SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0];
4843
+ const row = this.#rowById(table, operation.rowId, columns.join());
4823
4844
  if (row === undefined)
4824
4845
  return { opIndex, existed: false };
4825
4846
  const values = {};
@@ -4861,7 +4882,7 @@ export class SyncClient {
4861
4882
  const table = this.#schema.tables.get(operation.table);
4862
4883
  if (table === undefined)
4863
4884
  continue;
4864
- const row = this.#db.query(`SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0];
4885
+ const row = this.#rowById(table, operation.rowId, `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`);
4865
4886
  if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
4866
4887
  batch.table(table.name);
4867
4888
  deleteLocalRow(this.#db, table, operation.rowId);
@@ -4947,7 +4968,7 @@ export class SyncClient {
4947
4968
  batch.table(op.table);
4948
4969
  continue;
4949
4970
  }
4950
- const local = this.#db.query(`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, op.rowId)])[0];
4971
+ const local = this.#rowById(table, op.rowId);
4951
4972
  if (local === undefined && !full) {
4952
4973
  if (batch !== undefined && !precise)
4953
4974
  batch.table(op.table);
@@ -5148,6 +5169,10 @@ export class SyncClient {
5148
5169
  deleteUnreferencedCachedBlobs(this.#db, this.#schema);
5149
5170
  }
5150
5171
  // -- helpers -----------------------------------------------------------------
5172
+ /** The local row `rowId` of `table`, selecting `columns`. */
5173
+ #rowById(table, rowId, columns = '*') {
5174
+ return this.#db.query(`SELECT ${columns} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
5175
+ }
5151
5176
  #table(name) {
5152
5177
  const table = this.#schema.tables.get(name);
5153
5178
  if (table === undefined) {
@@ -56,14 +56,19 @@ export interface DiagnosticRoundCounters {
56
56
  readonly failed: number;
57
57
  readonly deferredCommits: number;
58
58
  }
59
+ /** One completed sync round. `(epoch, attempt)` identifies it (SPEC §7.6). */
59
60
  export type DiagnosticLastRound = {
60
61
  readonly status: 'succeeded';
62
+ readonly epoch: string;
63
+ readonly attempt: number;
61
64
  readonly startedAtMs: number;
62
65
  readonly completedAtMs: number;
63
66
  readonly durationMs: number;
64
67
  readonly counters: DiagnosticRoundCounters;
65
68
  } | {
66
69
  readonly status: 'failed';
70
+ readonly epoch: string;
71
+ readonly attempt: number;
67
72
  readonly startedAtMs: number;
68
73
  readonly completedAtMs: number;
69
74
  readonly durationMs: number;
@@ -73,7 +73,6 @@ export interface CommandResult<T> {
73
73
  readonly value: T;
74
74
  readonly effects: CommandEffects;
75
75
  }
76
- export declare const NO_COMMAND_EFFECTS: CommandEffects;
77
76
  /**
78
77
  * Per-observer-transaction accumulator. It contains no revision itself: the
79
78
  * transaction wrapper assigns the revision only after all writes succeeded.
@@ -1,6 +1,3 @@
1
- export const NO_COMMAND_EFFECTS = {
2
- sync: { kind: 'none' },
3
- };
4
1
  /**
5
2
  * Per-observer-transaction accumulator. It contains no revision itself: the
6
3
  * transaction wrapper assigns the revision only after all writes succeeded.
@@ -1,6 +1,8 @@
1
1
  import type { TransportCauseKind } from './diagnostics.js';
2
2
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
3
3
  export interface SyncProgress {
4
+ /** Random per client core; `(epoch, attempt)` identifies the attempt (SPEC §7.6). */
5
+ readonly epoch: string;
4
6
  readonly attempt: number;
5
7
  readonly state: 'running' | 'complete' | 'failed';
6
8
  readonly phase: 'request' | 'download' | 'import';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.82.3",
3
+ "version": "0.84.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.82.3"
124
+ "@syncular/core": "0.84.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.82.3",
128
+ "@syncular/server": "0.84.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/client.ts CHANGED
@@ -989,6 +989,8 @@ export class SyncClient {
989
989
  /** §7.8: restarts the running drive's round bound when rows apply. */
990
990
  #roundProgressed: (() => void) | undefined;
991
991
  #progressAttempt = 0;
992
+ /** §7.6: scopes `#progressAttempt`; a new core gets a new epoch. */
993
+ readonly #epoch = crypto.randomUUID();
992
994
  /**
993
995
  * True from the synchronous entry of `sync()` until its serialized round
994
996
  * settles — the "one loop owns the database" guard that rejects a
@@ -3031,13 +3033,6 @@ export class SyncClient {
3031
3033
  );
3032
3034
  }
3033
3035
 
3034
- /** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
3035
- * `undefined` if no lease is held. Negative once expired. */
3036
- leaseRemainingMs(now: number = this.#now()): number | undefined {
3037
- const expiresAtMs = this.#leaseState?.expiresAtMs;
3038
- return expiresAtMs === undefined ? undefined : expiresAtMs - now;
3039
- }
3040
-
3041
3036
  /** True when syncing is stopped pending a client upgrade. */
3042
3037
  get stopped(): boolean {
3043
3038
  return this.#schemaFloor !== undefined;
@@ -3463,12 +3458,19 @@ export class SyncClient {
3463
3458
  { clientCommitId: supplied },
3464
3459
  );
3465
3460
  const clientCommitId = supplied ?? crypto.randomUUID();
3461
+ // §7.1: a patch reads the row as the commit's earlier operations leave
3462
+ // it. Keyed by `table rowId` (a table name holds no space): the JSON
3463
+ // values an earlier upsert wrote, or null after an earlier delete. A
3464
+ // patch changes neither presence nor a scope column, so it records
3465
+ // nothing.
3466
+ const staged = new Map<string, Record<string, JsonRowValue> | null>();
3466
3467
  const operations: OutboxOperation[] = mutations.map((mutation) => {
3467
3468
  const table = this.#table(mutation.table);
3468
3469
  if (mutation.op === 'delete') {
3469
3470
  // §2.4: the server rejects a rowId holding U+0000.
3470
3471
  if (mutation.rowId.includes('\u0000'))
3471
3472
  throw invalidRequest('rowId holds U+0000');
3473
+ staged.set(`${table.name} ${mutation.rowId}`, null);
3472
3474
  return definedObject({
3473
3475
  table: mutation.table,
3474
3476
  rowId: mutation.rowId,
@@ -3486,11 +3488,13 @@ export class SyncClient {
3486
3488
  const scopeColumns = new Set(table.scopeColumnByVariable.values());
3487
3489
  const pkColumn = table.columns[table.primaryKeyIndex] as RowColumn;
3488
3490
  const pkValue = requireRowId(normalized.get(pkColumn.name));
3489
- const local = this.#db.query(
3490
- `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
3491
- [pkSqlValue(table, pkValue)],
3492
- )[0];
3493
- if (!local)
3491
+ // The base: an earlier operation's JSON values, else the stored row.
3492
+ const key = `${table.name} ${pkValue}`;
3493
+ const base = staged.get(key);
3494
+ const stored = staged.has(key)
3495
+ ? undefined
3496
+ : this.#rowById(table, pkValue);
3497
+ if (!base && !stored)
3494
3498
  throw new ClientSyncError(
3495
3499
  'sync.row_missing',
3496
3500
  'a sparse patch requires a local row',
@@ -3501,7 +3505,8 @@ export class SyncClient {
3501
3505
  // §3.4 rule 5 / §6.2: scope columns are immutable on update. The
3502
3506
  // server accepts a present scope column whose value equals the
3503
3507
  // stored row and applies it as a no-op, so a decoded envelope
3504
- // round-trips. The local row is the only value the client can
3508
+ // round-trips. The local row, as the commit's earlier operations
3509
+ // leave it, is the only value the client can
3505
3510
  // prove equality against; when the row is absent locally the
3506
3511
  // client cannot prove equality against the server's stored row
3507
3512
  // and fails closed. A primary key that is also a scope column
@@ -3511,9 +3516,11 @@ export class SyncClient {
3511
3516
  if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
3512
3517
  if (
3513
3518
  !Object.is(
3514
- rowValueToJson(
3515
- fromSqlValue(column, local[column.name] ?? null),
3516
- ),
3519
+ stored
3520
+ ? rowValueToJson(
3521
+ fromSqlValue(column, stored[column.name] ?? null),
3522
+ )
3523
+ : base?.[column.name],
3517
3524
  rowValueToJson(
3518
3525
  coerceSqlRepresentation(
3519
3526
  column,
@@ -3570,12 +3577,9 @@ export class SyncClient {
3570
3577
  );
3571
3578
  // §7.1 insert intent: a full-row write of a row the replica does not
3572
3579
  // show replays and encodes as a full row under every later schema.
3580
+ if (mutation.op !== 'patch') staged.set(`${table.name} ${pkValue}`, json);
3573
3581
  const insert =
3574
- mutation.op !== 'patch' &&
3575
- this.#db.query(
3576
- `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=? LIMIT 1`,
3577
- [pkSqlValue(table, pkValue)],
3578
- ).length === 0;
3582
+ mutation.op !== 'patch' && !this.#rowById(table, pkValue, '1');
3579
3583
  return definedObject({
3580
3584
  table: mutation.table,
3581
3585
  rowId: pkValue,
@@ -3590,10 +3594,11 @@ export class SyncClient {
3590
3594
  for (const operation of operations) {
3591
3595
  const table = this.#table(operation.table);
3592
3596
  if (!table.hasEncryptedColumns) continue;
3593
- const keyId = this.#db.query(
3594
- `SELECT ${quoteIdent(SEALED_KEY_COLUMN)} AS k FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
3595
- [pkSqlValue(table, operation.rowId)],
3596
- )[0]?.k;
3597
+ const keyId = this.#rowById(
3598
+ table,
3599
+ operation.rowId,
3600
+ `${quoteIdent(SEALED_KEY_COLUMN)} AS k`,
3601
+ )?.k;
3597
3602
  if (typeof keyId === 'string')
3598
3603
  throw new ClientSyncError(
3599
3604
  'client.encryption_key_missing',
@@ -4127,10 +4132,11 @@ export class SyncClient {
4127
4132
  (table, rowId) => {
4128
4133
  const selector = this.#encryption?.keyIdColumns?.[table.name];
4129
4134
  if (selector === undefined) return undefined;
4130
- const row = this.#db.query(
4131
- `SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
4132
- [pkSqlValue(table, rowId)],
4133
- )[0];
4135
+ const row = this.#rowById(
4136
+ table,
4137
+ rowId,
4138
+ `${quoteIdent(selector)} AS value`,
4139
+ );
4134
4140
  const value = row?.value;
4135
4141
  return typeof value === 'string' && value.length > 0
4136
4142
  ? value
@@ -4364,15 +4370,24 @@ export class SyncClient {
4364
4370
  this.#syncOutstanding = true;
4365
4371
  this.#beginDiagnosticsDeferral();
4366
4372
  const startedAtMs = this.#now();
4373
+ // `#syncOutstanding` keeps this the attempt `#runSync` starts (§7.6).
4374
+ const attempt = this.#progressAttempt + 1;
4375
+ const round = () => {
4376
+ const completedAtMs = this.#now();
4377
+ return {
4378
+ epoch: this.#epoch,
4379
+ attempt,
4380
+ startedAtMs,
4381
+ completedAtMs,
4382
+ durationMs: Math.max(0, completedAtMs - startedAtMs),
4383
+ };
4384
+ };
4367
4385
  return this.#serialize(() => this.#runSync(signal))
4368
4386
  .then(
4369
4387
  (summary) => {
4370
- const completedAtMs = this.#now();
4371
4388
  this.#lastRound = {
4372
4389
  status: 'succeeded',
4373
- startedAtMs,
4374
- completedAtMs,
4375
- durationMs: Math.max(0, completedAtMs - startedAtMs),
4390
+ ...round(),
4376
4391
  counters: this.#diagnosticRoundCounters(summary),
4377
4392
  };
4378
4393
  this.#emitDiagnostics();
@@ -4380,8 +4395,13 @@ export class SyncClient {
4380
4395
  },
4381
4396
  (caught: unknown) => {
4382
4397
  const error = classifySqliteFailure(caught).error;
4383
- const completedAtMs = this.#now();
4398
+ // A gate refusal starts no attempt and records no round.
4399
+ if (this.#progressAttempt !== attempt) throw error;
4384
4400
  const code = (error as { code?: unknown }).code;
4401
+ const errorCode =
4402
+ typeof code === 'string'
4403
+ ? this.#diagnosticCode(code)
4404
+ : 'client.unknown_failure';
4385
4405
  const details =
4386
4406
  typeof error === 'object' && error !== null && 'details' in error
4387
4407
  ? error.details
@@ -4428,27 +4448,19 @@ export class SyncClient {
4428
4448
  this.#progress.update(
4429
4449
  definedObject({
4430
4450
  state: 'failed',
4431
- errorCode:
4432
- typeof code === 'string'
4433
- ? this.#diagnosticCode(code)
4434
- : 'client.unknown_failure',
4451
+ errorCode,
4435
4452
  retryDelayMs: this.#roundRetryDelayMs,
4436
4453
  causeKind,
4437
4454
  httpStatus,
4438
4455
  }),
4439
4456
  );
4440
- this.#lastRound = {
4457
+ this.#lastRound = definedObject({
4441
4458
  status: 'failed',
4442
- startedAtMs,
4443
- completedAtMs,
4444
- durationMs: Math.max(0, completedAtMs - startedAtMs),
4445
- errorCode:
4446
- typeof code === 'string'
4447
- ? this.#diagnosticCode(code)
4448
- : 'client.unknown_failure',
4449
- ...(causeKind !== undefined ? { causeKind } : {}),
4450
- ...(httpStatus !== undefined ? { httpStatus } : {}),
4451
- };
4459
+ ...round(),
4460
+ errorCode,
4461
+ causeKind,
4462
+ httpStatus,
4463
+ });
4452
4464
  this.#emitDiagnostics();
4453
4465
  throw error;
4454
4466
  },
@@ -4485,6 +4497,7 @@ export class SyncClient {
4485
4497
  this.#requireTransport();
4486
4498
  this.#roundRetryDelayMs = undefined;
4487
4499
  this.#progress.emit({
4500
+ epoch: this.#epoch,
4488
4501
  attempt: ++this.#progressAttempt,
4489
4502
  state: 'running',
4490
4503
  phase: 'request',
@@ -6176,10 +6189,11 @@ export class SyncClient {
6176
6189
  table.scopePrefixByVariable.has(variable),
6177
6190
  );
6178
6191
  if (mappings.length === 0) return false;
6179
- const row = this.#db.query(
6180
- `SELECT ${mappings.map(([, column]) => quoteIdent(column)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
6181
- [pkSqlValue(table, rowId)],
6182
- )[0];
6192
+ const row = this.#rowById(
6193
+ table,
6194
+ rowId,
6195
+ mappings.map(([, column]) => quoteIdent(column)).join(),
6196
+ );
6183
6197
  if (row === undefined) return false;
6184
6198
  let recorded = false;
6185
6199
  for (const [variable, column] of mappings) {
@@ -6613,10 +6627,7 @@ export class SyncClient {
6613
6627
  ...table.columns.map((column) => quoteIdent(column.name)),
6614
6628
  quoteIdent(SYNC_VERSION_COLUMN),
6615
6629
  ];
6616
- const row = this.#db.query(
6617
- `SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
6618
- [pkSqlValue(table, operation.rowId)],
6619
- )[0];
6630
+ const row = this.#rowById(table, operation.rowId, columns.join());
6620
6631
  if (row === undefined) return { opIndex, existed: false };
6621
6632
  const values: Record<string, ReturnType<typeof rowValueToJson>> = {};
6622
6633
  for (const column of table.columns) {
@@ -6679,10 +6690,11 @@ export class SyncClient {
6679
6690
  if (operation.op !== 'upsert') continue;
6680
6691
  const table = this.#schema.tables.get(operation.table);
6681
6692
  if (table === undefined) continue;
6682
- const row = this.#db.query(
6683
- `SELECT ${quoteIdent(SYNC_VERSION_COLUMN)} AS v FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
6684
- [pkSqlValue(table, operation.rowId)],
6685
- )[0];
6693
+ const row = this.#rowById(
6694
+ table,
6695
+ operation.rowId,
6696
+ `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`,
6697
+ );
6686
6698
  if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
6687
6699
  batch.table(table.name);
6688
6700
  deleteLocalRow(this.#db, table, operation.rowId);
@@ -6787,10 +6799,7 @@ export class SyncClient {
6787
6799
  if (batch !== undefined && !precise) batch.table(op.table);
6788
6800
  continue;
6789
6801
  }
6790
- const local = this.#db.query(
6791
- `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
6792
- [pkSqlValue(table, op.rowId)],
6793
- )[0];
6802
+ const local = this.#rowById(table, op.rowId);
6794
6803
  if (local === undefined && !full) {
6795
6804
  if (batch !== undefined && !precise) batch.table(op.table);
6796
6805
  continue;
@@ -7045,6 +7054,18 @@ export class SyncClient {
7045
7054
 
7046
7055
  // -- helpers -----------------------------------------------------------------
7047
7056
 
7057
+ /** The local row `rowId` of `table`, selecting `columns`. */
7058
+ #rowById(
7059
+ table: CompiledClientTable,
7060
+ rowId: string,
7061
+ columns = '*',
7062
+ ): SqlRow | undefined {
7063
+ return this.#db.query(
7064
+ `SELECT ${columns} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
7065
+ [pkSqlValue(table, rowId)],
7066
+ )[0];
7067
+ }
7068
+
7048
7069
  #table(name: string): CompiledClientTable {
7049
7070
  const table = this.#schema.tables.get(name);
7050
7071
  if (table === undefined) {
@@ -91,9 +91,12 @@ export interface DiagnosticRoundCounters {
91
91
  readonly deferredCommits: number;
92
92
  }
93
93
 
94
+ /** One completed sync round. `(epoch, attempt)` identifies it (SPEC §7.6). */
94
95
  export type DiagnosticLastRound =
95
96
  | {
96
97
  readonly status: 'succeeded';
98
+ readonly epoch: string;
99
+ readonly attempt: number;
97
100
  readonly startedAtMs: number;
98
101
  readonly completedAtMs: number;
99
102
  readonly durationMs: number;
@@ -101,6 +104,8 @@ export type DiagnosticLastRound =
101
104
  }
102
105
  | {
103
106
  readonly status: 'failed';
107
+ readonly epoch: string;
108
+ readonly attempt: number;
104
109
  readonly startedAtMs: number;
105
110
  readonly completedAtMs: number;
106
111
  readonly durationMs: number;
@@ -79,10 +79,6 @@ export interface CommandResult<T> {
79
79
  readonly effects: CommandEffects;
80
80
  }
81
81
 
82
- export const NO_COMMAND_EFFECTS: CommandEffects = {
83
- sync: { kind: 'none' },
84
- };
85
-
86
82
  interface MutableTableChange {
87
83
  tableWide: boolean;
88
84
  scopeKeys: Set<string> | undefined;
package/src/progress.ts CHANGED
@@ -2,6 +2,8 @@ import type { TransportCauseKind } from './diagnostics';
2
2
 
3
3
  /** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
4
4
  export interface SyncProgress {
5
+ /** Random per client core; `(epoch, attempt)` identifies the attempt (SPEC §7.6). */
6
+ readonly epoch: string;
5
7
  readonly attempt: number;
6
8
  readonly state: 'running' | 'complete' | 'failed';
7
9
  readonly phase: 'request' | 'download' | 'import';