@syncular/server 0.57.0 → 0.59.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 (91) hide show
  1. package/README.md +31 -22
  2. package/dist/admin.js +8 -4
  3. package/dist/blob-handlers.d.ts +25 -31
  4. package/dist/blob-handlers.js +63 -41
  5. package/dist/blob-store.d.ts +42 -24
  6. package/dist/blob-store.js +0 -0
  7. package/dist/bucket-blob-store.d.ts +12 -8
  8. package/dist/bucket-blob-store.js +54 -45
  9. package/dist/bucket-segment-store.js +18 -16
  10. package/dist/content-encoding.d.ts +5 -2
  11. package/dist/content-encoding.js +42 -13
  12. package/dist/context.d.ts +16 -0
  13. package/dist/context.js +21 -1
  14. package/dist/d1-storage.d.ts +14 -98
  15. package/dist/d1-storage.js +223 -1111
  16. package/dist/errors.js +8 -0
  17. package/dist/events.d.ts +1 -1
  18. package/dist/handler.js +135 -103
  19. package/dist/local-authority.d.ts +2 -0
  20. package/dist/local-authority.js +17 -3
  21. package/dist/object-bucket.d.ts +2 -0
  22. package/dist/operations-realtime.js +69 -50
  23. package/dist/pg-executor-pglite.d.ts +5 -6
  24. package/dist/pg-executor-pglite.js +22 -14
  25. package/dist/pg-executor.d.ts +4 -1
  26. package/dist/postgres-storage.d.ts +1 -1
  27. package/dist/postgres-storage.js +182 -105
  28. package/dist/pull.d.ts +28 -20
  29. package/dist/pull.js +85 -87
  30. package/dist/push.js +272 -147
  31. package/dist/realtime.d.ts +68 -28
  32. package/dist/realtime.js +297 -136
  33. package/dist/relational-rows.d.ts +27 -15
  34. package/dist/relational-rows.js +38 -22
  35. package/dist/s3-blob-store.d.ts +11 -12
  36. package/dist/s3-blob-store.js +20 -13
  37. package/dist/s3-object-bucket.d.ts +8 -1
  38. package/dist/s3-object-bucket.js +16 -3
  39. package/dist/schema.d.ts +14 -0
  40. package/dist/schema.js +23 -0
  41. package/dist/scopes.d.ts +6 -2
  42. package/dist/scopes.js +22 -4
  43. package/dist/seed.js +1 -2
  44. package/dist/segment-download.js +18 -4
  45. package/dist/signed-url.d.ts +2 -2
  46. package/dist/signed-url.js +9 -2
  47. package/dist/sigv4.d.ts +8 -2
  48. package/dist/sigv4.js +8 -4
  49. package/dist/sqlite-blob-store.d.ts +1 -1
  50. package/dist/sqlite-blob-store.js +23 -22
  51. package/dist/sqlite-dialect.d.ts +150 -47
  52. package/dist/sqlite-dialect.js +987 -88
  53. package/dist/sqlite-lease-store.js +13 -18
  54. package/dist/sqlite-storage.d.ts +9 -62
  55. package/dist/sqlite-storage.js +293 -1117
  56. package/dist/storage.d.ts +32 -12
  57. package/package.json +2 -2
  58. package/src/admin.ts +16 -2
  59. package/src/blob-handlers.ts +91 -72
  60. package/src/blob-store.ts +0 -0
  61. package/src/bucket-blob-store.ts +75 -48
  62. package/src/bucket-segment-store.ts +20 -15
  63. package/src/content-encoding.ts +48 -16
  64. package/src/context.ts +32 -1
  65. package/src/d1-storage.ts +326 -1692
  66. package/src/errors.ts +8 -0
  67. package/src/events.ts +1 -1
  68. package/src/handler.ts +178 -127
  69. package/src/local-authority.ts +17 -3
  70. package/src/object-bucket.ts +2 -0
  71. package/src/operations-realtime.ts +85 -61
  72. package/src/pg-executor-pglite.ts +27 -23
  73. package/src/pg-executor.ts +5 -1
  74. package/src/postgres-storage.ts +231 -138
  75. package/src/pull.ts +133 -147
  76. package/src/push.ts +356 -205
  77. package/src/realtime.ts +380 -179
  78. package/src/relational-rows.ts +54 -27
  79. package/src/s3-blob-store.ts +23 -13
  80. package/src/s3-object-bucket.ts +20 -2
  81. package/src/schema.ts +31 -0
  82. package/src/scopes.ts +23 -3
  83. package/src/seed.ts +1 -2
  84. package/src/segment-download.ts +25 -4
  85. package/src/signed-url.ts +10 -4
  86. package/src/sigv4.ts +17 -4
  87. package/src/sqlite-blob-store.ts +27 -26
  88. package/src/sqlite-dialect.ts +1607 -114
  89. package/src/sqlite-lease-store.ts +12 -23
  90. package/src/sqlite-storage.ts +360 -1811
  91. package/src/storage.ts +33 -12
@@ -1,16 +1,8 @@
1
- import { retainRollbackFailure, rollbackAfterError } from './storage-errors';
2
- import { validateCommitPruneQuery } from './prune';
3
- import { StorageQueryError } from './storage-errors';
4
- import type { CommitPruneQuery, CommitPruneResult } from './storage';
5
- import {
6
- clientRoundState,
7
- PARTITION_TOUCH_INTERVAL_MS,
8
- rowsLiveAfterDelete,
9
- serveGateRefusal,
10
- } from './storage';
11
- import { serveNotReadyError } from './readiness';
12
1
  /**
13
- * SQLite server storage over the shared synchronous driver.
2
+ * SQLite server storage over the shared synchronous driver. The statements
3
+ * it shares with D1 live in `SqliteFamilyStorage` (`sqlite-dialect.ts`);
4
+ * this class adds the request lock, interactive `BEGIN IMMEDIATE`
5
+ * transactions, in-place schema migration and backfill checkpoints.
14
6
  *
15
7
  * Scope fanout is index-first: both the commit log and the
16
8
  * current-row table carry a (table, variable, value) inverted index; reads
@@ -18,119 +10,63 @@ import { serveNotReadyError } from './readiness';
18
10
  * match against the stored scope map — never a log scan.
19
11
  */
20
12
  import {
21
- bindAuthoritativePartition,
22
- prepareAuthoritativeQuery,
23
- } from './authoritative-query';
24
- import type { ScopeMap } from '@syncular/core';
25
- import { syncError } from './errors';
13
+ isSqliteConstraintError,
14
+ retainRollbackFailure,
15
+ rollbackAfterError,
16
+ StorageConstraintError,
17
+ StorageQueryError,
18
+ } from './storage-errors';
19
+ import { serveGateRefusal } from './storage';
20
+ import { serveNotReadyError } from './readiness';
26
21
  import {
27
22
  assertPhysicalColumns,
28
23
  assertStoredLayouts,
29
- commitWindowPageSql,
30
- LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
31
- deleteRowSql,
32
- deleteSqliteRowScopesSql,
33
24
  dropTableDdl,
34
- indexRowPageStatement,
35
25
  layoutsOf,
36
26
  migratePayload,
37
27
  parseLayouts,
38
- quoteIdent,
39
28
  retiredTableNames,
40
29
  rewritePlan,
41
30
  rewriteRowSql,
42
31
  rewriteValues,
43
32
  SCHEMA_META_DDL_SQLITE,
44
- SYNC_COLUMN_VERSIONS_COLUMN,
45
- SYNC_PARTITION_COLUMN,
46
- SYNC_PAYLOAD_COLUMN,
47
- SYNC_ROW_ID_COLUMN,
48
- SYNC_SCOPES_COLUMN,
49
- SYNC_VERSION_COLUMN,
50
33
  type StoredColumnLayout,
51
- scanRowPageSql,
52
34
  schemaDdl,
53
35
  serverIndexDdl,
54
36
  SQLITE_TABLE_INDEXES_SQL,
55
37
  type SqliteTableIndexRow,
56
38
  sqliteIndexSignatures,
57
- selectRowScopesSql,
58
- selectRowSql,
59
39
  selectRowsForRewriteSql,
60
- upsertSql,
61
- upsertValues,
62
40
  } from './relational-rows';
63
41
  import type { CompiledSchema, CompiledTable } from './schema';
64
- import { matchesEffective } from './scopes';
65
42
  import {
66
- collectCommitWindowPage,
67
- deserializePushResult,
68
- ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL,
69
- eraseScopeValueHistoryParams,
70
- LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
71
- placeholders,
43
+ SQLITE_ADDED_COLUMNS,
72
44
  SQLITE_DDL,
73
- SYNC_CLIENT_ROUND_COLUMNS,
74
- type SqliteChangeRecord,
75
- type SqliteCommitWindowRecord,
76
- type SqliteRowRecord,
77
- serializePushResult,
78
- toStoredChange,
79
- toStoredRow,
45
+ SqliteFamilyStorage,
46
+ SqliteFamilyTransaction,
47
+ type SqliteStatementSpec,
80
48
  } from './sqlite-dialect';
81
49
  import {
82
50
  SqliteAdapterRequiredError,
83
51
  type SqliteDatabase,
52
+ type SqliteValue,
84
53
  } from './sqlite-driver';
85
54
  import type {
86
55
  AuthoritativeQueryRequest,
87
56
  AuthoritativeQueryResult,
88
57
  AuthoritativeQueryValue,
89
58
  CheckpointDeclaration,
90
- ClientCursorInfo,
91
- ClientPushResult,
92
- ClientRecord,
93
- ClientRecordWriteOptions,
94
- ClientSubscription,
95
- CommitChangeSummary,
96
- CommitDetail,
97
- CommitMetadata,
98
- CommitMetadataQuery,
99
- CommitWindowQuery,
100
- DurableJsonValue,
101
59
  IndexRowScanQuery,
102
60
  NewCommit,
103
- NewReaction,
104
61
  PreparedPushApply,
105
- PartitionRegistryEntry,
106
- PrunedReactionCounts,
107
- ReactionClaimQuery,
108
- ReactionFailure,
109
- ReactionFailureUpdate,
110
- ReactionListQuery,
111
- ReactionPruneQuery,
112
- RowChangeRecord,
113
- RowChangesQuery,
114
- RowListQuery,
115
62
  RowScanQuery,
116
- ScopeActivityQuery,
117
- ScopeCommitActivity,
118
- ScopeValueHistoryQuery,
119
- ScopeValueQuery,
120
63
  ServerStorage,
121
64
  ServeGate,
122
65
  StorageTransaction,
123
- StoredCommit,
124
66
  StoredCheckpoint,
125
67
  StoredPushResult,
126
- StoredReaction,
127
68
  StoredRow,
128
69
  } from './storage';
129
- import {
130
- isSqliteConstraintError,
131
- StorageConstraintError,
132
- } from './storage-errors';
133
- import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
134
70
 
135
71
  interface SqliteCheckpointRecord {
136
72
  partition: string;
@@ -156,59 +92,13 @@ function toStoredCheckpoint(record: SqliteCheckpointRecord): StoredCheckpoint {
156
92
  };
157
93
  }
158
94
 
159
- interface SqliteReactionRecord {
160
- partition: string;
161
- idempotency_key: string;
162
- type: string;
163
- version: number;
164
- payload: string;
165
- source_client_id: string;
166
- source_client_commit_id: string;
167
- source_commit_seq: number;
168
- created_at_ms: number;
169
- available_at_ms: number;
170
- status: StoredReaction['status'];
171
- attempts: number;
172
- max_attempts: number;
173
- lease_owner: string | null;
174
- lease_expires_at_ms: number | null;
175
- completed_at_ms: number | null;
176
- last_failure: string | null;
177
- }
178
-
179
- function toStoredReaction(record: SqliteReactionRecord): StoredReaction {
180
- return {
181
- idempotencyKey: record.idempotency_key,
182
- type: record.type,
183
- version: record.version,
184
- payload: JSON.parse(record.payload) as DurableJsonValue,
185
- sourceClientId: record.source_client_id,
186
- sourceClientCommitId: record.source_client_commit_id,
187
- sourceCommitSeq: record.source_commit_seq,
188
- createdAtMs: record.created_at_ms,
189
- maxAttempts: record.max_attempts,
190
- status: record.status,
191
- attempts: record.attempts,
192
- availableAtMs: record.available_at_ms,
193
- ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
194
- ...(record.lease_expires_at_ms !== null
195
- ? { leaseExpiresAtMs: record.lease_expires_at_ms }
196
- : {}),
197
- ...(record.completed_at_ms !== null
198
- ? { completedAtMs: record.completed_at_ms }
199
- : {}),
200
- ...(record.last_failure !== null
201
- ? { lastFailure: JSON.parse(record.last_failure) as ReactionFailure }
202
- : {}),
203
- };
204
- }
205
-
206
- class SqliteTransaction implements StorageTransaction {
95
+ class SqliteTransaction
96
+ extends SqliteFamilyTransaction
97
+ implements StorageTransaction
98
+ {
207
99
  #storage: SqliteServerStorage;
208
- #partition: string;
209
100
  /** Schema version this transaction writes; rides every appended commit row. */
210
101
  #writerVersion: number;
211
- #open = true;
212
102
  #pushApplySavepoint = false;
213
103
  readonly #release: () => void;
214
104
 
@@ -218,75 +108,50 @@ class SqliteTransaction implements StorageTransaction {
218
108
  writerVersion: number,
219
109
  release: () => void,
220
110
  ) {
111
+ super(partition);
221
112
  this.#storage = storage;
222
- this.#partition = partition;
223
113
  this.#writerVersion = writerVersion;
224
114
  this.#release = release;
225
115
  storage.db.exec('BEGIN IMMEDIATE');
226
116
  }
227
117
 
228
- #assertOpen(): void {
229
- if (!this.#open) throw new Error('transaction already finished');
230
- }
231
-
232
- getRow(table: string, rowId: string): Promise<StoredRow | undefined> {
233
- this.#assertOpen();
234
- return this.#storage.getRow(this.#partition, table, rowId);
118
+ protected run(sql: string, params: readonly SqliteValue[]): void {
119
+ this.#storage.db.run(sql, params);
235
120
  }
236
121
 
237
- async getRows(
238
- table: string,
239
- rowIds: readonly string[],
240
- ): Promise<ReadonlyMap<string, StoredRow>> {
241
- this.#assertOpen();
242
- // SQLite is in-process: one indexed lookup per id costs no round trip.
243
- const rows = new Map<string, StoredRow>();
244
- for (const rowId of new Set(rowIds)) {
245
- const row = await this.#storage.getRow(this.#partition, table, rowId);
246
- if (row !== undefined) rows.set(rowId, row);
247
- }
248
- return rows;
122
+ protected async all<T>(
123
+ sql: string,
124
+ params: readonly SqliteValue[],
125
+ ): Promise<T[]> {
126
+ return this.#storage.db.query<T, SqliteValue[]>(sql).all(...params);
249
127
  }
250
128
 
251
- async getTombstoneSeq(
252
- table: string,
253
- rowId: string,
254
- ): Promise<number | undefined> {
255
- this.#assertOpen();
256
- const row = this.#storage.db
257
- .query<{ commit_seq: number }, [string, string, string]>(
258
- 'SELECT commit_seq FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
259
- )
260
- .get(this.#partition, table, rowId);
261
- return row?.commit_seq;
129
+ protected table(name: string): CompiledTable {
130
+ return this.#storage.table(name);
262
131
  }
263
132
 
264
- async clearTombstone(table: string, rowId: string): Promise<void> {
265
- this.#assertOpen();
266
- this.#storage.db
267
- .query(
268
- 'DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
269
- )
270
- .run(this.#partition, table, rowId);
133
+ getRow(table: string, rowId: string): Promise<StoredRow | undefined> {
134
+ this.assertOpen();
135
+ return this.#storage.getRow(this.partition, table, rowId);
271
136
  }
272
137
 
273
138
  scanRows(query: RowScanQuery): Promise<StoredRow[]> {
274
- this.#assertOpen();
275
- return this.#storage.scanRows(this.#partition, query);
139
+ this.assertOpen();
140
+ return this.#storage.scanRows(this.partition, query);
276
141
  }
277
142
 
278
143
  scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
279
- this.#assertOpen();
280
- return this.#storage.scanRowsByIndex(this.#partition, query);
144
+ this.assertOpen();
145
+ return this.#storage.scanRowsByIndex(this.partition, query);
281
146
  }
282
147
 
283
148
  async queryAuthoritative(
284
149
  query: AuthoritativeQueryRequest,
285
150
  ): Promise<AuthoritativeQueryResult> {
286
- this.#assertOpen();
151
+ this.assertOpen();
287
152
  // Same shared connection: the query runs inside this transaction's
288
153
  // BEGIN IMMEDIATE and observes every row staged so far.
289
- return this.#storage.runAuthoritativeQuery(this.#partition, query);
154
+ return this.#storage.runAuthoritativeQuery(this.partition, query);
290
155
  }
291
156
 
292
157
  async preparePushApply(
@@ -298,17 +163,17 @@ class SqliteTransaction implements StorageTransaction {
298
163
  readonly rowIds: readonly string[];
299
164
  }[] = [],
300
165
  ): Promise<PreparedPushApply> {
301
- this.#assertOpen();
166
+ this.assertOpen();
302
167
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
303
168
  this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
304
169
  this.#pushApplySavepoint = true;
305
170
  return {
306
171
  gate: await this.#storage.readServeGate(
307
- this.#partition,
172
+ this.partition,
308
173
  runningSchemaVersion,
309
174
  ),
310
175
  persisted: await this.#storage.getPushResult(
311
- this.#partition,
176
+ this.partition,
312
177
  clientId,
313
178
  clientCommitId,
314
179
  ),
@@ -316,7 +181,7 @@ class SqliteTransaction implements StorageTransaction {
316
181
  }
317
182
 
318
183
  async lockPartition(): Promise<void> {
319
- this.#assertOpen();
184
+ this.assertOpen();
320
185
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
321
186
  }
322
187
 
@@ -327,22 +192,22 @@ class SqliteTransaction implements StorageTransaction {
327
192
  observedRows: number,
328
193
  nowMs: number,
329
194
  ): Promise<boolean> {
330
- this.#assertOpen();
195
+ this.assertOpen();
331
196
  const result = this.#storage.db
332
197
  .query(
333
198
  `UPDATE sync_backfill_checkpoints
334
199
  SET watermark=?, observed_rows=?, updated_at_ms=?
335
200
  WHERE partition=? AND name=? AND owner_epoch=?`,
336
201
  )
337
- .run(watermark, observedRows, nowMs, this.#partition, name, ownerEpoch);
202
+ .run(watermark, observedRows, nowMs, this.partition, name, ownerEpoch);
338
203
  return Number(result.changes) === 1;
339
204
  }
340
205
 
341
206
  readServeGate(runningSchemaVersion: number): Promise<ServeGate> {
342
- this.#assertOpen();
207
+ this.assertOpen();
343
208
  // Same shared connection: this read runs inside this transaction's
344
209
  // BEGIN IMMEDIATE, so the gate and the write share one transaction.
345
- return this.#storage.readServeGate(this.#partition, runningSchemaVersion);
210
+ return this.#storage.readServeGate(this.partition, runningSchemaVersion);
346
211
  }
347
212
 
348
213
  async commitRejectedPushResult(
@@ -350,7 +215,7 @@ class SqliteTransaction implements StorageTransaction {
350
215
  clientCommitId: string,
351
216
  result: StoredPushResult,
352
217
  ): Promise<StoredPushResult> {
353
- this.#assertOpen();
218
+ this.assertOpen();
354
219
  if (!this.#pushApplySavepoint) {
355
220
  throw new Error('push rejection requires its apply savepoint');
356
221
  }
@@ -369,9 +234,9 @@ class SqliteTransaction implements StorageTransaction {
369
234
  row: StoredRow,
370
235
  context?: { readonly opIndex: number },
371
236
  ): Promise<void> {
372
- this.#assertOpen();
237
+ this.assertOpen();
373
238
  try {
374
- this.#storage.writeRow(this.#partition, table, row);
239
+ this.writeRow(table, row);
375
240
  } catch (error) {
376
241
  if (isSqliteConstraintError(error)) {
377
242
  throw new StorageConstraintError(error, context?.opIndex);
@@ -380,151 +245,37 @@ class SqliteTransaction implements StorageTransaction {
380
245
  }
381
246
  }
382
247
 
383
- async deleteRow(table: string, rowId: string): Promise<void> {
384
- this.#assertOpen();
385
- const db = this.#storage.db;
386
- const compiled = this.#storage.table(table);
387
- db.query(deleteSqliteRowScopesSql(compiled)).run(
388
- this.#partition,
389
- table,
390
- rowId,
391
- this.#partition,
392
- rowId,
393
- );
394
- db.query(deleteRowSql(compiled, 'sqlite')).run(this.#partition, rowId);
395
- // §5.9.4: a deleted row references no blobs.
396
- db.query(
397
- 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
398
- ).run(this.#partition, table, rowId);
399
- }
400
-
401
- async setBlobRefs(
402
- table: string,
403
- rowId: string,
404
- blobIds: readonly string[],
405
- ): Promise<void> {
406
- this.#assertOpen();
407
- const db = this.#storage.db;
408
- // Replace the row's reference set atomically (§5.9.4).
409
- db.query(
410
- 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
411
- ).run(this.#partition, table, rowId);
412
- for (const blobId of blobIds) {
413
- db.query(
414
- 'INSERT OR IGNORE INTO sync_blob_refs(partition, tbl, row_id, blob_id) VALUES (?,?,?,?)',
415
- ).run(this.#partition, table, rowId, blobId);
416
- }
417
- }
418
-
419
- async appendCommit(commit: NewCommit): Promise<number> {
420
- this.#assertOpen();
421
- const db = this.#storage.db;
422
- const p = this.#partition;
423
- db.query('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)').run(
248
+ protected async appendCommitRow(commit: NewCommit): Promise<number> {
249
+ const p = this.partition;
250
+ this.run('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)', [
424
251
  p,
252
+ ]);
253
+ const [row] = await this.all<{ max_commit_seq: number }>(
254
+ 'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
255
+ [p],
425
256
  );
426
- const row = db
427
- .query<{ max_commit_seq: number }, [string]>(
428
- 'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
429
- )
430
- .get(p);
431
257
  const commitSeq = (row?.max_commit_seq ?? 0) + 1;
432
- db.query(
433
- 'UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?',
434
- ).run(commitSeq, p);
435
- db.query(
436
- 'INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)',
437
- ).run(
438
- p,
258
+ this.run('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?', [
439
259
  commitSeq,
440
- commit.clientId,
441
- commit.clientCommitId,
442
- commit.actorId,
443
- commit.createdAtMs,
444
- this.#writerVersion,
445
- );
446
- const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
447
- commit.changes.forEach((change, idx) => {
448
- db.query(
449
- 'INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)',
450
- ).run(
260
+ p,
261
+ ]);
262
+ this.run(
263
+ 'INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)',
264
+ [
451
265
  p,
452
266
  commitSeq,
453
- idx,
454
- change.table,
455
- change.rowId,
456
- change.op === 'upsert' ? 1 : 2,
457
- change.rowVersion ?? null,
458
- JSON.stringify(change.scopes),
459
- change.payload ?? null,
460
- );
461
- if (
462
- change.op === 'delete' &&
463
- !liveAfterDelete.has(`${change.table}\u0000${change.rowId}`)
464
- ) {
465
- // §5 delete precedence: every applied delete leaves a tombstone,
466
- // pruned with the commit log (§4.6). A delete that the same commit
467
- // follows with an upsert is a §2.2 scope move, not a deletion.
468
- db.query(
469
- `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
470
- ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`,
471
- ).run(p, change.table, change.rowId, commitSeq);
472
- }
473
- for (const [variable, value] of Object.entries(change.scopes)) {
474
- db.query(
475
- 'INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)',
476
- ).run(p, change.table, variable, value, commitSeq);
477
- }
478
- });
479
- return commitSeq;
480
- }
481
-
482
- async putPushResult(
483
- clientId: string,
484
- clientCommitId: string,
485
- result: StoredPushResult,
486
- ): Promise<void> {
487
- this.#assertOpen();
488
- this.#storage.db
489
- .query(
490
- 'INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
491
- )
492
- .run(
493
- this.#partition,
494
- clientId,
495
- clientCommitId,
496
- serializePushResult(result),
497
- );
498
- }
499
-
500
- async enqueueReactions(reactions: readonly NewReaction[]): Promise<void> {
501
- this.#assertOpen();
502
- const statement = this.#storage.db.query(
503
- `INSERT INTO sync_reactions(
504
- partition, idempotency_key, type, version, payload,
505
- source_client_id, source_client_commit_id, source_commit_seq,
506
- created_at_ms, available_at_ms, status, attempts, max_attempts
507
- ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`,
267
+ commit.clientId,
268
+ commit.clientCommitId,
269
+ commit.actorId,
270
+ commit.createdAtMs,
271
+ this.#writerVersion,
272
+ ],
508
273
  );
509
- for (const reaction of reactions) {
510
- statement.run(
511
- this.#partition,
512
- reaction.idempotencyKey,
513
- reaction.type,
514
- reaction.version,
515
- JSON.stringify(reaction.payload),
516
- reaction.sourceClientId,
517
- reaction.sourceClientCommitId,
518
- reaction.sourceCommitSeq,
519
- reaction.createdAtMs,
520
- reaction.createdAtMs,
521
- reaction.maxAttempts,
522
- );
523
- }
274
+ return commitSeq;
524
275
  }
525
276
 
526
277
  async commit(): Promise<void> {
527
- this.#assertOpen();
278
+ this.assertOpen();
528
279
  try {
529
280
  this.#storage.db.exec('COMMIT');
530
281
  } catch (error) {
@@ -539,14 +290,14 @@ class SqliteTransaction implements StorageTransaction {
539
290
  }
540
291
  throw error;
541
292
  } finally {
542
- this.#open = false;
293
+ this.open = false;
543
294
  this.#release();
544
295
  }
545
296
  }
546
297
 
547
298
  async rollback(): Promise<void> {
548
- if (!this.#open) return;
549
- this.#open = false;
299
+ if (!this.open) return;
300
+ this.open = false;
550
301
  try {
551
302
  this.#storage.db.exec('ROLLBACK');
552
303
  } finally {
@@ -555,49 +306,53 @@ class SqliteTransaction implements StorageTransaction {
555
306
  }
556
307
  }
557
308
 
558
- export class SqliteServerStorage implements ServerStorage {
309
+ export class SqliteServerStorage
310
+ extends SqliteFamilyStorage
311
+ implements ServerStorage
312
+ {
559
313
  readonly db: SqliteDatabase;
560
- /** One SQLite connection can own only one transaction at a time. */
561
- #transactionTail: Promise<void> = Promise.resolve();
562
- /** Set by `ensureSchema`: app-table lookup for the relational row store. */
563
- #tables: ReadonlyMap<string, CompiledTable> | undefined;
564
- #schemaVersion: number | undefined;
314
+ protected readonly maxBindParams = Number.POSITIVE_INFINITY;
315
+ /**
316
+ * §6.4: one SQLite connection serves one caller at a time. A transaction
317
+ * holds it from `begin` until commit or rollback; every other call waits
318
+ * behind it in FIFO order, so no request reads another's uncommitted rows
319
+ * and no write joins another's open transaction. A call on an idle
320
+ * connection takes it synchronously and runs at call time.
321
+ */
322
+ #busy = false;
323
+ readonly #waiters: (() => void)[] = [];
565
324
 
566
- async #serializeWrite<T>(operation: () => T): Promise<T> {
567
- const previous = this.#transactionTail;
568
- let release!: () => void;
569
- this.#transactionTail = new Promise<void>((resolve) => {
570
- release = resolve;
571
- });
572
- await previous;
573
- try {
574
- return operation();
575
- } finally {
576
- release();
325
+ /** `undefined` when the caller owns the connection now. */
326
+ #acquire(): Promise<void> | undefined {
327
+ if (!this.#busy) {
328
+ this.#busy = true;
329
+ return undefined;
577
330
  }
331
+ return new Promise<void>((resolve) => {
332
+ this.#waiters.push(resolve);
333
+ });
334
+ }
335
+
336
+ /** Hand the connection to the next waiter, or mark it idle. */
337
+ #release(): void {
338
+ const next = this.#waiters.shift();
339
+ if (next === undefined) this.#busy = false;
340
+ else next();
578
341
  }
579
342
 
580
343
  constructor(db: SqliteDatabase | string = ':memory:') {
581
344
  if (typeof db === 'string') {
582
345
  throw new SqliteAdapterRequiredError();
583
346
  }
347
+ super();
584
348
  this.db = db;
585
349
  this.db.exec(SQLITE_DDL);
586
- const clientColumns = this.db
587
- .query<{ name: string }, []>('PRAGMA table_info("sync_clients")')
588
- .all();
589
- if (!clientColumns.some((column) => column.name === 'wire_version')) {
590
- this.db.exec(
591
- 'ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1',
592
- );
593
- }
594
- for (const [name, definition] of Object.entries(
595
- SYNC_CLIENT_ROUND_COLUMNS,
596
- )) {
597
- if (!clientColumns.some((column) => column.name === name)) {
598
- this.db.exec(
599
- `ALTER TABLE sync_clients ADD COLUMN ${name} ${definition}`,
600
- );
350
+ for (const [table, name, definition] of SQLITE_ADDED_COLUMNS) {
351
+ const columns = this.db
352
+ .query<{ name: string }, []>(`PRAGMA table_info("${table}")`)
353
+ .all();
354
+ if (!columns.some((column) => column.name === name)) {
355
+ this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
601
356
  }
602
357
  }
603
358
  const commitColumns = this.db
@@ -626,17 +381,69 @@ WHEN EXISTS (
626
381
  BEGIN
627
382
  SELECT RAISE(ABORT, 'sync.storage.writer_fence_rejected');
628
383
  END`);
384
+ // Callers receive this proxy: every method except the ones below runs
385
+ // under `#acquire`. Methods execute against the raw instance, so a
386
+ // transaction (constructed with the raw instance) and a method's own
387
+ // internal calls never queue behind themselves.
388
+ return new Proxy(this, {
389
+ get: (target, property) => {
390
+ const value: unknown = Reflect.get(target, property, target);
391
+ // An own property is a caller's override (a test double or host
392
+ // wrapper); it reaches the queue through the original it calls.
393
+ if (typeof value !== 'function' || Object.hasOwn(target, property)) {
394
+ return value;
395
+ }
396
+ if (
397
+ property === 'begin' ||
398
+ property === 'table' ||
399
+ property === 'runAuthoritativeQuery' ||
400
+ property === 'constructor'
401
+ ) {
402
+ return value.bind(target);
403
+ }
404
+ return (...args: unknown[]): Promise<unknown> => {
405
+ const run = async () => {
406
+ try {
407
+ return await Reflect.apply(value, target, args);
408
+ } finally {
409
+ target.#release();
410
+ }
411
+ };
412
+ return target.#acquire()?.then(run) ?? run();
413
+ };
414
+ },
415
+ });
629
416
  }
630
417
 
631
- /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
632
- table(name: string): CompiledTable {
633
- const table = this.#tables?.get(name);
634
- if (table === undefined) {
635
- throw new Error(
636
- `unknown table ${JSON.stringify(name)} — ensureSchema(schema) must run before row operations`,
418
+ protected async all<T>(
419
+ sql: string,
420
+ params: readonly SqliteValue[],
421
+ ): Promise<T[]> {
422
+ return this.db.query<T, SqliteValue[]>(sql).all(...params);
423
+ }
424
+
425
+ protected guardedAll<T>(
426
+ sql: string,
427
+ params: readonly SqliteValue[],
428
+ ): Promise<T[]> {
429
+ return this.all<T>(sql, params);
430
+ }
431
+
432
+ protected async atomic(
433
+ statements: readonly SqliteStatementSpec[],
434
+ ): Promise<unknown[][]> {
435
+ this.db.exec('BEGIN IMMEDIATE');
436
+ try {
437
+ const results = statements.map(({ sql, params }) =>
438
+ this.db.query<unknown, SqliteValue[]>(sql).all(...params),
637
439
  );
440
+ this.db.exec('COMMIT');
441
+ return results;
442
+ } catch (error) {
443
+ rollbackAfterError(() => {
444
+ this.db.exec('ROLLBACK');
445
+ }, error);
638
446
  }
639
- return table;
640
447
  }
641
448
 
642
449
  async ensureSchema(
@@ -644,7 +451,7 @@ END`);
644
451
  checkpoints?: readonly CheckpointDeclaration[],
645
452
  ): Promise<void> {
646
453
  // Memoized fast path: same instance, same schema version.
647
- if (this.#schemaVersion === schema.version) return;
454
+ if (this.schemaVersion === schema.version) return;
648
455
  // The barrier reads stored state: a checkpoint at this schema version that
649
456
  // is not activated and that this caller did not declare means this process
650
457
  // must not serve. An omitted or empty declaration set declares nothing and
@@ -721,17 +528,15 @@ END`);
721
528
  ),
722
529
  );
723
530
  if (reconcile.length > 0) {
724
- await this.#serializeWrite(() => {
725
- this.db.exec('BEGIN IMMEDIATE');
726
- try {
727
- for (const statement of reconcile) this.db.exec(statement);
728
- this.db.exec('COMMIT');
729
- } catch (error) {
730
- rollbackAfterError(() => {
731
- this.db.exec('ROLLBACK');
732
- }, error);
733
- }
734
- });
531
+ this.db.exec('BEGIN IMMEDIATE');
532
+ try {
533
+ for (const statement of reconcile) this.db.exec(statement);
534
+ this.db.exec('COMMIT');
535
+ } catch (error) {
536
+ rollbackAfterError(() => {
537
+ this.db.exec('ROLLBACK');
538
+ }, error);
539
+ }
735
540
  }
736
541
  }
737
542
  if (marker === null || marker.schema_version < schema.version) {
@@ -768,206 +573,95 @@ END`);
768
573
  }
769
574
  }
770
575
  // The migration rewrites application rows (`#rewriteRows`) with no
771
- // commit log entry. Serialize it through the same writer queue as
772
- // pushes and prune (`#serializeWrite`) rather than trusting the
773
- // migration as privileged; `BEGIN IMMEDIATE` then owns SQLite's writer
774
- // lock for the whole rewrite.
775
- await this.#serializeWrite(() => {
776
- this.db.exec('BEGIN IMMEDIATE');
777
- try {
778
- // Another process sharing the database may have bumped between the
779
- // marker read above and the writer lock; the locked marker decides
780
- // (SPEC "Schema upgrade writer fence").
781
- const locked = this.db
782
- .query<{ schema_version: number; layouts: string }, []>(
783
- 'SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1',
784
- )
785
- .get();
786
- if (locked !== null && locked.schema_version > schema.version) {
787
- throw new Error(
788
- `stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`,
789
- );
790
- }
791
- if (locked !== null && locked.schema_version === schema.version) {
792
- this.db.exec('COMMIT');
793
- return;
794
- }
795
- const layouts = parseLayouts(locked?.layouts);
796
- const retiredTables = retiredTableNames(schema, layouts);
797
- for (const tableName of retiredTables) {
798
- this.db
799
- .query('DELETE FROM sync_row_scopes WHERE tbl=?')
800
- .run(tableName);
801
- this.db
802
- .query('DELETE FROM sync_blob_refs WHERE tbl=?')
803
- .run(tableName);
804
- this.db.exec(dropTableDdl(tableName));
805
- }
806
- for (const statement of schemaDdl(
807
- schema,
808
- existing,
809
- 'sqlite',
810
- existingIndexes,
811
- )) {
812
- this.db.exec(statement);
813
- }
814
- for (const table of schema.tables.values()) {
815
- const oldLayout = layouts[table.name];
816
- const plan = rewritePlan(
817
- table,
818
- oldLayout,
819
- existing.get(table.name),
820
- );
821
- if (!plan.migrate && !plan.backfill) continue;
822
- this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
823
- }
576
+ // commit log entry. It runs behind the same connection queue as pushes
577
+ // and prune rather than trusting the migration as privileged;
578
+ // `BEGIN IMMEDIATE` then owns SQLite's writer lock for the whole
579
+ // rewrite.
580
+ this.db.exec('BEGIN IMMEDIATE');
581
+ try {
582
+ // Another process sharing the database may have bumped between the
583
+ // marker read above and the writer lock; the locked marker decides
584
+ // (SPEC "Schema upgrade writer fence").
585
+ const locked = this.db
586
+ .query<{ schema_version: number; layouts: string }, []>(
587
+ 'SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1',
588
+ )
589
+ .get();
590
+ if (locked !== null && locked.schema_version > schema.version) {
591
+ throw new Error(
592
+ `stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`,
593
+ );
594
+ }
595
+ if (locked !== null && locked.schema_version === schema.version) {
596
+ this.db.exec('COMMIT');
597
+ this.tables = schema.tables;
598
+ this.schemaVersion = schema.version;
599
+ return;
600
+ }
601
+ const layouts = parseLayouts(locked?.layouts);
602
+ const retiredTables = retiredTableNames(schema, layouts);
603
+ for (const tableName of retiredTables) {
824
604
  this.db
825
- .query(
826
- 'INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts',
827
- )
828
- .run(schema.version, layoutsOf(schema));
829
- // A writer of the previous schema would append payloads in the
830
- // previous layout; the bump fences every partition at the new
831
- // version (see PostgresServerStorage.ensureSchema).
605
+ .query('DELETE FROM sync_row_scopes WHERE tbl=?')
606
+ .run(tableName);
832
607
  this.db
833
- .query(
834
- `INSERT INTO sync_writer_fence(partition, required_writer_version)
835
- SELECT partition, ? FROM sync_partitions WHERE true
836
- ON CONFLICT(partition) DO UPDATE SET
837
- required_writer_version=max(
838
- sync_writer_fence.required_writer_version,
839
- excluded.required_writer_version)`,
840
- )
841
- .run(schema.version);
842
- // The host's declared checkpoints install in the schema-bump
843
- // transaction, so no observer sees the bumped marker without the
844
- // fence, or the fence without its declaration row.
845
- const installedAtMs = Date.now();
846
- for (const declaration of checkpoints ?? []) {
847
- this.#installCheckpoint(
848
- declaration.partition,
849
- declaration.name,
850
- declaration.schemaVersion,
851
- installedAtMs,
852
- );
853
- }
854
- this.db.exec('COMMIT');
855
- } catch (error) {
856
- rollbackAfterError(() => {
857
- this.db.exec('ROLLBACK');
858
- }, error);
608
+ .query('DELETE FROM sync_blob_refs WHERE tbl=?')
609
+ .run(tableName);
610
+ this.db.exec(dropTableDdl(tableName));
611
+ }
612
+ for (const statement of schemaDdl(
613
+ schema,
614
+ existing,
615
+ 'sqlite',
616
+ existingIndexes,
617
+ )) {
618
+ this.db.exec(statement);
619
+ }
620
+ for (const table of schema.tables.values()) {
621
+ const oldLayout = layouts[table.name];
622
+ const plan = rewritePlan(table, oldLayout, existing.get(table.name));
623
+ if (!plan.migrate && !plan.backfill) continue;
624
+ this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
859
625
  }
860
- });
861
- }
862
- this.#tables = schema.tables;
863
- this.#schemaVersion = schema.version;
864
- }
865
-
866
- async touchPartition(
867
- partition: string,
868
- authenticatedAtMs: number,
869
- initialLogEpoch: string,
870
- ): Promise<PartitionRegistryEntry> {
871
- if (initialLogEpoch.length === 0) {
872
- throw new Error('initial log epoch must be non-empty');
873
- }
874
- const select = this.db.query<
875
- {
876
- log_epoch: string;
877
- epoch_required: number;
878
- last_authenticated_at_ms: number;
879
- },
880
- [string]
881
- >(
882
- `SELECT log_epoch, epoch_required, last_authenticated_at_ms
883
- FROM sync_partition_registry WHERE partition=?`,
884
- );
885
- let row = select.get(partition);
886
- if (
887
- row === null ||
888
- authenticatedAtMs - row.last_authenticated_at_ms >=
889
- PARTITION_TOUCH_INTERVAL_MS
890
- ) {
891
- this.db
892
- .query(
893
- `INSERT INTO sync_partition_registry(
894
- partition, log_epoch, last_authenticated_at_ms
895
- ) VALUES (?,?,?)
896
- ON CONFLICT(partition) DO UPDATE SET
897
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`,
898
- )
899
- .run(partition, initialLogEpoch, authenticatedAtMs);
900
- row = select.get(partition);
901
- }
902
- if (row === null)
903
- throw new Error('partition registry write did not persist');
904
- return {
905
- partition,
906
- logEpoch: row.log_epoch,
907
- epochRequired: row.epoch_required === 1,
908
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
909
- };
910
- }
911
-
912
- async rotatePartitionLogEpoch(
913
- partition: string,
914
- logEpoch: string,
915
- authenticatedAtMs: number,
916
- ): Promise<PartitionRegistryEntry> {
917
- if (logEpoch.length === 0) throw new Error('log epoch must be non-empty');
918
- return this.#serializeWrite(() => {
919
- this.db.exec('BEGIN IMMEDIATE');
920
- try {
921
626
  this.db
922
627
  .query(
923
- `INSERT INTO sync_partition_registry(
924
- partition, log_epoch, epoch_required, last_authenticated_at_ms
925
- ) VALUES (?,?,1,?)
926
- ON CONFLICT(partition) DO UPDATE SET
927
- log_epoch=excluded.log_epoch,
928
- epoch_required=1,
929
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`,
628
+ 'INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts',
930
629
  )
931
- .run(partition, logEpoch, authenticatedAtMs);
630
+ .run(schema.version, layoutsOf(schema));
631
+ // A writer of the previous schema would append payloads in the
632
+ // previous layout; the bump fences every partition at the new
633
+ // version (see PostgresServerStorage.ensureSchema).
932
634
  this.db
933
- .query('DELETE FROM sync_clients WHERE partition=?')
934
- .run(partition);
635
+ .query(
636
+ `INSERT INTO sync_writer_fence(partition, required_writer_version)
637
+ SELECT partition, ? FROM sync_partitions WHERE true
638
+ ON CONFLICT(partition) DO UPDATE SET
639
+ required_writer_version=max(
640
+ sync_writer_fence.required_writer_version,
641
+ excluded.required_writer_version)`,
642
+ )
643
+ .run(schema.version);
644
+ // The host's declared checkpoints install in the schema-bump
645
+ // transaction, so no observer sees the bumped marker without the
646
+ // fence, or the fence without its declaration row.
647
+ const installedAtMs = Date.now();
648
+ for (const declaration of checkpoints ?? []) {
649
+ this.#installCheckpoint(
650
+ declaration.partition,
651
+ declaration.name,
652
+ declaration.schemaVersion,
653
+ installedAtMs,
654
+ );
655
+ }
935
656
  this.db.exec('COMMIT');
936
657
  } catch (error) {
937
658
  rollbackAfterError(() => {
938
659
  this.db.exec('ROLLBACK');
939
660
  }, error);
940
661
  }
941
- return {
942
- partition,
943
- logEpoch,
944
- epochRequired: true,
945
- lastAuthenticatedAtMs: authenticatedAtMs,
946
- };
947
- });
948
- }
949
-
950
- async listPartitionRegistry(): Promise<PartitionRegistryEntry[]> {
951
- return this.db
952
- .query<
953
- {
954
- partition: string;
955
- log_epoch: string;
956
- epoch_required: number;
957
- last_authenticated_at_ms: number;
958
- },
959
- []
960
- >(
961
- `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
962
- FROM sync_partition_registry ORDER BY partition`,
963
- )
964
- .all()
965
- .map((row) => ({
966
- partition: row.partition,
967
- logEpoch: row.log_epoch,
968
- epochRequired: row.epoch_required === 1,
969
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
970
- }));
662
+ }
663
+ this.tables = schema.tables;
664
+ this.schemaVersion = schema.version;
971
665
  }
972
666
 
973
667
  /**
@@ -999,13 +693,7 @@ END`);
999
693
  ? migratePayload(oldLayout, table, row.payload)
1000
694
  : row.payload;
1001
695
  update.run(
1002
- ...(rewriteValues(
1003
- table,
1004
- row.partition,
1005
- row.row_id,
1006
- payload,
1007
- 'sqlite',
1008
- ) as (string | number | boolean | Uint8Array | null)[]),
696
+ ...rewriteValues(table, row.partition, row.row_id, payload, 'sqlite'),
1009
697
  );
1010
698
  }
1011
699
  const last = rows[rows.length - 1];
@@ -1020,60 +708,20 @@ END`);
1020
708
  // database file, so one FIFO over the shared connection is the correct
1021
709
  // serialization unit — a per-partition queue would still contend on the
1022
710
  // same BEGIN IMMEDIATE writer lock.
1023
- const previous = this.#transactionTail;
1024
- let release!: () => void;
1025
- this.#transactionTail = new Promise<void>((resolve) => {
1026
- release = resolve;
1027
- });
1028
- await previous;
711
+ await this.#acquire();
1029
712
  try {
1030
713
  return new SqliteTransaction(
1031
714
  this,
1032
715
  partition,
1033
- this.#schemaVersion ?? 0,
1034
- release,
716
+ this.schemaVersion ?? 0,
717
+ () => this.#release(),
1035
718
  );
1036
719
  } catch (error) {
1037
- release();
720
+ this.#release();
1038
721
  throw error;
1039
722
  }
1040
723
  }
1041
724
 
1042
- /** Internal: write a row + refresh its scope-index entries. */
1043
- writeRow(partition: string, table: string, row: StoredRow): void {
1044
- const compiled = this.table(table);
1045
- this.db
1046
- .query(deleteSqliteRowScopesSql(compiled))
1047
- .run(partition, table, row.rowId, partition, row.rowId);
1048
- this.db
1049
- .query(upsertSql(compiled, 'sqlite'))
1050
- .run(
1051
- ...(upsertValues(compiled, partition, row, 'sqlite') as (
1052
- | string
1053
- | number
1054
- | boolean
1055
- | Uint8Array
1056
- | null
1057
- )[]),
1058
- );
1059
- for (const [variable, value] of Object.entries(row.scopes)) {
1060
- this.db
1061
- .query(
1062
- 'INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)',
1063
- )
1064
- .run(partition, table, variable, value, row.rowId);
1065
- }
1066
- }
1067
-
1068
- async getMaxCommitSeq(partition: string): Promise<number> {
1069
- const row = this.db
1070
- .query<{ max_commit_seq: number }, [string]>(
1071
- 'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
1072
- )
1073
- .get(partition);
1074
- return row?.max_commit_seq ?? 0;
1075
- }
1076
-
1077
725
  /**
1078
726
  * Internal: rewrite and run one registered query on the shared connection.
1079
727
  * The caller owns the transaction: `queryAuthoritative` opens a read
@@ -1084,20 +732,7 @@ END`);
1084
732
  partition: string,
1085
733
  query: AuthoritativeQueryRequest,
1086
734
  ): AuthoritativeQueryResult {
1087
- if (this.#tables === undefined) {
1088
- throw new Error(
1089
- 'ensureSchema(schema) must run before registered queries',
1090
- );
1091
- }
1092
- const prepared = bindAuthoritativePartition(
1093
- prepareAuthoritativeQuery(
1094
- query.plan,
1095
- query.params,
1096
- query.tables,
1097
- this.#tables,
1098
- ),
1099
- partition,
1100
- );
735
+ const prepared = this.prepareAuthoritativeQuery(partition, query);
1101
736
  const rows = this.db
1102
737
  .query<Readonly<Record<string, unknown>>, AuthoritativeQueryValue[]>(
1103
738
  prepared.sql,
@@ -1116,12 +751,6 @@ END`);
1116
751
  query: AuthoritativeQueryRequest,
1117
752
  checkpoints?: readonly CheckpointDeclaration[],
1118
753
  ): Promise<AuthoritativeQueryResult> {
1119
- const previous = this.#transactionTail;
1120
- let release!: () => void;
1121
- this.#transactionTail = new Promise<void>((resolve) => {
1122
- release = resolve;
1123
- });
1124
- await previous;
1125
754
  let open = false;
1126
755
  try {
1127
756
  this.db.exec('BEGIN');
@@ -1129,7 +758,7 @@ END`);
1129
758
  // RFC 0007: evaluate the gate on this connection after BEGIN. SQLite is
1130
759
  // single-writer and the shared connection serializes writers, so the
1131
760
  // gate read and the query read cannot straddle a migration.
1132
- const runningVersion = this.#schemaVersion ?? 0;
761
+ const runningVersion = this.schemaVersion ?? 0;
1133
762
  const gate = await this.readServeGate(partition, runningVersion);
1134
763
  const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
1135
764
  if (refusal !== undefined) throw serveNotReadyError(refusal);
@@ -1141,133 +770,26 @@ END`);
1141
770
  rollbackAfterError(() => {
1142
771
  if (open) this.db.exec('ROLLBACK');
1143
772
  }, error);
1144
- } finally {
1145
- release();
1146
773
  }
1147
774
  }
1148
775
 
1149
- async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
1150
- return this.db
1151
- .query<{ log_epoch: string }, [string]>(
1152
- 'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
1153
- )
1154
- .get(partition)?.log_epoch;
1155
- }
1156
-
1157
- async getHorizonSeq(partition: string): Promise<number> {
1158
- const row = this.db
1159
- .query<{ horizon_seq: number }, [string]>(
1160
- 'SELECT horizon_seq FROM sync_partitions WHERE partition=?',
1161
- )
1162
- .get(partition);
1163
- return row?.horizon_seq ?? 0;
1164
- }
1165
-
1166
- async setHorizonSeq(partition: string, seq: number): Promise<void> {
1167
- await this.#serializeWrite(() => {
1168
- this.db
1169
- .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
1170
- ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
1171
- .run(partition, seq);
1172
- });
1173
- }
1174
-
1175
- async pruneCommitsThrough(
1176
- partition: string,
1177
- query: CommitPruneQuery,
1178
- ): Promise<CommitPruneResult> {
1179
- validateCommitPruneQuery(query);
1180
- return this.#serializeWrite(() => {
1181
- this.db.exec('BEGIN IMMEDIATE');
1182
- try {
1183
- const epoch = this.db
1184
- .query<{ log_epoch: string }, [string]>(
1185
- 'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
1186
- )
1187
- .get(partition)?.log_epoch;
1188
- if (epoch !== query.logEpoch)
1189
- throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
1190
- const previousHorizonSeq =
1191
- this.db
1192
- .query<{ horizon_seq: number }, [string]>(
1193
- 'SELECT horizon_seq FROM sync_partitions WHERE partition=?',
1194
- )
1195
- .get(partition)?.horizon_seq ?? 0;
1196
- const horizonSeq = Math.max(previousHorizonSeq, query.throughSeq);
1197
- this.db
1198
- .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
1199
- ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq`)
1200
- .run(partition, horizonSeq);
1201
- const removed = this.db
1202
- .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
1203
- .run(partition, horizonSeq);
1204
- this.db
1205
- .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
1206
- .run(partition, horizonSeq);
1207
- this.db
1208
- .query(
1209
- 'DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?',
1210
- )
1211
- .run(partition, horizonSeq);
1212
- // §4.6: tombstones prune in the same pass as the commit log.
1213
- this.db
1214
- .query(
1215
- 'DELETE FROM sync_tombstones WHERE partition=? AND commit_seq<=?',
1216
- )
1217
- .run(partition, horizonSeq);
1218
- this.db.exec('COMMIT');
1219
- return {
1220
- previousHorizonSeq,
1221
- horizonSeq,
1222
- removedCommits: Number(removed.changes),
1223
- };
1224
- } catch (error) {
1225
- rollbackAfterError(() => {
1226
- this.db.exec('ROLLBACK');
1227
- }, error);
1228
- }
1229
- });
1230
- }
1231
-
1232
- async getCommitSeqBefore(
1233
- partition: string,
1234
- createdBeforeMs: number,
1235
- ): Promise<number> {
1236
- const row = this.db
1237
- .query<{ seq: number | null }, [string, number]>(
1238
- 'SELECT max(commit_seq) AS seq FROM sync_commits WHERE partition=? AND created_at_ms<?',
1239
- )
1240
- .get(partition, createdBeforeMs);
1241
- return row?.seq ?? 0;
1242
- }
1243
-
1244
776
  async readServeGate(
1245
777
  partition: string,
1246
778
  runningSchemaVersion: number,
1247
779
  ): Promise<ServeGate> {
1248
- const marker = this.db
1249
- .query<{ schema_version: number }, []>(
1250
- 'SELECT schema_version FROM sync_schema_meta WHERE id=1',
1251
- )
1252
- .get();
1253
- const epoch = this.db
1254
- .query<{ log_epoch: string }, [string]>(
1255
- 'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
1256
- )
1257
- .get(partition);
1258
- const pending = this.db
1259
- .query<{ partition: string; name: string }, [number]>(
1260
- `SELECT partition, name FROM sync_backfill_checkpoints
1261
- WHERE schema_version=? AND state<>'activated'`,
1262
- )
1263
- .all(runningSchemaVersion);
780
+ const [marker] = await this.all<{ schema_version: number }>(
781
+ 'SELECT schema_version FROM sync_schema_meta WHERE id=1',
782
+ [],
783
+ );
784
+ const pending = await this.all<{ partition: string; name: string }>(
785
+ `SELECT partition, name FROM sync_backfill_checkpoints
786
+ WHERE schema_version=? AND state<>'activated'`,
787
+ [runningSchemaVersion],
788
+ );
1264
789
  return {
1265
790
  storedSchemaVersion: marker?.schema_version ?? 0,
1266
- logEpoch: epoch?.log_epoch,
1267
- pending: pending.map((row) => ({
1268
- partition: row.partition,
1269
- name: row.name,
1270
- })),
791
+ logEpoch: await this.getPartitionLogEpoch(partition),
792
+ pending,
1271
793
  };
1272
794
  }
1273
795
 
@@ -1324,27 +846,25 @@ END`);
1324
846
  // One transaction: the checkpoint becomes visible and the fence that
1325
847
  // protects it is raised together. The fence is raised at declaration, not
1326
848
  // at activation, so old writers are rejected for the whole backfill.
1327
- return this.#serializeWrite(() => {
1328
- this.db.exec('BEGIN IMMEDIATE');
1329
- try {
1330
- this.#installCheckpoint(partition, name, schemaVersion, nowMs);
1331
- const row = this.db
1332
- .query<SqliteCheckpointRecord, [string, string]>(
1333
- `SELECT partition, name, schema_version, state, watermark,
1334
- owner_epoch, observed_rows, updated_at_ms
1335
- FROM sync_backfill_checkpoints WHERE partition=? AND name=?`,
1336
- )
1337
- .get(partition, name);
1338
- if (row === null)
1339
- throw new StorageQueryError('sync.storage.checkpoint_not_declared');
1340
- this.db.exec('COMMIT');
1341
- return toStoredCheckpoint(row);
1342
- } catch (error) {
1343
- rollbackAfterError(() => {
1344
- this.db.exec('ROLLBACK');
1345
- }, error);
1346
- }
1347
- });
849
+ this.db.exec('BEGIN IMMEDIATE');
850
+ try {
851
+ this.#installCheckpoint(partition, name, schemaVersion, nowMs);
852
+ const row = this.db
853
+ .query<SqliteCheckpointRecord, [string, string]>(
854
+ `SELECT partition, name, schema_version, state, watermark,
855
+ owner_epoch, observed_rows, updated_at_ms
856
+ FROM sync_backfill_checkpoints WHERE partition=? AND name=?`,
857
+ )
858
+ .get(partition, name);
859
+ if (row === null)
860
+ throw new StorageQueryError('sync.storage.checkpoint_not_declared');
861
+ this.db.exec('COMMIT');
862
+ return toStoredCheckpoint(row);
863
+ } catch (error) {
864
+ rollbackAfterError(() => {
865
+ this.db.exec('ROLLBACK');
866
+ }, error);
867
+ }
1348
868
  }
1349
869
 
1350
870
  async activateCheckpoint(
@@ -1355,55 +875,53 @@ END`);
1355
875
  sources: readonly string[],
1356
876
  nowMs: number,
1357
877
  ): Promise<'activated' | 'stale' | 'unverifiable'> {
1358
- return this.#serializeWrite(() => {
1359
- // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
1360
- // lock a push takes. Nothing may observe activation without the fence.
1361
- this.db.exec('BEGIN IMMEDIATE');
1362
- try {
1363
- const fence = this.db
1364
- .query<{ required_writer_version: number }, [string]>(
1365
- 'SELECT required_writer_version FROM sync_writer_fence WHERE partition=?',
1366
- )
1367
- .get(partition);
1368
- const checkpoint = this.db
1369
- .query<{ schema_version: number }, [string, string]>(
1370
- 'SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?',
1371
- )
1372
- .get(partition, name);
1373
- if (
1374
- fence === null ||
1375
- checkpoint === null ||
1376
- fence.required_writer_version < checkpoint.schema_version
1377
- ) {
1378
- // The barrier is not installed. Activating would certify a state old
1379
- // writers can still decay; refuse instead of silently proceeding.
1380
- throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
1381
- }
1382
- const coverage = this.#hasSourceChangesAbove(
1383
- partition,
1384
- sources,
1385
- watermark,
1386
- );
1387
- if (coverage !== 'clean') {
1388
- this.db.exec('ROLLBACK');
1389
- return coverage === 'changed' ? 'stale' : 'unverifiable';
1390
- }
1391
- const updated = this.db
1392
- .query(
1393
- `UPDATE sync_backfill_checkpoints
1394
- SET state='activated', watermark=?, updated_at_ms=?
1395
- WHERE partition=? AND name=? AND owner_epoch=?
1396
- AND state<>'activated'`,
1397
- )
1398
- .run(watermark, nowMs, partition, name, ownerEpoch);
1399
- this.db.exec('COMMIT');
1400
- return Number(updated.changes) === 1 ? 'activated' : 'stale';
1401
- } catch (error) {
1402
- rollbackAfterError(() => {
1403
- this.db.exec('ROLLBACK');
1404
- }, error);
878
+ // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
879
+ // lock a push takes. Nothing may observe activation without the fence.
880
+ this.db.exec('BEGIN IMMEDIATE');
881
+ try {
882
+ const fence = this.db
883
+ .query<{ required_writer_version: number }, [string]>(
884
+ 'SELECT required_writer_version FROM sync_writer_fence WHERE partition=?',
885
+ )
886
+ .get(partition);
887
+ const checkpoint = this.db
888
+ .query<{ schema_version: number }, [string, string]>(
889
+ 'SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?',
890
+ )
891
+ .get(partition, name);
892
+ if (
893
+ fence === null ||
894
+ checkpoint === null ||
895
+ fence.required_writer_version < checkpoint.schema_version
896
+ ) {
897
+ // The barrier is not installed. Activating would certify a state old
898
+ // writers can still decay; refuse instead of silently proceeding.
899
+ throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
1405
900
  }
1406
- });
901
+ const coverage = await this.hasSourceChangesAbove(
902
+ partition,
903
+ sources,
904
+ watermark,
905
+ );
906
+ if (coverage !== 'clean') {
907
+ this.db.exec('ROLLBACK');
908
+ return coverage === 'changed' ? 'stale' : 'unverifiable';
909
+ }
910
+ const updated = this.db
911
+ .query(
912
+ `UPDATE sync_backfill_checkpoints
913
+ SET state='activated', watermark=?, updated_at_ms=?
914
+ WHERE partition=? AND name=? AND owner_epoch=?
915
+ AND state<>'activated'`,
916
+ )
917
+ .run(watermark, nowMs, partition, name, ownerEpoch);
918
+ this.db.exec('COMMIT');
919
+ return Number(updated.changes) === 1 ? 'activated' : 'stale';
920
+ } catch (error) {
921
+ rollbackAfterError(() => {
922
+ this.db.exec('ROLLBACK');
923
+ }, error);
924
+ }
1407
925
  }
1408
926
 
1409
927
  async claimCheckpoint(
@@ -1412,23 +930,21 @@ END`);
1412
930
  schemaVersion: number,
1413
931
  nowMs: number,
1414
932
  ): Promise<StoredCheckpoint> {
1415
- return this.#serializeWrite(() => {
1416
- const claimed = this.db
1417
- .query<SqliteCheckpointRecord, (string | number)[]>(
1418
- `UPDATE sync_backfill_checkpoints
1419
- SET owner_epoch=owner_epoch+1,
1420
- state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
1421
- schema_version=?, updated_at_ms=?
1422
- WHERE partition=? AND name=? AND state<>'activated'
1423
- RETURNING partition, name, schema_version, state, watermark,
1424
- owner_epoch, observed_rows, updated_at_ms`,
1425
- )
1426
- .get(schemaVersion, nowMs, partition, name);
1427
- if (claimed === null) {
1428
- throw new StorageQueryError('sync.storage.checkpoint_not_declared');
1429
- }
1430
- return toStoredCheckpoint(claimed);
1431
- });
933
+ const claimed = this.db
934
+ .query<SqliteCheckpointRecord, (string | number)[]>(
935
+ `UPDATE sync_backfill_checkpoints
936
+ SET owner_epoch=owner_epoch+1,
937
+ state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
938
+ schema_version=?, updated_at_ms=?
939
+ WHERE partition=? AND name=? AND state<>'activated'
940
+ RETURNING partition, name, schema_version, state, watermark,
941
+ owner_epoch, observed_rows, updated_at_ms`,
942
+ )
943
+ .get(schemaVersion, nowMs, partition, name);
944
+ if (claimed === null) {
945
+ throw new StorageQueryError('sync.storage.checkpoint_not_declared');
946
+ }
947
+ return toStoredCheckpoint(claimed);
1432
948
  }
1433
949
 
1434
950
  async advanceCheckpoint(
@@ -1439,980 +955,13 @@ END`);
1439
955
  observedRows: number,
1440
956
  nowMs: number,
1441
957
  ): Promise<boolean> {
1442
- return this.#serializeWrite(() => {
1443
- const result = this.db
1444
- .query(
1445
- `UPDATE sync_backfill_checkpoints
1446
- SET watermark=?, observed_rows=?, updated_at_ms=?
1447
- WHERE partition=? AND name=? AND owner_epoch=?`,
1448
- )
1449
- .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
1450
- return Number(result.changes) === 1;
1451
- });
1452
- }
1453
-
1454
- async sourceCoverageSeq(
1455
- partition: string,
1456
- tables: readonly string[],
1457
- ): Promise<number> {
1458
- if (tables.length === 0) return 0;
1459
- const row = this.db
1460
- .query<{ seq: number | null }, (string | number)[]>(
1461
- `SELECT max(commit_seq) AS seq FROM sync_changes
1462
- WHERE partition=? AND tbl IN (${placeholders(tables.length)})`,
1463
- )
1464
- .get(partition, ...tables);
1465
- return row?.seq ?? 0;
1466
- }
1467
-
1468
- #hasSourceChangesAbove(
1469
- partition: string,
1470
- tables: readonly string[],
1471
- seq: number,
1472
- ): 'clean' | 'changed' | 'unverifiable' {
1473
- // Read the horizon before the window scan: a horizon past `seq` means the
1474
- // history that would answer the question is gone, so an empty scan proves
1475
- // nothing and must not be reported as `clean`.
1476
- const horizon =
1477
- this.db
1478
- .query<{ horizon_seq: number }, [string]>(
1479
- 'SELECT horizon_seq FROM sync_partitions WHERE partition=?',
1480
- )
1481
- .get(partition)?.horizon_seq ?? 0;
1482
- if (tables.length === 0) return 'clean';
1483
- const hit = this.db
1484
- .query<{ hit: number }, (string | number)[]>(
1485
- `SELECT 1 AS hit FROM sync_changes
1486
- WHERE partition=? AND tbl IN (${placeholders(tables.length)})
1487
- AND commit_seq>? LIMIT 1`,
1488
- )
1489
- .get(partition, ...tables, seq);
1490
- if (hit !== null && hit !== undefined) return 'changed';
1491
- return horizon > seq ? 'unverifiable' : 'clean';
1492
- }
1493
-
1494
- async hasSourceChangesAbove(
1495
- partition: string,
1496
- tables: readonly string[],
1497
- seq: number,
1498
- ): Promise<'clean' | 'changed' | 'unverifiable'> {
1499
- return this.#hasSourceChangesAbove(partition, tables, seq);
1500
- }
1501
-
1502
- async getRow(
1503
- partition: string,
1504
- table: string,
1505
- rowId: string,
1506
- ): Promise<StoredRow | undefined> {
1507
- const record = this.db
1508
- .query<SqliteRowRecord, [string, string]>(
1509
- selectRowSql(this.table(table), 'sqlite'),
1510
- )
1511
- .get(partition, rowId);
1512
- return record === null ? undefined : toStoredRow(record);
1513
- }
1514
-
1515
- async getPushResult(
1516
- partition: string,
1517
- clientId: string,
1518
- clientCommitId: string,
1519
- ): Promise<StoredPushResult | undefined> {
1520
- const record = this.db
1521
- .query<{ result: string }, [string, string, string]>(
1522
- 'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
1523
- )
1524
- .get(partition, clientId, clientCommitId);
1525
- if (record === null) return undefined;
1526
- try {
1527
- return deserializePushResult(record.result);
1528
- } catch {
1529
- throw syncError(
1530
- 'sync.idempotency_cache_miss',
1531
- 'persisted push result unreadable (§6.3)',
1532
- );
1533
- }
1534
- }
1535
-
1536
- async claimReactions(
1537
- partition: string,
1538
- query: ReactionClaimQuery,
1539
- ): Promise<StoredReaction[]> {
1540
- if (query.types.length === 0 || query.limit <= 0) return [];
1541
- return this.#serializeWrite(() => {
1542
- const typeParams = query.types.map(() => '?').join(',');
1543
- const records = this.db
1544
- .query<SqliteReactionRecord, (string | number)[]>(
1545
- `UPDATE sync_reactions
1546
- SET status='leased', attempts=attempts+1,
1547
- lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
1548
- WHERE (partition, idempotency_key) IN (
1549
- SELECT partition, idempotency_key
1550
- FROM sync_reactions
1551
- WHERE partition=? AND type IN (${typeParams})
1552
- AND ((status='pending' AND available_at_ms<=?)
1553
- OR (status='leased' AND lease_expires_at_ms<=?))
1554
- ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
1555
- ELSE available_at_ms END,
1556
- created_at_ms, idempotency_key
1557
- LIMIT ?
1558
- )
1559
- RETURNING *`,
1560
- )
1561
- .all(
1562
- query.leaseOwner,
1563
- Math.min(
1564
- Number.MAX_SAFE_INTEGER,
1565
- query.nowMs + query.leaseDurationMs,
1566
- ),
1567
- partition,
1568
- ...query.types,
1569
- query.nowMs,
1570
- query.nowMs,
1571
- query.limit,
1572
- );
1573
- return records
1574
- .map(toStoredReaction)
1575
- .sort(
1576
- (a, b) =>
1577
- a.createdAtMs - b.createdAtMs ||
1578
- a.idempotencyKey.localeCompare(b.idempotencyKey),
1579
- );
1580
- });
1581
- }
1582
-
1583
- async completeReaction(
1584
- partition: string,
1585
- idempotencyKey: string,
1586
- leaseOwner: string,
1587
- completedAtMs: number,
1588
- ): Promise<boolean> {
1589
- return this.#serializeWrite(() => {
1590
- const result = this.db
1591
- .query(
1592
- `UPDATE sync_reactions
1593
- SET status='completed', completed_at_ms=?,
1594
- lease_owner=NULL, lease_expires_at_ms=NULL
1595
- WHERE partition=? AND idempotency_key=?
1596
- AND status='leased' AND lease_owner=?`,
1597
- )
1598
- .run(completedAtMs, partition, idempotencyKey, leaseOwner);
1599
- return Number(result.changes) === 1;
1600
- });
1601
- }
1602
-
1603
- async extendReactionLease(
1604
- partition: string,
1605
- idempotencyKey: string,
1606
- leaseOwner: string,
1607
- leaseExpiresAtMs: number,
1608
- ): Promise<boolean> {
1609
- return this.#serializeWrite(() => {
1610
- const result = this.db
1611
- .query(
1612
- `UPDATE sync_reactions SET lease_expires_at_ms=?
1613
- WHERE partition=? AND idempotency_key=?
1614
- AND status='leased' AND lease_owner=?`,
1615
- )
1616
- .run(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner);
1617
- return Number(result.changes) === 1;
1618
- });
1619
- }
1620
-
1621
- async failReaction(
1622
- partition: string,
1623
- idempotencyKey: string,
1624
- update: ReactionFailureUpdate,
1625
- ): Promise<boolean> {
1626
- const retry = update.retryAtMs !== undefined;
1627
- return this.#serializeWrite(() => {
1628
- const result = this.db
1629
- .query(
1630
- `UPDATE sync_reactions
1631
- SET status=?, available_at_ms=?, last_failure=?,
1632
- lease_owner=NULL, lease_expires_at_ms=NULL
1633
- WHERE partition=? AND idempotency_key=?
1634
- AND status='leased' AND lease_owner=?`,
1635
- )
1636
- .run(
1637
- retry ? 'pending' : 'dead-letter',
1638
- update.retryAtMs ?? update.failure.atMs,
1639
- JSON.stringify(update.failure),
1640
- partition,
1641
- idempotencyKey,
1642
- update.leaseOwner,
1643
- );
1644
- return Number(result.changes) === 1;
1645
- });
1646
- }
1647
-
1648
- async retryReaction(
1649
- partition: string,
1650
- idempotencyKey: string,
1651
- nowMs: number,
1652
- ): Promise<boolean> {
1653
- return this.#serializeWrite(() => {
1654
- const result = this.db
1655
- .query(
1656
- `UPDATE sync_reactions
1657
- SET status='pending', attempts=0, available_at_ms=?,
1658
- last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
1659
- completed_at_ms=NULL
1660
- WHERE partition=? AND idempotency_key=? AND status='dead-letter'`,
1661
- )
1662
- .run(nowMs, partition, idempotencyKey);
1663
- return Number(result.changes) === 1;
1664
- });
1665
- }
1666
-
1667
- async getReaction(
1668
- partition: string,
1669
- idempotencyKey: string,
1670
- ): Promise<StoredReaction | undefined> {
1671
- const record = this.db
1672
- .query<SqliteReactionRecord, [string, string]>(
1673
- 'SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?',
1674
- )
1675
- .get(partition, idempotencyKey);
1676
- return record === null ? undefined : toStoredReaction(record);
1677
- }
1678
-
1679
- async listReactions(
1680
- partition: string,
1681
- query: ReactionListQuery,
1682
- ): Promise<StoredReaction[]> {
1683
- const where = ['partition=?'];
1684
- const params: (string | number)[] = [partition];
1685
- if (query.statuses !== undefined && query.statuses.length > 0) {
1686
- where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
1687
- params.push(...query.statuses);
1688
- }
1689
- if (query.types !== undefined && query.types.length > 0) {
1690
- where.push(`type IN (${query.types.map(() => '?').join(',')})`);
1691
- params.push(...query.types);
1692
- }
1693
- params.push(query.limit);
1694
- const records = this.db
1695
- .query<SqliteReactionRecord, (string | number)[]>(
1696
- `SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
1697
- ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`,
1698
- )
1699
- .all(...params);
1700
- return records.map(toStoredReaction);
1701
- }
1702
-
1703
- async pruneReactions(
1704
- partition: string,
1705
- query: ReactionPruneQuery,
1706
- ): Promise<PrunedReactionCounts> {
1707
- if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
1708
- return this.#serializeWrite(() => {
1709
- const records = this.db
1710
- .query<
1711
- { status: 'completed' | 'dead-letter' },
1712
- [string, string, number, number, number, number, number]
1713
- >(
1714
- `DELETE FROM sync_reactions
1715
- WHERE partition=? AND idempotency_key IN (
1716
- SELECT idempotency_key FROM sync_reactions
1717
- WHERE partition=?
1718
- AND ((status='completed' AND completed_at_ms IS NOT NULL
1719
- AND completed_at_ms<?)
1720
- OR (status='dead-letter' AND available_at_ms<?))
1721
- ORDER BY CASE WHEN status='completed' THEN completed_at_ms
1722
- ELSE available_at_ms END,
1723
- idempotency_key
1724
- LIMIT ?
1725
- )
1726
- AND ((status='completed' AND completed_at_ms IS NOT NULL
1727
- AND completed_at_ms<?)
1728
- OR (status='dead-letter' AND available_at_ms<?))
1729
- RETURNING status`,
1730
- )
1731
- .all(
1732
- partition,
1733
- partition,
1734
- query.completedBeforeMs,
1735
- query.deadLetterBeforeMs,
1736
- query.limit,
1737
- query.completedBeforeMs,
1738
- query.deadLetterBeforeMs,
1739
- );
1740
- return {
1741
- completed: records.filter((record) => record.status === 'completed')
1742
- .length,
1743
- deadLetter: records.filter((record) => record.status === 'dead-letter')
1744
- .length,
1745
- };
1746
- });
1747
- }
1748
-
1749
- async latestScopedChangeSeq(
1750
- partition: string,
1751
- query: { readonly table: string; readonly scopeFilter: ScopeMap },
1752
- ): Promise<number> {
1753
- const firstVariable = Object.keys(query.scopeFilter).sort()[0];
1754
- const values =
1755
- firstVariable === undefined
1756
- ? []
1757
- : (query.scopeFilter[firstVariable] ?? []);
1758
- if (firstVariable === undefined || values.length === 0) return 0;
1759
- const row = this.db
1760
- .query<{ seq: number | null }, string[]>(
1761
- LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
1762
- )
1763
- .get(partition, query.table, firstVariable, JSON.stringify(values));
1764
- return row?.seq ?? 0;
1765
- }
1766
-
1767
- async readCommitWindow(
1768
- partition: string,
1769
- query: CommitWindowQuery,
1770
- ): Promise<StoredCommit[]> {
1771
- const variables = Object.keys(query.scopeFilter).sort();
1772
- const firstVariable = variables[0];
1773
- if (firstVariable === undefined) return [];
1774
- const firstValues = query.scopeFilter[firstVariable] ?? [];
1775
- if (firstValues.length === 0) return [];
1776
- // Candidates via the inverted index (one variable) LEFT JOINed to the
1777
- // commit meta + the table's changes — one statement per page, never two
1778
- // per candidate (see `commitWindowPageSql`). Exact multi-variable
1779
- // verification against the stored scope map in `collectCommitWindowPage`.
1780
- const sql = commitWindowPageSql(firstValues.length, 'sqlite');
1781
- const commits: StoredCommit[] = [];
1782
- let deliveredChanges = 0;
1783
- let afterSeq = query.afterSeq;
1784
- const batchSize = Math.max(64, query.limitChanges);
1785
- while (deliveredChanges < query.limitChanges) {
1786
- const records = this.db
1787
- .query<SqliteCommitWindowRecord, (string | number)[]>(sql)
1788
- .all(
1789
- partition,
1790
- query.table,
1791
- firstVariable,
1792
- ...firstValues,
1793
- afterSeq,
1794
- query.throughSeq,
1795
- batchSize,
1796
- partition,
1797
- partition,
1798
- query.table,
1799
- );
1800
- if (records.length === 0) break;
1801
- const page = collectCommitWindowPage(
1802
- records,
1803
- query.scopeFilter,
1804
- query.limitChanges - deliveredChanges,
1805
- );
1806
- commits.push(...page.commits);
1807
- deliveredChanges += page.delivered;
1808
- afterSeq = page.lastSeq;
1809
- if (page.candidateCount < batchSize) break;
1810
- }
1811
- return commits;
1812
- }
1813
-
1814
- async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
1815
- const firstVariable = assertScopeIndexedScan(query);
1816
- const firstValues = query.scopeFilter[firstVariable] ?? [];
1817
- if (firstValues.length === 0) return [];
1818
- // Candidates via the inverted index LEFT JOINed to the row table — one
1819
- // statement per page, never one per row (see `scanRowPageSql`). Exact
1820
- // multi-variable verification against the stored scope map below.
1821
- const sql = scanRowPageSql(
1822
- this.table(query.table),
1823
- firstValues.length,
1824
- 'sqlite',
1825
- );
1826
- const rows: StoredRow[] = [];
1827
- let afterRowId = query.afterRowId ?? '';
1828
- const batchSize = Math.max(64, query.limit);
1829
- while (rows.length < query.limit) {
1830
- const records = this.db
1831
- .query<
1832
- SqliteRowRecord & { payload: Uint8Array | null },
1833
- (string | number)[]
1834
- >(sql)
1835
- .all(
1836
- partition,
1837
- query.table,
1838
- firstVariable,
1839
- ...firstValues,
1840
- afterRowId,
1841
- batchSize,
1842
- partition,
1843
- );
1844
- if (records.length === 0) break;
1845
- for (const record of records) {
1846
- afterRowId = record.row_id;
1847
- // NULL payload: an index candidate whose row vanished — it still
1848
- // advances the keyset cursor (LEFT JOIN contract) but yields no row.
1849
- if (record.payload === null) continue;
1850
- const stored = toStoredRow(record);
1851
- if (!matchesEffective(stored.scopes, query.scopeFilter)) continue;
1852
- rows.push(stored);
1853
- if (rows.length >= query.limit) break;
1854
- }
1855
- if (records.length < batchSize) break;
1856
- }
1857
- return rows;
1858
- }
1859
-
1860
- async scanRowsByIndex(
1861
- partition: string,
1862
- query: IndexRowScanQuery,
1863
- ): Promise<StoredRow[]> {
1864
- const table = this.table(query.table);
1865
- const index = resolveIndexRowScan(table, query);
1866
- const statement = indexRowPageStatement(
1867
- table,
1868
- index,
1869
- query.values,
1870
- partition,
1871
- query.afterRowId,
1872
- query.limit,
1873
- 'sqlite',
1874
- );
1875
- const params = statement.params as readonly (
1876
- | string
1877
- | number
1878
- | Uint8Array
1879
- | null
1880
- )[];
1881
- const records = this.db
1882
- .query<SqliteRowRecord, (string | number | Uint8Array | null)[]>(
1883
- statement.sql,
1884
- )
1885
- .all(...params);
1886
- return records.map(toStoredRow);
1887
- }
1888
-
1889
- async getClientRecord(
1890
- partition: string,
1891
- clientId: string,
1892
- ): Promise<ClientRecord | undefined> {
1893
- const record = this.db
1894
- .query<
1895
- {
1896
- client_id: string;
1897
- actor_id: string;
1898
- wire_version: number;
1899
- cursor: number;
1900
- subscriptions: string;
1901
- updated_at_ms: number;
1902
- last_round_at_ms: number | null;
1903
- last_error_code: string | null;
1904
- consecutive_failures: number;
1905
- },
1906
- [string, string]
1907
- >(
1908
- 'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=? AND client_id=?',
1909
- )
1910
- .get(partition, clientId);
1911
- if (record === null) return undefined;
1912
- return {
1913
- clientId: record.client_id,
1914
- actorId: record.actor_id,
1915
- wireVersion: record.wire_version,
1916
- cursor: record.cursor,
1917
- updatedAtMs: record.updated_at_ms,
1918
- subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
1919
- ...clientRoundState(
1920
- record.last_round_at_ms,
1921
- record.last_error_code,
1922
- record.consecutive_failures,
1923
- ),
1924
- };
1925
- }
1926
-
1927
- async putClientRecord(
1928
- partition: string,
1929
- record: ClientRecord,
1930
- options?: ClientRecordWriteOptions,
1931
- ): Promise<void> {
1932
- this.db
958
+ const result = this.db
1933
959
  .query(
1934
- `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
1935
- ON CONFLICT(partition, client_id) DO UPDATE SET
1936
- actor_id=excluded.actor_id,
1937
- wire_version=excluded.wire_version,
1938
- cursor=excluded.cursor,
1939
- subscriptions=excluded.subscriptions,
1940
- updated_at_ms=excluded.updated_at_ms,
1941
- last_round_at_ms=excluded.last_round_at_ms${
1942
- options?.keepRoundOutcome === true
1943
- ? ''
1944
- : `,
1945
- last_error_code=NULL,
1946
- consecutive_failures=0`
1947
- }`,
1948
- )
1949
- .run(
1950
- partition,
1951
- record.clientId,
1952
- record.actorId,
1953
- record.wireVersion,
1954
- record.cursor,
1955
- JSON.stringify(record.subscriptions),
1956
- record.updatedAtMs,
1957
- record.updatedAtMs,
1958
- );
1959
- }
1960
-
1961
- async recordClientRoundFailure(
1962
- partition: string,
1963
- clientId: string,
1964
- actorId: string,
1965
- errorCode: string,
1966
- atMs: number,
1967
- ): Promise<void> {
1968
- this.db
1969
- .query(
1970
- `UPDATE sync_clients
1971
- SET last_round_at_ms=?, last_error_code=?,
1972
- consecutive_failures=consecutive_failures+1
1973
- WHERE partition=? AND client_id=? AND actor_id=?`,
1974
- )
1975
- .run(atMs, errorCode, partition, clientId, actorId);
1976
- }
1977
-
1978
- async advanceClientCursor(
1979
- partition: string,
1980
- clientId: string,
1981
- actorId: string,
1982
- logEpoch: string,
1983
- cursor: number,
1984
- updatedAtMs: number,
1985
- ): Promise<void> {
1986
- this.db
1987
- .query(`UPDATE sync_clients
1988
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
1989
- WHERE partition=? AND client_id=? AND actor_id=?
1990
- AND EXISTS (SELECT 1 FROM sync_partition_registry
1991
- WHERE partition=sync_clients.partition AND log_epoch=?)`)
1992
- .run(cursor, updatedAtMs, partition, clientId, actorId, logEpoch);
1993
- }
1994
-
1995
- async updateClientCursor(
1996
- partition: string,
1997
- clientId: string,
1998
- cursor: number,
1999
- updatedAtMs: number,
2000
- ): Promise<void> {
2001
- this.db
2002
- .query(
2003
- `UPDATE sync_clients
2004
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
2005
- WHERE partition=? AND client_id=?`,
2006
- )
2007
- .run(cursor, updatedAtMs, partition, clientId);
2008
- }
2009
-
2010
- async getActiveClientCursorFloor(
2011
- partition: string,
2012
- cutoffMs: number,
2013
- ): Promise<number | null> {
2014
- const row = this.db
2015
- .query<{ cursor: number | null }, [string, number]>(
2016
- 'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?',
2017
- )
2018
- .get(partition, cutoffMs);
2019
- return row!.cursor;
2020
- }
2021
-
2022
- async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
2023
- const records = this.db
2024
- .query<
2025
- { client_id: string; cursor: number; updated_at_ms: number },
2026
- [string]
2027
- >(
2028
- 'SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?',
2029
- )
2030
- .all(partition);
2031
- return records.map((r) => ({
2032
- clientId: r.client_id,
2033
- cursor: r.cursor,
2034
- updatedAtMs: r.updated_at_ms,
2035
- }));
2036
- }
2037
-
2038
- async listRowsReferencingBlob(
2039
- partition: string,
2040
- blobId: string,
2041
- ): Promise<
2042
- {
2043
- readonly table: string;
2044
- readonly rowId: string;
2045
- readonly scopes: Record<string, string>;
2046
- }[]
2047
- > {
2048
- // Candidate rows via the by-blob index (§5.9.4/§5.9.5); each row's
2049
- // stored scopes come from sync_rows for the §3.4 authorization test.
2050
- const refs = this.db
2051
- .query<{ tbl: string; row_id: string }, [string, string]>(
2052
- 'SELECT tbl, row_id FROM sync_blob_refs WHERE partition=? AND blob_id=?',
2053
- )
2054
- .all(partition, blobId);
2055
- const out: {
2056
- table: string;
2057
- rowId: string;
2058
- scopes: Record<string, string>;
2059
- }[] = [];
2060
- for (const ref of refs) {
2061
- const compiled = this.#tables?.get(ref.tbl);
2062
- if (compiled === undefined) continue; // table no longer in the schema
2063
- const row = this.db
2064
- .query<{ scopes: string }, [string, string]>(
2065
- selectRowScopesSql(compiled, 'sqlite'),
2066
- )
2067
- .get(partition, ref.row_id);
2068
- if (row === null) continue;
2069
- out.push({
2070
- table: ref.tbl,
2071
- rowId: ref.row_id,
2072
- scopes: JSON.parse(row.scopes) as Record<string, string>,
2073
- });
2074
- }
2075
- return out;
2076
- }
2077
-
2078
- async listReferencedBlobIds(partition: string): Promise<string[]> {
2079
- const rows = this.db
2080
- .query<{ blob_id: string }, [string]>(
2081
- 'SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=?',
2082
- )
2083
- .all(partition);
2084
- return rows.map((r) => r.blob_id);
2085
- }
2086
-
2087
- async listScopeValueRows(
2088
- partition: string,
2089
- query: ScopeValueQuery,
2090
- ): Promise<string[]> {
2091
- return this.db
2092
- .query<{ row_id: string }, [string, string, string, string, number]>(
2093
- LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
2094
- )
2095
- .all(partition, query.table, query.variable, query.value, query.limit)
2096
- .map((row) => row.row_id);
2097
- }
2098
-
2099
- async eraseScopeValueHistory(
2100
- partition: string,
2101
- query: ScopeValueHistoryQuery,
2102
- ): Promise<number> {
2103
- const params = eraseScopeValueHistoryParams(partition, query);
2104
- return this.#serializeWrite(() => {
2105
- this.db.exec('BEGIN IMMEDIATE');
2106
- try {
2107
- let removed = 0;
2108
- for (const sql of ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL) {
2109
- removed += this.db.query(sql).all(...params).length;
2110
- }
2111
- this.db.exec('COMMIT');
2112
- return removed;
2113
- } catch (error) {
2114
- rollbackAfterError(() => {
2115
- this.db.exec('ROLLBACK');
2116
- }, error);
2117
- }
2118
- });
2119
- }
2120
-
2121
- // -- admin/console read surface --------------------------------------------
2122
-
2123
- async listClientRecords(partition: string): Promise<ClientRecord[]> {
2124
- const records = this.db
2125
- .query<
2126
- {
2127
- client_id: string;
2128
- actor_id: string;
2129
- wire_version: number;
2130
- cursor: number;
2131
- subscriptions: string;
2132
- updated_at_ms: number;
2133
- last_round_at_ms: number | null;
2134
- last_error_code: string | null;
2135
- consecutive_failures: number;
2136
- },
2137
- [string]
2138
- >(
2139
- 'SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms, last_error_code, consecutive_failures FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC',
2140
- )
2141
- .all(partition);
2142
- return records.map((record) => ({
2143
- clientId: record.client_id,
2144
- actorId: record.actor_id,
2145
- wireVersion: record.wire_version,
2146
- cursor: record.cursor,
2147
- updatedAtMs: record.updated_at_ms,
2148
- subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
2149
- ...clientRoundState(
2150
- record.last_round_at_ms,
2151
- record.last_error_code,
2152
- record.consecutive_failures,
2153
- ),
2154
- }));
2155
- }
2156
-
2157
- async listCommitMetadata(
2158
- partition: string,
2159
- query: CommitMetadataQuery,
2160
- ): Promise<CommitMetadata[]> {
2161
- // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
2162
- // ended by `beforeSeq` (exclusive upper bound) when paging older. An
2163
- // omitted bound is the largest safe commitSeq, so one statement serves
2164
- // both the bounded and unbounded read.
2165
- const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
2166
- const rows = query.table
2167
- ? this.db
2168
- .query<
2169
- {
2170
- commit_seq: number;
2171
- client_id: string;
2172
- client_commit_id: string;
2173
- actor_id: string;
2174
- created_at_ms: number;
2175
- },
2176
- [string, number, number, string, number]
2177
- >(
2178
- `SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
2179
- FROM sync_commits c
2180
- WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
2181
- AND EXISTS (SELECT 1 FROM sync_changes ch
2182
- WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
2183
- ORDER BY c.commit_seq DESC LIMIT ?`,
2184
- )
2185
- .all(partition, query.afterSeq, beforeSeq, query.table, query.limit)
2186
- : this.db
2187
- .query<
2188
- {
2189
- commit_seq: number;
2190
- client_id: string;
2191
- client_commit_id: string;
2192
- actor_id: string;
2193
- created_at_ms: number;
2194
- },
2195
- [string, number, number, number]
2196
- >(
2197
- `SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
2198
- FROM sync_commits
2199
- WHERE partition=? AND commit_seq>? AND commit_seq<?
2200
- ORDER BY commit_seq DESC LIMIT ?`,
2201
- )
2202
- .all(partition, query.afterSeq, beforeSeq, query.limit);
2203
- // `changeSample`: one extra statement for the whole page — the first
2204
- // `sample` changes (change-index order) of every listed commit.
2205
- const sampleCount =
2206
- query.changeSample !== undefined &&
2207
- Number.isInteger(query.changeSample) &&
2208
- query.changeSample > 0
2209
- ? query.changeSample
2210
- : 0;
2211
- const samples = new Map<number, CommitChangeSummary[]>();
2212
- if (sampleCount > 0 && rows.length > 0) {
2213
- const seqs = rows.map((row) => row.commit_seq);
2214
- const records = this.db
2215
- .query<
2216
- { commit_seq: number; tbl: string; row_id: string; op: number },
2217
- (string | number)[]
2218
- >(
2219
- `SELECT commit_seq, tbl, row_id, op FROM sync_changes
2220
- WHERE partition=? AND commit_seq IN (${placeholders(seqs.length)}) AND idx<?
2221
- ORDER BY commit_seq, idx`,
2222
- )
2223
- .all(partition, ...seqs, sampleCount);
2224
- for (const record of records) {
2225
- const sample = samples.get(record.commit_seq) ?? [];
2226
- sample.push({
2227
- table: record.tbl,
2228
- rowId: record.row_id,
2229
- op: record.op === 1 ? 'upsert' : 'delete',
2230
- });
2231
- samples.set(record.commit_seq, sample);
2232
- }
2233
- }
2234
- return rows.map((row) => {
2235
- const changes = this.db
2236
- .query<{ tbl: string; n: number }, [string, number]>(
2237
- 'SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl',
2238
- )
2239
- .all(partition, row.commit_seq);
2240
- return {
2241
- commitSeq: row.commit_seq,
2242
- clientId: row.client_id,
2243
- clientCommitId: row.client_commit_id,
2244
- actorId: row.actor_id,
2245
- createdAtMs: row.created_at_ms,
2246
- changeCount: changes.reduce((sum, c) => sum + c.n, 0),
2247
- tables: changes.map((c) => c.tbl),
2248
- ...(sampleCount > 0
2249
- ? { sample: samples.get(row.commit_seq) ?? [] }
2250
- : {}),
2251
- };
2252
- });
2253
- }
2254
-
2255
- async getCommit(
2256
- partition: string,
2257
- commitSeq: number,
2258
- ): Promise<CommitDetail | undefined> {
2259
- const meta = this.db
2260
- .query<
2261
- {
2262
- client_id: string;
2263
- client_commit_id: string;
2264
- actor_id: string;
2265
- created_at_ms: number;
2266
- },
2267
- [string, number]
2268
- >(
2269
- 'SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
2270
- )
2271
- .get(partition, commitSeq);
2272
- if (meta === null) return undefined;
2273
- const changes = this.db
2274
- .query<SqliteChangeRecord, [string, number]>(
2275
- 'SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx',
2276
- )
2277
- .all(partition, commitSeq)
2278
- .map(toStoredChange);
2279
- return {
2280
- commitSeq,
2281
- clientId: meta.client_id,
2282
- clientCommitId: meta.client_commit_id,
2283
- actorId: meta.actor_id,
2284
- createdAtMs: meta.created_at_ms,
2285
- changeCount: changes.length,
2286
- tables: [...new Set(changes.map((change) => change.table))].sort(),
2287
- changes,
2288
- };
2289
- }
2290
-
2291
- async listRowChanges(
2292
- partition: string,
2293
- query: RowChangesQuery,
2294
- ): Promise<RowChangeRecord[]> {
2295
- // Retained-log read for one row: no dedicated index (the write path pays
2296
- // nothing for it), bounded by retention (§4.6).
2297
- return this.db
2298
- .query<
2299
- {
2300
- commit_seq: number;
2301
- op: number;
2302
- row_version: number | null;
2303
- actor_id: string;
2304
- client_id: string;
2305
- created_at_ms: number;
2306
- },
2307
- [string, string, string, number]
2308
- >(
2309
- `SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
2310
- FROM sync_changes ch
2311
- JOIN sync_commits c
2312
- ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
2313
- WHERE ch.partition=? AND ch.tbl=? AND ch.row_id=?
2314
- ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`,
2315
- )
2316
- .all(partition, query.table, query.rowId, query.limit)
2317
- .map((row) => ({
2318
- commitSeq: row.commit_seq,
2319
- op: row.op === 1 ? 'upsert' : 'delete',
2320
- ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
2321
- actorId: row.actor_id,
2322
- clientId: row.client_id,
2323
- createdAtMs: row.created_at_ms,
2324
- }));
2325
- }
2326
-
2327
- async listRows(partition: string, query: RowListQuery): Promise<StoredRow[]> {
2328
- // Keyset page over the row table's (partition, rowId) primary key: an
2329
- // index range read, no scope filter, no per-row lookup.
2330
- return this.db
2331
- .query<SqliteRowRecord, [string, string, number]>(
2332
- `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, ${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
2333
- FROM ${quoteIdent(this.table(query.table).name)}
2334
- WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
2335
- ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`,
2336
- )
2337
- .all(partition, query.afterRowId ?? '', query.limit)
2338
- .map(toStoredRow);
2339
- }
2340
-
2341
- async countRows(partition: string, table: string): Promise<number> {
2342
- const record = this.db
2343
- .query<{ n: number }, [string]>(
2344
- `SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`,
2345
- )
2346
- .get(partition);
2347
- return record?.n ?? 0;
2348
- }
2349
-
2350
- async listPushResults(
2351
- partition: string,
2352
- clientCommitId: string,
2353
- ): Promise<ClientPushResult[]> {
2354
- // Retained outcomes for one clientCommitId: no dedicated index, ordered
2355
- // by client so the read is deterministic.
2356
- return this.db
2357
- .query<{ client_id: string; result: string }, [string, string]>(
2358
- 'SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id',
2359
- )
2360
- .all(partition, clientCommitId)
2361
- .map((record) => {
2362
- try {
2363
- return {
2364
- clientId: record.client_id,
2365
- result: deserializePushResult(record.result),
2366
- };
2367
- } catch {
2368
- throw syncError(
2369
- 'sync.idempotency_cache_miss',
2370
- 'persisted push result unreadable (§6.3)',
2371
- );
2372
- }
2373
- });
2374
- }
2375
-
2376
- async scopeActivity(
2377
- partition: string,
2378
- query: ScopeActivityQuery,
2379
- ): Promise<ScopeCommitActivity[]> {
2380
- // Candidate commits via the change-scope index (§3.1) — never a scan.
2381
- const rows = this.db
2382
- .query<
2383
- { commit_seq: number; tbl: string },
2384
- [string, string, string, number]
2385
- >(
2386
- `SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
2387
- WHERE partition=? AND var=? AND value=?
2388
- ORDER BY commit_seq DESC LIMIT ?`,
960
+ `UPDATE sync_backfill_checkpoints
961
+ SET watermark=?, observed_rows=?, updated_at_ms=?
962
+ WHERE partition=? AND name=? AND owner_epoch=?`,
2389
963
  )
2390
- .all(partition, query.variable, query.value, query.limit);
2391
- const out: ScopeCommitActivity[] = [];
2392
- for (const row of rows) {
2393
- const meta = this.db
2394
- .query<{ actor_id: string; created_at_ms: number }, [string, number]>(
2395
- 'SELECT actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
2396
- )
2397
- .get(partition, row.commit_seq);
2398
- if (meta === null) continue;
2399
- const count = this.db
2400
- .query<{ n: number }, [string, number, string]>(
2401
- 'SELECT count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? AND tbl=?',
2402
- )
2403
- .get(partition, row.commit_seq, row.tbl);
2404
- out.push({
2405
- commitSeq: row.commit_seq,
2406
- table: row.tbl,
2407
- createdAtMs: meta.created_at_ms,
2408
- actorId: meta.actor_id,
2409
- changeCount: count?.n ?? 0,
2410
- });
2411
- }
2412
- return out;
2413
- }
2414
-
2415
- async listPartitions(): Promise<string[]> {
2416
- return (await this.listPartitionRegistry()).map((entry) => entry.partition);
964
+ .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
965
+ return Number(result.changes) === 1;
2417
966
  }
2418
967
  }