@syncular/server 0.58.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,24 +1,20 @@
1
- import { retainRollbackFailure, rollbackAfterError } from './storage-errors.js';
2
- import { validateCommitPruneQuery } from './prune.js';
3
- import { StorageQueryError } from './storage-errors.js';
4
- import { clientRoundState, PARTITION_TOUCH_INTERVAL_MS, rowsLiveAfterDelete, serveGateRefusal, } from './storage.js';
5
- import { serveNotReadyError } from './readiness.js';
6
1
  /**
7
- * 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.
8
6
  *
9
7
  * Scope fanout is index-first: both the commit log and the
10
8
  * current-row table carry a (table, variable, value) inverted index; reads
11
9
  * select candidates from the index and verify the full multi-variable
12
10
  * match against the stored scope map — never a log scan.
13
11
  */
14
- import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
15
- import { syncError } from './errors.js';
16
- import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, serverIndexDdl, SQLITE_TABLE_INDEXES_SQL, sqliteIndexSignatures, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
17
- import { matchesEffective } from './scopes.js';
18
- import { collectCommitWindowPage, deserializePushResult, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, placeholders, SQLITE_DDL, SYNC_CLIENT_ROUND_COLUMNS, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
12
+ import { isSqliteConstraintError, retainRollbackFailure, rollbackAfterError, StorageConstraintError, StorageQueryError, } from './storage-errors.js';
13
+ import { serveGateRefusal } from './storage.js';
14
+ import { serveNotReadyError } from './readiness.js';
15
+ import { assertPhysicalColumns, assertStoredLayouts, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, schemaDdl, serverIndexDdl, SQLITE_TABLE_INDEXES_SQL, sqliteIndexSignatures, selectRowsForRewriteSql, } from './relational-rows.js';
16
+ import { SQLITE_ADDED_COLUMNS, SQLITE_DDL, SqliteFamilyStorage, SqliteFamilyTransaction, } from './sqlite-dialect.js';
19
17
  import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
20
- import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
21
- import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
22
18
  function toStoredCheckpoint(record) {
23
19
  return {
24
20
  partition: record.partition,
@@ -31,124 +27,77 @@ function toStoredCheckpoint(record) {
31
27
  updatedAtMs: record.updated_at_ms,
32
28
  };
33
29
  }
34
- function toStoredReaction(record) {
35
- return {
36
- idempotencyKey: record.idempotency_key,
37
- type: record.type,
38
- version: record.version,
39
- payload: JSON.parse(record.payload),
40
- sourceClientId: record.source_client_id,
41
- sourceClientCommitId: record.source_client_commit_id,
42
- sourceCommitSeq: record.source_commit_seq,
43
- createdAtMs: record.created_at_ms,
44
- maxAttempts: record.max_attempts,
45
- status: record.status,
46
- attempts: record.attempts,
47
- availableAtMs: record.available_at_ms,
48
- ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
49
- ...(record.lease_expires_at_ms !== null
50
- ? { leaseExpiresAtMs: record.lease_expires_at_ms }
51
- : {}),
52
- ...(record.completed_at_ms !== null
53
- ? { completedAtMs: record.completed_at_ms }
54
- : {}),
55
- ...(record.last_failure !== null
56
- ? { lastFailure: JSON.parse(record.last_failure) }
57
- : {}),
58
- };
59
- }
60
- class SqliteTransaction {
30
+ class SqliteTransaction extends SqliteFamilyTransaction {
61
31
  #storage;
62
- #partition;
63
32
  /** Schema version this transaction writes; rides every appended commit row. */
64
33
  #writerVersion;
65
- #open = true;
66
34
  #pushApplySavepoint = false;
67
35
  #release;
68
36
  constructor(storage, partition, writerVersion, release) {
37
+ super(partition);
69
38
  this.#storage = storage;
70
- this.#partition = partition;
71
39
  this.#writerVersion = writerVersion;
72
40
  this.#release = release;
73
41
  storage.db.exec('BEGIN IMMEDIATE');
74
42
  }
75
- #assertOpen() {
76
- if (!this.#open)
77
- throw new Error('transaction already finished');
43
+ run(sql, params) {
44
+ this.#storage.db.run(sql, params);
78
45
  }
79
- getRow(table, rowId) {
80
- this.#assertOpen();
81
- return this.#storage.getRow(this.#partition, table, rowId);
82
- }
83
- async getRows(table, rowIds) {
84
- this.#assertOpen();
85
- // SQLite is in-process: one indexed lookup per id costs no round trip.
86
- const rows = new Map();
87
- for (const rowId of new Set(rowIds)) {
88
- const row = await this.#storage.getRow(this.#partition, table, rowId);
89
- if (row !== undefined)
90
- rows.set(rowId, row);
91
- }
92
- return rows;
46
+ async all(sql, params) {
47
+ return this.#storage.db.query(sql).all(...params);
93
48
  }
94
- async getTombstoneSeq(table, rowId) {
95
- this.#assertOpen();
96
- const row = this.#storage.db
97
- .query('SELECT commit_seq FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?')
98
- .get(this.#partition, table, rowId);
99
- return row?.commit_seq;
49
+ table(name) {
50
+ return this.#storage.table(name);
100
51
  }
101
- async clearTombstone(table, rowId) {
102
- this.#assertOpen();
103
- this.#storage.db
104
- .query('DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?')
105
- .run(this.#partition, table, rowId);
52
+ getRow(table, rowId) {
53
+ this.assertOpen();
54
+ return this.#storage.getRow(this.partition, table, rowId);
106
55
  }
107
56
  scanRows(query) {
108
- this.#assertOpen();
109
- return this.#storage.scanRows(this.#partition, query);
57
+ this.assertOpen();
58
+ return this.#storage.scanRows(this.partition, query);
110
59
  }
111
60
  scanRowsByIndex(query) {
112
- this.#assertOpen();
113
- return this.#storage.scanRowsByIndex(this.#partition, query);
61
+ this.assertOpen();
62
+ return this.#storage.scanRowsByIndex(this.partition, query);
114
63
  }
115
64
  async queryAuthoritative(query) {
116
- this.#assertOpen();
65
+ this.assertOpen();
117
66
  // Same shared connection: the query runs inside this transaction's
118
67
  // BEGIN IMMEDIATE and observes every row staged so far.
119
- return this.#storage.runAuthoritativeQuery(this.#partition, query);
68
+ return this.#storage.runAuthoritativeQuery(this.partition, query);
120
69
  }
121
70
  async preparePushApply(clientId, clientCommitId, runningSchemaVersion, _targets = []) {
122
- this.#assertOpen();
71
+ this.assertOpen();
123
72
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
124
73
  this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
125
74
  this.#pushApplySavepoint = true;
126
75
  return {
127
- gate: await this.#storage.readServeGate(this.#partition, runningSchemaVersion),
128
- persisted: await this.#storage.getPushResult(this.#partition, clientId, clientCommitId),
76
+ gate: await this.#storage.readServeGate(this.partition, runningSchemaVersion),
77
+ persisted: await this.#storage.getPushResult(this.partition, clientId, clientCommitId),
129
78
  };
130
79
  }
131
80
  async lockPartition() {
132
- this.#assertOpen();
81
+ this.assertOpen();
133
82
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
134
83
  }
135
84
  async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
136
- this.#assertOpen();
85
+ this.assertOpen();
137
86
  const result = this.#storage.db
138
87
  .query(`UPDATE sync_backfill_checkpoints
139
88
  SET watermark=?, observed_rows=?, updated_at_ms=?
140
89
  WHERE partition=? AND name=? AND owner_epoch=?`)
141
- .run(watermark, observedRows, nowMs, this.#partition, name, ownerEpoch);
90
+ .run(watermark, observedRows, nowMs, this.partition, name, ownerEpoch);
142
91
  return Number(result.changes) === 1;
143
92
  }
144
93
  readServeGate(runningSchemaVersion) {
145
- this.#assertOpen();
94
+ this.assertOpen();
146
95
  // Same shared connection: this read runs inside this transaction's
147
96
  // BEGIN IMMEDIATE, so the gate and the write share one transaction.
148
- return this.#storage.readServeGate(this.#partition, runningSchemaVersion);
97
+ return this.#storage.readServeGate(this.partition, runningSchemaVersion);
149
98
  }
150
99
  async commitRejectedPushResult(clientId, clientCommitId, result) {
151
- this.#assertOpen();
100
+ this.assertOpen();
152
101
  if (!this.#pushApplySavepoint) {
153
102
  throw new Error('push rejection requires its apply savepoint');
154
103
  }
@@ -162,9 +111,9 @@ class SqliteTransaction {
162
111
  return result;
163
112
  }
164
113
  async upsertRow(table, row, context) {
165
- this.#assertOpen();
114
+ this.assertOpen();
166
115
  try {
167
- this.#storage.writeRow(this.#partition, table, row);
116
+ this.writeRow(table, row);
168
117
  }
169
118
  catch (error) {
170
119
  if (isSqliteConstraintError(error)) {
@@ -173,71 +122,30 @@ class SqliteTransaction {
173
122
  throw error;
174
123
  }
175
124
  }
176
- async deleteRow(table, rowId) {
177
- this.#assertOpen();
178
- const db = this.#storage.db;
179
- const compiled = this.#storage.table(table);
180
- db.query(deleteSqliteRowScopesSql(compiled)).run(this.#partition, table, rowId, this.#partition, rowId);
181
- db.query(deleteRowSql(compiled, 'sqlite')).run(this.#partition, rowId);
182
- // §5.9.4: a deleted row references no blobs.
183
- db.query('DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?').run(this.#partition, table, rowId);
184
- }
185
- async setBlobRefs(table, rowId, blobIds) {
186
- this.#assertOpen();
187
- const db = this.#storage.db;
188
- // Replace the row's reference set atomically (§5.9.4).
189
- db.query('DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?').run(this.#partition, table, rowId);
190
- for (const blobId of blobIds) {
191
- db.query('INSERT OR IGNORE INTO sync_blob_refs(partition, tbl, row_id, blob_id) VALUES (?,?,?,?)').run(this.#partition, table, rowId, blobId);
192
- }
193
- }
194
- async appendCommit(commit) {
195
- this.#assertOpen();
196
- const db = this.#storage.db;
197
- const p = this.#partition;
198
- db.query('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)').run(p);
199
- const row = db
200
- .query('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
201
- .get(p);
125
+ async appendCommitRow(commit) {
126
+ const p = this.partition;
127
+ this.run('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)', [
128
+ p,
129
+ ]);
130
+ const [row] = await this.all('SELECT max_commit_seq FROM sync_partitions WHERE partition=?', [p]);
202
131
  const commitSeq = (row?.max_commit_seq ?? 0) + 1;
203
- db.query('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?').run(commitSeq, p);
204
- db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs, this.#writerVersion);
205
- const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
206
- commit.changes.forEach((change, idx) => {
207
- db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
208
- if (change.op === 'delete' &&
209
- !liveAfterDelete.has(`${change.table}\u0000${change.rowId}`)) {
210
- // §5 delete precedence: every applied delete leaves a tombstone,
211
- // pruned with the commit log (§4.6). A delete that the same commit
212
- // follows with an upsert is a §2.2 scope move, not a deletion.
213
- db.query(`INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
214
- ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`).run(p, change.table, change.rowId, commitSeq);
215
- }
216
- for (const [variable, value] of Object.entries(change.scopes)) {
217
- db.query('INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)').run(p, change.table, variable, value, commitSeq);
218
- }
219
- });
132
+ this.run('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?', [
133
+ commitSeq,
134
+ p,
135
+ ]);
136
+ this.run('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)', [
137
+ p,
138
+ commitSeq,
139
+ commit.clientId,
140
+ commit.clientCommitId,
141
+ commit.actorId,
142
+ commit.createdAtMs,
143
+ this.#writerVersion,
144
+ ]);
220
145
  return commitSeq;
221
146
  }
222
- async putPushResult(clientId, clientCommitId, result) {
223
- this.#assertOpen();
224
- this.#storage.db
225
- .query('INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)')
226
- .run(this.#partition, clientId, clientCommitId, serializePushResult(result));
227
- }
228
- async enqueueReactions(reactions) {
229
- this.#assertOpen();
230
- const statement = this.#storage.db.query(`INSERT INTO sync_reactions(
231
- partition, idempotency_key, type, version, payload,
232
- source_client_id, source_client_commit_id, source_commit_seq,
233
- created_at_ms, available_at_ms, status, attempts, max_attempts
234
- ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`);
235
- for (const reaction of reactions) {
236
- statement.run(this.#partition, reaction.idempotencyKey, reaction.type, reaction.version, JSON.stringify(reaction.payload), reaction.sourceClientId, reaction.sourceClientCommitId, reaction.sourceCommitSeq, reaction.createdAtMs, reaction.createdAtMs, reaction.maxAttempts);
237
- }
238
- }
239
147
  async commit() {
240
- this.#assertOpen();
148
+ this.assertOpen();
241
149
  try {
242
150
  this.#storage.db.exec('COMMIT');
243
151
  }
@@ -255,14 +163,14 @@ class SqliteTransaction {
255
163
  throw error;
256
164
  }
257
165
  finally {
258
- this.#open = false;
166
+ this.open = false;
259
167
  this.#release();
260
168
  }
261
169
  }
262
170
  async rollback() {
263
- if (!this.#open)
171
+ if (!this.open)
264
172
  return;
265
- this.#open = false;
173
+ this.open = false;
266
174
  try {
267
175
  this.#storage.db.exec('ROLLBACK');
268
176
  }
@@ -271,42 +179,49 @@ class SqliteTransaction {
271
179
  }
272
180
  }
273
181
  }
274
- export class SqliteServerStorage {
182
+ export class SqliteServerStorage extends SqliteFamilyStorage {
275
183
  db;
276
- /** One SQLite connection can own only one transaction at a time. */
277
- #transactionTail = Promise.resolve();
278
- /** Set by `ensureSchema`: app-table lookup for the relational row store. */
279
- #tables;
280
- #schemaVersion;
281
- async #serializeWrite(operation) {
282
- const previous = this.#transactionTail;
283
- let release;
284
- this.#transactionTail = new Promise((resolve) => {
285
- release = resolve;
286
- });
287
- await previous;
288
- try {
289
- return operation();
290
- }
291
- finally {
292
- release();
184
+ maxBindParams = Number.POSITIVE_INFINITY;
185
+ /**
186
+ * §6.4: one SQLite connection serves one caller at a time. A transaction
187
+ * holds it from `begin` until commit or rollback; every other call waits
188
+ * behind it in FIFO order, so no request reads another's uncommitted rows
189
+ * and no write joins another's open transaction. A call on an idle
190
+ * connection takes it synchronously and runs at call time.
191
+ */
192
+ #busy = false;
193
+ #waiters = [];
194
+ /** `undefined` when the caller owns the connection now. */
195
+ #acquire() {
196
+ if (!this.#busy) {
197
+ this.#busy = true;
198
+ return undefined;
293
199
  }
200
+ return new Promise((resolve) => {
201
+ this.#waiters.push(resolve);
202
+ });
203
+ }
204
+ /** Hand the connection to the next waiter, or mark it idle. */
205
+ #release() {
206
+ const next = this.#waiters.shift();
207
+ if (next === undefined)
208
+ this.#busy = false;
209
+ else
210
+ next();
294
211
  }
295
212
  constructor(db = ':memory:') {
296
213
  if (typeof db === 'string') {
297
214
  throw new SqliteAdapterRequiredError();
298
215
  }
216
+ super();
299
217
  this.db = db;
300
218
  this.db.exec(SQLITE_DDL);
301
- const clientColumns = this.db
302
- .query('PRAGMA table_info("sync_clients")')
303
- .all();
304
- if (!clientColumns.some((column) => column.name === 'wire_version')) {
305
- this.db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1');
306
- }
307
- for (const [name, definition] of Object.entries(SYNC_CLIENT_ROUND_COLUMNS)) {
308
- if (!clientColumns.some((column) => column.name === name)) {
309
- this.db.exec(`ALTER TABLE sync_clients ADD COLUMN ${name} ${definition}`);
219
+ for (const [table, name, definition] of SQLITE_ADDED_COLUMNS) {
220
+ const columns = this.db
221
+ .query(`PRAGMA table_info("${table}")`)
222
+ .all();
223
+ if (!columns.some((column) => column.name === name)) {
224
+ this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
310
225
  }
311
226
  }
312
227
  const commitColumns = this.db
@@ -333,18 +248,60 @@ WHEN EXISTS (
333
248
  BEGIN
334
249
  SELECT RAISE(ABORT, 'sync.storage.writer_fence_rejected');
335
250
  END`);
251
+ // Callers receive this proxy: every method except the ones below runs
252
+ // under `#acquire`. Methods execute against the raw instance, so a
253
+ // transaction (constructed with the raw instance) and a method's own
254
+ // internal calls never queue behind themselves.
255
+ return new Proxy(this, {
256
+ get: (target, property) => {
257
+ const value = Reflect.get(target, property, target);
258
+ // An own property is a caller's override (a test double or host
259
+ // wrapper); it reaches the queue through the original it calls.
260
+ if (typeof value !== 'function' || Object.hasOwn(target, property)) {
261
+ return value;
262
+ }
263
+ if (property === 'begin' ||
264
+ property === 'table' ||
265
+ property === 'runAuthoritativeQuery' ||
266
+ property === 'constructor') {
267
+ return value.bind(target);
268
+ }
269
+ return (...args) => {
270
+ const run = async () => {
271
+ try {
272
+ return await Reflect.apply(value, target, args);
273
+ }
274
+ finally {
275
+ target.#release();
276
+ }
277
+ };
278
+ return target.#acquire()?.then(run) ?? run();
279
+ };
280
+ },
281
+ });
336
282
  }
337
- /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
338
- table(name) {
339
- const table = this.#tables?.get(name);
340
- if (table === undefined) {
341
- throw new Error(`unknown table ${JSON.stringify(name)} — ensureSchema(schema) must run before row operations`);
283
+ async all(sql, params) {
284
+ return this.db.query(sql).all(...params);
285
+ }
286
+ guardedAll(sql, params) {
287
+ return this.all(sql, params);
288
+ }
289
+ async atomic(statements) {
290
+ this.db.exec('BEGIN IMMEDIATE');
291
+ try {
292
+ const results = statements.map(({ sql, params }) => this.db.query(sql).all(...params));
293
+ this.db.exec('COMMIT');
294
+ return results;
295
+ }
296
+ catch (error) {
297
+ rollbackAfterError(() => {
298
+ this.db.exec('ROLLBACK');
299
+ }, error);
342
300
  }
343
- return table;
344
301
  }
345
302
  async ensureSchema(schema, checkpoints) {
346
303
  // Memoized fast path: same instance, same schema version.
347
- if (this.#schemaVersion === schema.version)
304
+ if (this.schemaVersion === schema.version)
348
305
  return;
349
306
  // The barrier reads stored state: a checkpoint at this schema version that
350
307
  // is not activated and that this caller did not declare means this process
@@ -390,19 +347,17 @@ END`);
390
347
  .all(table.name)))),
391
348
  ])));
392
349
  if (reconcile.length > 0) {
393
- await this.#serializeWrite(() => {
394
- this.db.exec('BEGIN IMMEDIATE');
395
- try {
396
- for (const statement of reconcile)
397
- this.db.exec(statement);
398
- this.db.exec('COMMIT');
399
- }
400
- catch (error) {
401
- rollbackAfterError(() => {
402
- this.db.exec('ROLLBACK');
403
- }, error);
404
- }
405
- });
350
+ this.db.exec('BEGIN IMMEDIATE');
351
+ try {
352
+ for (const statement of reconcile)
353
+ this.db.exec(statement);
354
+ this.db.exec('COMMIT');
355
+ }
356
+ catch (error) {
357
+ rollbackAfterError(() => {
358
+ this.db.exec('ROLLBACK');
359
+ }, error);
360
+ }
406
361
  }
407
362
  }
408
363
  if (marker === null || marker.schema_version < schema.version) {
@@ -426,126 +381,69 @@ END`);
426
381
  }
427
382
  }
428
383
  // The migration rewrites application rows (`#rewriteRows`) with no
429
- // commit log entry. Serialize it through the same writer queue as
430
- // pushes and prune (`#serializeWrite`) rather than trusting the
431
- // migration as privileged; `BEGIN IMMEDIATE` then owns SQLite's writer
432
- // lock for the whole rewrite.
433
- await this.#serializeWrite(() => {
434
- this.db.exec('BEGIN IMMEDIATE');
435
- try {
436
- // Another process sharing the database may have bumped between the
437
- // marker read above and the writer lock; the locked marker decides
438
- // (SPEC "Schema upgrade writer fence").
439
- const locked = this.db
440
- .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
441
- .get();
442
- if (locked !== null && locked.schema_version > schema.version) {
443
- throw new Error(`stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
444
- }
445
- if (locked !== null && locked.schema_version === schema.version) {
446
- this.db.exec('COMMIT');
447
- return;
448
- }
449
- const layouts = parseLayouts(locked?.layouts);
450
- const retiredTables = retiredTableNames(schema, layouts);
451
- for (const tableName of retiredTables) {
452
- this.db
453
- .query('DELETE FROM sync_row_scopes WHERE tbl=?')
454
- .run(tableName);
455
- this.db
456
- .query('DELETE FROM sync_blob_refs WHERE tbl=?')
457
- .run(tableName);
458
- this.db.exec(dropTableDdl(tableName));
459
- }
460
- for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
461
- this.db.exec(statement);
462
- }
463
- for (const table of schema.tables.values()) {
464
- const oldLayout = layouts[table.name];
465
- const plan = rewritePlan(table, oldLayout, existing.get(table.name));
466
- if (!plan.migrate && !plan.backfill)
467
- continue;
468
- this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
469
- }
384
+ // commit log entry. It runs behind the same connection queue as pushes
385
+ // and prune rather than trusting the migration as privileged;
386
+ // `BEGIN IMMEDIATE` then owns SQLite's writer lock for the whole
387
+ // rewrite.
388
+ this.db.exec('BEGIN IMMEDIATE');
389
+ try {
390
+ // Another process sharing the database may have bumped between the
391
+ // marker read above and the writer lock; the locked marker decides
392
+ // (SPEC "Schema upgrade writer fence").
393
+ const locked = this.db
394
+ .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
395
+ .get();
396
+ if (locked !== null && locked.schema_version > schema.version) {
397
+ throw new Error(`stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
398
+ }
399
+ if (locked !== null && locked.schema_version === schema.version) {
400
+ this.db.exec('COMMIT');
401
+ this.tables = schema.tables;
402
+ this.schemaVersion = schema.version;
403
+ return;
404
+ }
405
+ const layouts = parseLayouts(locked?.layouts);
406
+ const retiredTables = retiredTableNames(schema, layouts);
407
+ for (const tableName of retiredTables) {
470
408
  this.db
471
- .query('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')
472
- .run(schema.version, layoutsOf(schema));
473
- // A writer of the previous schema would append payloads in the
474
- // previous layout; the bump fences every partition at the new
475
- // version (see PostgresServerStorage.ensureSchema).
409
+ .query('DELETE FROM sync_row_scopes WHERE tbl=?')
410
+ .run(tableName);
476
411
  this.db
477
- .query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
478
- SELECT partition, ? FROM sync_partitions WHERE true
479
- ON CONFLICT(partition) DO UPDATE SET
480
- required_writer_version=max(
481
- sync_writer_fence.required_writer_version,
482
- excluded.required_writer_version)`)
483
- .run(schema.version);
484
- // The host's declared checkpoints install in the schema-bump
485
- // transaction, so no observer sees the bumped marker without the
486
- // fence, or the fence without its declaration row.
487
- const installedAtMs = Date.now();
488
- for (const declaration of checkpoints ?? []) {
489
- this.#installCheckpoint(declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
490
- }
491
- this.db.exec('COMMIT');
412
+ .query('DELETE FROM sync_blob_refs WHERE tbl=?')
413
+ .run(tableName);
414
+ this.db.exec(dropTableDdl(tableName));
492
415
  }
493
- catch (error) {
494
- rollbackAfterError(() => {
495
- this.db.exec('ROLLBACK');
496
- }, error);
416
+ for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
417
+ this.db.exec(statement);
418
+ }
419
+ for (const table of schema.tables.values()) {
420
+ const oldLayout = layouts[table.name];
421
+ const plan = rewritePlan(table, oldLayout, existing.get(table.name));
422
+ if (!plan.migrate && !plan.backfill)
423
+ continue;
424
+ this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
497
425
  }
498
- });
499
- }
500
- this.#tables = schema.tables;
501
- this.#schemaVersion = schema.version;
502
- }
503
- async touchPartition(partition, authenticatedAtMs, initialLogEpoch) {
504
- if (initialLogEpoch.length === 0) {
505
- throw new Error('initial log epoch must be non-empty');
506
- }
507
- const select = this.db.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
508
- FROM sync_partition_registry WHERE partition=?`);
509
- let row = select.get(partition);
510
- if (row === null ||
511
- authenticatedAtMs - row.last_authenticated_at_ms >=
512
- PARTITION_TOUCH_INTERVAL_MS) {
513
- this.db
514
- .query(`INSERT INTO sync_partition_registry(
515
- partition, log_epoch, last_authenticated_at_ms
516
- ) VALUES (?,?,?)
517
- ON CONFLICT(partition) DO UPDATE SET
518
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
519
- .run(partition, initialLogEpoch, authenticatedAtMs);
520
- row = select.get(partition);
521
- }
522
- if (row === null)
523
- throw new Error('partition registry write did not persist');
524
- return {
525
- partition,
526
- logEpoch: row.log_epoch,
527
- epochRequired: row.epoch_required === 1,
528
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
529
- };
530
- }
531
- async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
532
- if (logEpoch.length === 0)
533
- throw new Error('log epoch must be non-empty');
534
- return this.#serializeWrite(() => {
535
- this.db.exec('BEGIN IMMEDIATE');
536
- try {
537
426
  this.db
538
- .query(`INSERT INTO sync_partition_registry(
539
- partition, log_epoch, epoch_required, last_authenticated_at_ms
540
- ) VALUES (?,?,1,?)
541
- ON CONFLICT(partition) DO UPDATE SET
542
- log_epoch=excluded.log_epoch,
543
- epoch_required=1,
544
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
545
- .run(partition, logEpoch, authenticatedAtMs);
427
+ .query('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')
428
+ .run(schema.version, layoutsOf(schema));
429
+ // A writer of the previous schema would append payloads in the
430
+ // previous layout; the bump fences every partition at the new
431
+ // version (see PostgresServerStorage.ensureSchema).
546
432
  this.db
547
- .query('DELETE FROM sync_clients WHERE partition=?')
548
- .run(partition);
433
+ .query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
434
+ SELECT partition, ? FROM sync_partitions WHERE true
435
+ ON CONFLICT(partition) DO UPDATE SET
436
+ required_writer_version=max(
437
+ sync_writer_fence.required_writer_version,
438
+ excluded.required_writer_version)`)
439
+ .run(schema.version);
440
+ // The host's declared checkpoints install in the schema-bump
441
+ // transaction, so no observer sees the bumped marker without the
442
+ // fence, or the fence without its declaration row.
443
+ const installedAtMs = Date.now();
444
+ for (const declaration of checkpoints ?? []) {
445
+ this.#installCheckpoint(declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
446
+ }
549
447
  this.db.exec('COMMIT');
550
448
  }
551
449
  catch (error) {
@@ -553,25 +451,9 @@ END`);
553
451
  this.db.exec('ROLLBACK');
554
452
  }, error);
555
453
  }
556
- return {
557
- partition,
558
- logEpoch,
559
- epochRequired: true,
560
- lastAuthenticatedAtMs: authenticatedAtMs,
561
- };
562
- });
563
- }
564
- async listPartitionRegistry() {
565
- return this.db
566
- .query(`SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
567
- FROM sync_partition_registry ORDER BY partition`)
568
- .all()
569
- .map((row) => ({
570
- partition: row.partition,
571
- logEpoch: row.log_epoch,
572
- epochRequired: row.epoch_required === 1,
573
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
574
- }));
454
+ }
455
+ this.tables = schema.tables;
456
+ this.schemaVersion = schema.version;
575
457
  }
576
458
  /**
577
459
  * Migration rewrite: keyset-paged walk of a row table. When `oldLayout` is
@@ -609,41 +491,15 @@ END`);
609
491
  // database file, so one FIFO over the shared connection is the correct
610
492
  // serialization unit — a per-partition queue would still contend on the
611
493
  // same BEGIN IMMEDIATE writer lock.
612
- const previous = this.#transactionTail;
613
- let release;
614
- this.#transactionTail = new Promise((resolve) => {
615
- release = resolve;
616
- });
617
- await previous;
494
+ await this.#acquire();
618
495
  try {
619
- return new SqliteTransaction(this, partition, this.#schemaVersion ?? 0, release);
496
+ return new SqliteTransaction(this, partition, this.schemaVersion ?? 0, () => this.#release());
620
497
  }
621
498
  catch (error) {
622
- release();
499
+ this.#release();
623
500
  throw error;
624
501
  }
625
502
  }
626
- /** Internal: write a row + refresh its scope-index entries. */
627
- writeRow(partition, table, row) {
628
- const compiled = this.table(table);
629
- this.db
630
- .query(deleteSqliteRowScopesSql(compiled))
631
- .run(partition, table, row.rowId, partition, row.rowId);
632
- this.db
633
- .query(upsertSql(compiled, 'sqlite'))
634
- .run(...upsertValues(compiled, partition, row, 'sqlite'));
635
- for (const [variable, value] of Object.entries(row.scopes)) {
636
- this.db
637
- .query('INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)')
638
- .run(partition, table, variable, value, row.rowId);
639
- }
640
- }
641
- async getMaxCommitSeq(partition) {
642
- const row = this.db
643
- .query('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
644
- .get(partition);
645
- return row?.max_commit_seq ?? 0;
646
- }
647
503
  /**
648
504
  * Internal: rewrite and run one registered query on the shared connection.
649
505
  * The caller owns the transaction: `queryAuthoritative` opens a read
@@ -651,10 +507,7 @@ END`);
651
507
  * inside the push transaction's `BEGIN IMMEDIATE`.
652
508
  */
653
509
  runAuthoritativeQuery(partition, query) {
654
- if (this.#tables === undefined) {
655
- throw new Error('ensureSchema(schema) must run before registered queries');
656
- }
657
- const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
510
+ const prepared = this.prepareAuthoritativeQuery(partition, query);
658
511
  const rows = this.db
659
512
  .query(prepared.sql)
660
513
  .all(...prepared.params);
@@ -664,12 +517,6 @@ END`);
664
517
  return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
665
518
  }
666
519
  async queryAuthoritative(partition, query, checkpoints) {
667
- const previous = this.#transactionTail;
668
- let release;
669
- this.#transactionTail = new Promise((resolve) => {
670
- release = resolve;
671
- });
672
- await previous;
673
520
  let open = false;
674
521
  try {
675
522
  this.db.exec('BEGIN');
@@ -677,7 +524,7 @@ END`);
677
524
  // RFC 0007: evaluate the gate on this connection after BEGIN. SQLite is
678
525
  // single-writer and the shared connection serializes writers, so the
679
526
  // gate read and the query read cannot straddle a migration.
680
- const runningVersion = this.#schemaVersion ?? 0;
527
+ const runningVersion = this.schemaVersion ?? 0;
681
528
  const gate = await this.readServeGate(partition, runningVersion);
682
529
  const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
683
530
  if (refusal !== undefined)
@@ -693,98 +540,15 @@ END`);
693
540
  this.db.exec('ROLLBACK');
694
541
  }, error);
695
542
  }
696
- finally {
697
- release();
698
- }
699
- }
700
- async getPartitionLogEpoch(partition) {
701
- return this.db
702
- .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
703
- .get(partition)?.log_epoch;
704
- }
705
- async getHorizonSeq(partition) {
706
- const row = this.db
707
- .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
708
- .get(partition);
709
- return row?.horizon_seq ?? 0;
710
- }
711
- async setHorizonSeq(partition, seq) {
712
- await this.#serializeWrite(() => {
713
- this.db
714
- .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
715
- ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
716
- .run(partition, seq);
717
- });
718
- }
719
- async pruneCommitsThrough(partition, query) {
720
- validateCommitPruneQuery(query);
721
- return this.#serializeWrite(() => {
722
- this.db.exec('BEGIN IMMEDIATE');
723
- try {
724
- const epoch = this.db
725
- .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
726
- .get(partition)?.log_epoch;
727
- if (epoch !== query.logEpoch)
728
- throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
729
- const previousHorizonSeq = this.db
730
- .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
731
- .get(partition)?.horizon_seq ?? 0;
732
- const horizonSeq = Math.max(previousHorizonSeq, query.throughSeq);
733
- this.db
734
- .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
735
- ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq`)
736
- .run(partition, horizonSeq);
737
- const removed = this.db
738
- .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
739
- .run(partition, horizonSeq);
740
- this.db
741
- .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
742
- .run(partition, horizonSeq);
743
- this.db
744
- .query('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
745
- .run(partition, horizonSeq);
746
- // §4.6: tombstones prune in the same pass as the commit log.
747
- this.db
748
- .query('DELETE FROM sync_tombstones WHERE partition=? AND commit_seq<=?')
749
- .run(partition, horizonSeq);
750
- this.db.exec('COMMIT');
751
- return {
752
- previousHorizonSeq,
753
- horizonSeq,
754
- removedCommits: Number(removed.changes),
755
- };
756
- }
757
- catch (error) {
758
- rollbackAfterError(() => {
759
- this.db.exec('ROLLBACK');
760
- }, error);
761
- }
762
- });
763
- }
764
- async getCommitSeqBefore(partition, createdBeforeMs) {
765
- const row = this.db
766
- .query('SELECT max(commit_seq) AS seq FROM sync_commits WHERE partition=? AND created_at_ms<?')
767
- .get(partition, createdBeforeMs);
768
- return row?.seq ?? 0;
769
543
  }
770
544
  async readServeGate(partition, runningSchemaVersion) {
771
- const marker = this.db
772
- .query('SELECT schema_version FROM sync_schema_meta WHERE id=1')
773
- .get();
774
- const epoch = this.db
775
- .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
776
- .get(partition);
777
- const pending = this.db
778
- .query(`SELECT partition, name FROM sync_backfill_checkpoints
779
- WHERE schema_version=? AND state<>'activated'`)
780
- .all(runningSchemaVersion);
545
+ const [marker] = await this.all('SELECT schema_version FROM sync_schema_meta WHERE id=1', []);
546
+ const pending = await this.all(`SELECT partition, name FROM sync_backfill_checkpoints
547
+ WHERE schema_version=? AND state<>'activated'`, [runningSchemaVersion]);
781
548
  return {
782
549
  storedSchemaVersion: marker?.schema_version ?? 0,
783
- logEpoch: epoch?.log_epoch,
784
- pending: pending.map((row) => ({
785
- partition: row.partition,
786
- name: row.name,
787
- })),
550
+ logEpoch: await this.getPartitionLogEpoch(partition),
551
+ pending,
788
552
  };
789
553
  }
790
554
  async readCheckpoints(partition) {
@@ -822,672 +586,84 @@ END`);
822
586
  // One transaction: the checkpoint becomes visible and the fence that
823
587
  // protects it is raised together. The fence is raised at declaration, not
824
588
  // at activation, so old writers are rejected for the whole backfill.
825
- return this.#serializeWrite(() => {
826
- this.db.exec('BEGIN IMMEDIATE');
827
- try {
828
- this.#installCheckpoint(partition, name, schemaVersion, nowMs);
829
- const row = this.db
830
- .query(`SELECT partition, name, schema_version, state, watermark,
831
- owner_epoch, observed_rows, updated_at_ms
832
- FROM sync_backfill_checkpoints WHERE partition=? AND name=?`)
833
- .get(partition, name);
834
- if (row === null)
835
- throw new StorageQueryError('sync.storage.checkpoint_not_declared');
836
- this.db.exec('COMMIT');
837
- return toStoredCheckpoint(row);
838
- }
839
- catch (error) {
840
- rollbackAfterError(() => {
841
- this.db.exec('ROLLBACK');
842
- }, error);
843
- }
844
- });
845
- }
846
- async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
847
- return this.#serializeWrite(() => {
848
- // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
849
- // lock a push takes. Nothing may observe activation without the fence.
850
- this.db.exec('BEGIN IMMEDIATE');
851
- try {
852
- const fence = this.db
853
- .query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=?')
854
- .get(partition);
855
- const checkpoint = this.db
856
- .query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?')
857
- .get(partition, name);
858
- if (fence === null ||
859
- checkpoint === null ||
860
- fence.required_writer_version < checkpoint.schema_version) {
861
- // The barrier is not installed. Activating would certify a state old
862
- // writers can still decay; refuse instead of silently proceeding.
863
- throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
864
- }
865
- const coverage = this.#hasSourceChangesAbove(partition, sources, watermark);
866
- if (coverage !== 'clean') {
867
- this.db.exec('ROLLBACK');
868
- return coverage === 'changed' ? 'stale' : 'unverifiable';
869
- }
870
- const updated = this.db
871
- .query(`UPDATE sync_backfill_checkpoints
872
- SET state='activated', watermark=?, updated_at_ms=?
873
- WHERE partition=? AND name=? AND owner_epoch=?
874
- AND state<>'activated'`)
875
- .run(watermark, nowMs, partition, name, ownerEpoch);
876
- this.db.exec('COMMIT');
877
- return Number(updated.changes) === 1 ? 'activated' : 'stale';
878
- }
879
- catch (error) {
880
- rollbackAfterError(() => {
881
- this.db.exec('ROLLBACK');
882
- }, error);
883
- }
884
- });
885
- }
886
- async claimCheckpoint(partition, name, schemaVersion, nowMs) {
887
- return this.#serializeWrite(() => {
888
- const claimed = this.db
889
- .query(`UPDATE sync_backfill_checkpoints
890
- SET owner_epoch=owner_epoch+1,
891
- state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
892
- schema_version=?, updated_at_ms=?
893
- WHERE partition=? AND name=? AND state<>'activated'
894
- RETURNING partition, name, schema_version, state, watermark,
895
- owner_epoch, observed_rows, updated_at_ms`)
896
- .get(schemaVersion, nowMs, partition, name);
897
- if (claimed === null) {
898
- throw new StorageQueryError('sync.storage.checkpoint_not_declared');
899
- }
900
- return toStoredCheckpoint(claimed);
901
- });
902
- }
903
- async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
904
- return this.#serializeWrite(() => {
905
- const result = this.db
906
- .query(`UPDATE sync_backfill_checkpoints
907
- SET watermark=?, observed_rows=?, updated_at_ms=?
908
- WHERE partition=? AND name=? AND owner_epoch=?`)
909
- .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
910
- return Number(result.changes) === 1;
911
- });
912
- }
913
- async sourceCoverageSeq(partition, tables) {
914
- if (tables.length === 0)
915
- return 0;
916
- const row = this.db
917
- .query(`SELECT max(commit_seq) AS seq FROM sync_changes
918
- WHERE partition=? AND tbl IN (${placeholders(tables.length)})`)
919
- .get(partition, ...tables);
920
- return row?.seq ?? 0;
921
- }
922
- #hasSourceChangesAbove(partition, tables, seq) {
923
- // Read the horizon before the window scan: a horizon past `seq` means the
924
- // history that would answer the question is gone, so an empty scan proves
925
- // nothing and must not be reported as `clean`.
926
- const horizon = this.db
927
- .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
928
- .get(partition)?.horizon_seq ?? 0;
929
- if (tables.length === 0)
930
- return 'clean';
931
- const hit = this.db
932
- .query(`SELECT 1 AS hit FROM sync_changes
933
- WHERE partition=? AND tbl IN (${placeholders(tables.length)})
934
- AND commit_seq>? LIMIT 1`)
935
- .get(partition, ...tables, seq);
936
- if (hit !== null && hit !== undefined)
937
- return 'changed';
938
- return horizon > seq ? 'unverifiable' : 'clean';
939
- }
940
- async hasSourceChangesAbove(partition, tables, seq) {
941
- return this.#hasSourceChangesAbove(partition, tables, seq);
942
- }
943
- async getRow(partition, table, rowId) {
944
- const record = this.db
945
- .query(selectRowSql(this.table(table), 'sqlite'))
946
- .get(partition, rowId);
947
- return record === null ? undefined : toStoredRow(record);
948
- }
949
- async getPushResult(partition, clientId, clientCommitId) {
950
- const record = this.db
951
- .query('SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?')
952
- .get(partition, clientId, clientCommitId);
953
- if (record === null)
954
- return undefined;
589
+ this.db.exec('BEGIN IMMEDIATE');
955
590
  try {
956
- return deserializePushResult(record.result);
957
- }
958
- catch {
959
- throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
960
- }
961
- }
962
- async claimReactions(partition, query) {
963
- if (query.types.length === 0 || query.limit <= 0)
964
- return [];
965
- return this.#serializeWrite(() => {
966
- const typeParams = query.types.map(() => '?').join(',');
967
- const records = this.db
968
- .query(`UPDATE sync_reactions
969
- SET status='leased', attempts=attempts+1,
970
- lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
971
- WHERE (partition, idempotency_key) IN (
972
- SELECT partition, idempotency_key
973
- FROM sync_reactions
974
- WHERE partition=? AND type IN (${typeParams})
975
- AND ((status='pending' AND available_at_ms<=?)
976
- OR (status='leased' AND lease_expires_at_ms<=?))
977
- ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
978
- ELSE available_at_ms END,
979
- created_at_ms, idempotency_key
980
- LIMIT ?
981
- )
982
- RETURNING *`)
983
- .all(query.leaseOwner, Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs), partition, ...query.types, query.nowMs, query.nowMs, query.limit);
984
- return records
985
- .map(toStoredReaction)
986
- .sort((a, b) => a.createdAtMs - b.createdAtMs ||
987
- a.idempotencyKey.localeCompare(b.idempotencyKey));
988
- });
989
- }
990
- async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
991
- return this.#serializeWrite(() => {
992
- const result = this.db
993
- .query(`UPDATE sync_reactions
994
- SET status='completed', completed_at_ms=?,
995
- lease_owner=NULL, lease_expires_at_ms=NULL
996
- WHERE partition=? AND idempotency_key=?
997
- AND status='leased' AND lease_owner=?`)
998
- .run(completedAtMs, partition, idempotencyKey, leaseOwner);
999
- return Number(result.changes) === 1;
1000
- });
1001
- }
1002
- async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
1003
- return this.#serializeWrite(() => {
1004
- const result = this.db
1005
- .query(`UPDATE sync_reactions SET lease_expires_at_ms=?
1006
- WHERE partition=? AND idempotency_key=?
1007
- AND status='leased' AND lease_owner=?`)
1008
- .run(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner);
1009
- return Number(result.changes) === 1;
1010
- });
1011
- }
1012
- async failReaction(partition, idempotencyKey, update) {
1013
- const retry = update.retryAtMs !== undefined;
1014
- return this.#serializeWrite(() => {
1015
- const result = this.db
1016
- .query(`UPDATE sync_reactions
1017
- SET status=?, available_at_ms=?, last_failure=?,
1018
- lease_owner=NULL, lease_expires_at_ms=NULL
1019
- WHERE partition=? AND idempotency_key=?
1020
- AND status='leased' AND lease_owner=?`)
1021
- .run(retry ? 'pending' : 'dead-letter', update.retryAtMs ?? update.failure.atMs, JSON.stringify(update.failure), partition, idempotencyKey, update.leaseOwner);
1022
- return Number(result.changes) === 1;
1023
- });
1024
- }
1025
- async retryReaction(partition, idempotencyKey, nowMs) {
1026
- return this.#serializeWrite(() => {
1027
- const result = this.db
1028
- .query(`UPDATE sync_reactions
1029
- SET status='pending', attempts=0, available_at_ms=?,
1030
- last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
1031
- completed_at_ms=NULL
1032
- WHERE partition=? AND idempotency_key=? AND status='dead-letter'`)
1033
- .run(nowMs, partition, idempotencyKey);
1034
- return Number(result.changes) === 1;
1035
- });
1036
- }
1037
- async getReaction(partition, idempotencyKey) {
1038
- const record = this.db
1039
- .query('SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?')
1040
- .get(partition, idempotencyKey);
1041
- return record === null ? undefined : toStoredReaction(record);
1042
- }
1043
- async listReactions(partition, query) {
1044
- const where = ['partition=?'];
1045
- const params = [partition];
1046
- if (query.statuses !== undefined && query.statuses.length > 0) {
1047
- where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
1048
- params.push(...query.statuses);
1049
- }
1050
- if (query.types !== undefined && query.types.length > 0) {
1051
- where.push(`type IN (${query.types.map(() => '?').join(',')})`);
1052
- params.push(...query.types);
1053
- }
1054
- params.push(query.limit);
1055
- const records = this.db
1056
- .query(`SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
1057
- ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`)
1058
- .all(...params);
1059
- return records.map(toStoredReaction);
1060
- }
1061
- async pruneReactions(partition, query) {
1062
- if (query.limit <= 0)
1063
- return { completed: 0, deadLetter: 0 };
1064
- return this.#serializeWrite(() => {
1065
- const records = this.db
1066
- .query(`DELETE FROM sync_reactions
1067
- WHERE partition=? AND idempotency_key IN (
1068
- SELECT idempotency_key FROM sync_reactions
1069
- WHERE partition=?
1070
- AND ((status='completed' AND completed_at_ms IS NOT NULL
1071
- AND completed_at_ms<?)
1072
- OR (status='dead-letter' AND available_at_ms<?))
1073
- ORDER BY CASE WHEN status='completed' THEN completed_at_ms
1074
- ELSE available_at_ms END,
1075
- idempotency_key
1076
- LIMIT ?
1077
- )
1078
- AND ((status='completed' AND completed_at_ms IS NOT NULL
1079
- AND completed_at_ms<?)
1080
- OR (status='dead-letter' AND available_at_ms<?))
1081
- RETURNING status`)
1082
- .all(partition, partition, query.completedBeforeMs, query.deadLetterBeforeMs, query.limit, query.completedBeforeMs, query.deadLetterBeforeMs);
1083
- return {
1084
- completed: records.filter((record) => record.status === 'completed')
1085
- .length,
1086
- deadLetter: records.filter((record) => record.status === 'dead-letter')
1087
- .length,
1088
- };
1089
- });
1090
- }
1091
- async latestScopedChangeSeq(partition, query) {
1092
- const firstVariable = Object.keys(query.scopeFilter).sort()[0];
1093
- const values = firstVariable === undefined
1094
- ? []
1095
- : (query.scopeFilter[firstVariable] ?? []);
1096
- if (firstVariable === undefined || values.length === 0)
1097
- return 0;
1098
- const row = this.db
1099
- .query(LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL)
1100
- .get(partition, query.table, firstVariable, JSON.stringify(values));
1101
- return row?.seq ?? 0;
1102
- }
1103
- async readCommitWindow(partition, query) {
1104
- const variables = Object.keys(query.scopeFilter).sort();
1105
- const firstVariable = variables[0];
1106
- if (firstVariable === undefined)
1107
- return [];
1108
- const firstValues = query.scopeFilter[firstVariable] ?? [];
1109
- if (firstValues.length === 0)
1110
- return [];
1111
- // Candidates via the inverted index (one variable) LEFT JOINed to the
1112
- // commit meta + the table's changes — one statement per page, never two
1113
- // per candidate (see `commitWindowPageSql`). Exact multi-variable
1114
- // verification against the stored scope map in `collectCommitWindowPage`.
1115
- const sql = commitWindowPageSql(firstValues.length, 'sqlite');
1116
- const commits = [];
1117
- let deliveredChanges = 0;
1118
- let afterSeq = query.afterSeq;
1119
- const batchSize = Math.max(64, query.limitChanges);
1120
- while (deliveredChanges < query.limitChanges) {
1121
- const records = this.db
1122
- .query(sql)
1123
- .all(partition, query.table, firstVariable, ...firstValues, afterSeq, query.throughSeq, batchSize, partition, partition, query.table);
1124
- if (records.length === 0)
1125
- break;
1126
- const page = collectCommitWindowPage(records, query.scopeFilter, query.limitChanges - deliveredChanges);
1127
- commits.push(...page.commits);
1128
- deliveredChanges += page.delivered;
1129
- afterSeq = page.lastSeq;
1130
- if (page.candidateCount < batchSize)
1131
- break;
1132
- }
1133
- return commits;
1134
- }
1135
- async scanRows(partition, query) {
1136
- const firstVariable = assertScopeIndexedScan(query);
1137
- const firstValues = query.scopeFilter[firstVariable] ?? [];
1138
- if (firstValues.length === 0)
1139
- return [];
1140
- // Candidates via the inverted index LEFT JOINed to the row table — one
1141
- // statement per page, never one per row (see `scanRowPageSql`). Exact
1142
- // multi-variable verification against the stored scope map below.
1143
- const sql = scanRowPageSql(this.table(query.table), firstValues.length, 'sqlite');
1144
- const rows = [];
1145
- let afterRowId = query.afterRowId ?? '';
1146
- const batchSize = Math.max(64, query.limit);
1147
- while (rows.length < query.limit) {
1148
- const records = this.db
1149
- .query(sql)
1150
- .all(partition, query.table, firstVariable, ...firstValues, afterRowId, batchSize, partition);
1151
- if (records.length === 0)
1152
- break;
1153
- for (const record of records) {
1154
- afterRowId = record.row_id;
1155
- // NULL payload: an index candidate whose row vanished — it still
1156
- // advances the keyset cursor (LEFT JOIN contract) but yields no row.
1157
- if (record.payload === null)
1158
- continue;
1159
- const stored = toStoredRow(record);
1160
- if (!matchesEffective(stored.scopes, query.scopeFilter))
1161
- continue;
1162
- rows.push(stored);
1163
- if (rows.length >= query.limit)
1164
- break;
1165
- }
1166
- if (records.length < batchSize)
1167
- break;
1168
- }
1169
- return rows;
1170
- }
1171
- async scanRowsByIndex(partition, query) {
1172
- const table = this.table(query.table);
1173
- const index = resolveIndexRowScan(table, query);
1174
- const statement = indexRowPageStatement(table, index, query.values, partition, query.afterRowId, query.limit, 'sqlite');
1175
- const params = statement.params;
1176
- const records = this.db
1177
- .query(statement.sql)
1178
- .all(...params);
1179
- return records.map(toStoredRow);
1180
- }
1181
- async getClientRecord(partition, clientId) {
1182
- const record = this.db
1183
- .query('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=?')
1184
- .get(partition, clientId);
1185
- if (record === null)
1186
- return undefined;
1187
- return {
1188
- clientId: record.client_id,
1189
- actorId: record.actor_id,
1190
- wireVersion: record.wire_version,
1191
- cursor: record.cursor,
1192
- updatedAtMs: record.updated_at_ms,
1193
- subscriptions: JSON.parse(record.subscriptions),
1194
- ...clientRoundState(record.last_round_at_ms, record.last_error_code, record.consecutive_failures),
1195
- };
1196
- }
1197
- async putClientRecord(partition, record, options) {
1198
- this.db
1199
- .query(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
1200
- ON CONFLICT(partition, client_id) DO UPDATE SET
1201
- actor_id=excluded.actor_id,
1202
- wire_version=excluded.wire_version,
1203
- cursor=excluded.cursor,
1204
- subscriptions=excluded.subscriptions,
1205
- updated_at_ms=excluded.updated_at_ms,
1206
- last_round_at_ms=excluded.last_round_at_ms${options?.keepRoundOutcome === true
1207
- ? ''
1208
- : `,
1209
- last_error_code=NULL,
1210
- consecutive_failures=0`}`)
1211
- .run(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs, record.updatedAtMs);
1212
- }
1213
- async recordClientRoundFailure(partition, clientId, actorId, errorCode, atMs) {
1214
- this.db
1215
- .query(`UPDATE sync_clients
1216
- SET last_round_at_ms=?, last_error_code=?,
1217
- consecutive_failures=consecutive_failures+1
1218
- WHERE partition=? AND client_id=? AND actor_id=?`)
1219
- .run(atMs, errorCode, partition, clientId, actorId);
1220
- }
1221
- async advanceClientCursor(partition, clientId, actorId, logEpoch, cursor, updatedAtMs) {
1222
- this.db
1223
- .query(`UPDATE sync_clients
1224
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
1225
- WHERE partition=? AND client_id=? AND actor_id=?
1226
- AND EXISTS (SELECT 1 FROM sync_partition_registry
1227
- WHERE partition=sync_clients.partition AND log_epoch=?)`)
1228
- .run(cursor, updatedAtMs, partition, clientId, actorId, logEpoch);
1229
- }
1230
- async updateClientCursor(partition, clientId, cursor, updatedAtMs) {
1231
- this.db
1232
- .query(`UPDATE sync_clients
1233
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
1234
- WHERE partition=? AND client_id=?`)
1235
- .run(cursor, updatedAtMs, partition, clientId);
1236
- }
1237
- async getActiveClientCursorFloor(partition, cutoffMs) {
1238
- const row = this.db
1239
- .query('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?')
1240
- .get(partition, cutoffMs);
1241
- return row.cursor;
1242
- }
1243
- async listClientCursors(partition) {
1244
- const records = this.db
1245
- .query('SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?')
1246
- .all(partition);
1247
- return records.map((r) => ({
1248
- clientId: r.client_id,
1249
- cursor: r.cursor,
1250
- updatedAtMs: r.updated_at_ms,
1251
- }));
1252
- }
1253
- async listRowsReferencingBlob(partition, blobId) {
1254
- // Candidate rows via the by-blob index (§5.9.4/§5.9.5); each row's
1255
- // stored scopes come from sync_rows for the §3.4 authorization test.
1256
- const refs = this.db
1257
- .query('SELECT tbl, row_id FROM sync_blob_refs WHERE partition=? AND blob_id=?')
1258
- .all(partition, blobId);
1259
- const out = [];
1260
- for (const ref of refs) {
1261
- const compiled = this.#tables?.get(ref.tbl);
1262
- if (compiled === undefined)
1263
- continue; // table no longer in the schema
591
+ this.#installCheckpoint(partition, name, schemaVersion, nowMs);
1264
592
  const row = this.db
1265
- .query(selectRowScopesSql(compiled, 'sqlite'))
1266
- .get(partition, ref.row_id);
593
+ .query(`SELECT partition, name, schema_version, state, watermark,
594
+ owner_epoch, observed_rows, updated_at_ms
595
+ FROM sync_backfill_checkpoints WHERE partition=? AND name=?`)
596
+ .get(partition, name);
1267
597
  if (row === null)
1268
- continue;
1269
- out.push({
1270
- table: ref.tbl,
1271
- rowId: ref.row_id,
1272
- scopes: JSON.parse(row.scopes),
1273
- });
598
+ throw new StorageQueryError('sync.storage.checkpoint_not_declared');
599
+ this.db.exec('COMMIT');
600
+ return toStoredCheckpoint(row);
1274
601
  }
1275
- return out;
1276
- }
1277
- async listReferencedBlobIds(partition) {
1278
- const rows = this.db
1279
- .query('SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=?')
1280
- .all(partition);
1281
- return rows.map((r) => r.blob_id);
1282
- }
1283
- async listScopeValueRows(partition, query) {
1284
- return this.db
1285
- .query(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
1286
- .all(partition, query.table, query.variable, query.value, query.limit)
1287
- .map((row) => row.row_id);
1288
- }
1289
- async eraseScopeValueHistory(partition, query) {
1290
- const params = eraseScopeValueHistoryParams(partition, query);
1291
- return this.#serializeWrite(() => {
1292
- this.db.exec('BEGIN IMMEDIATE');
1293
- try {
1294
- let removed = 0;
1295
- for (const sql of ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL) {
1296
- removed += this.db.query(sql).all(...params).length;
1297
- }
1298
- this.db.exec('COMMIT');
1299
- return removed;
1300
- }
1301
- catch (error) {
1302
- rollbackAfterError(() => {
1303
- this.db.exec('ROLLBACK');
1304
- }, error);
1305
- }
1306
- });
1307
- }
1308
- // -- admin/console read surface --------------------------------------------
1309
- async listClientRecords(partition) {
1310
- const records = this.db
1311
- .query('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')
1312
- .all(partition);
1313
- return records.map((record) => ({
1314
- clientId: record.client_id,
1315
- actorId: record.actor_id,
1316
- wireVersion: record.wire_version,
1317
- cursor: record.cursor,
1318
- updatedAtMs: record.updated_at_ms,
1319
- subscriptions: JSON.parse(record.subscriptions),
1320
- ...clientRoundState(record.last_round_at_ms, record.last_error_code, record.consecutive_failures),
1321
- }));
1322
- }
1323
- async listCommitMetadata(partition, query) {
1324
- // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
1325
- // ended by `beforeSeq` (exclusive upper bound) when paging older. An
1326
- // omitted bound is the largest safe commitSeq, so one statement serves
1327
- // both the bounded and unbounded read.
1328
- const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
1329
- const rows = query.table
1330
- ? this.db
1331
- .query(`SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
1332
- FROM sync_commits c
1333
- WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
1334
- AND EXISTS (SELECT 1 FROM sync_changes ch
1335
- WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
1336
- ORDER BY c.commit_seq DESC LIMIT ?`)
1337
- .all(partition, query.afterSeq, beforeSeq, query.table, query.limit)
1338
- : this.db
1339
- .query(`SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
1340
- FROM sync_commits
1341
- WHERE partition=? AND commit_seq>? AND commit_seq<?
1342
- ORDER BY commit_seq DESC LIMIT ?`)
1343
- .all(partition, query.afterSeq, beforeSeq, query.limit);
1344
- // `changeSample`: one extra statement for the whole page — the first
1345
- // `sample` changes (change-index order) of every listed commit.
1346
- const sampleCount = query.changeSample !== undefined &&
1347
- Number.isInteger(query.changeSample) &&
1348
- query.changeSample > 0
1349
- ? query.changeSample
1350
- : 0;
1351
- const samples = new Map();
1352
- if (sampleCount > 0 && rows.length > 0) {
1353
- const seqs = rows.map((row) => row.commit_seq);
1354
- const records = this.db
1355
- .query(`SELECT commit_seq, tbl, row_id, op FROM sync_changes
1356
- WHERE partition=? AND commit_seq IN (${placeholders(seqs.length)}) AND idx<?
1357
- ORDER BY commit_seq, idx`)
1358
- .all(partition, ...seqs, sampleCount);
1359
- for (const record of records) {
1360
- const sample = samples.get(record.commit_seq) ?? [];
1361
- sample.push({
1362
- table: record.tbl,
1363
- rowId: record.row_id,
1364
- op: record.op === 1 ? 'upsert' : 'delete',
1365
- });
1366
- samples.set(record.commit_seq, sample);
1367
- }
602
+ catch (error) {
603
+ rollbackAfterError(() => {
604
+ this.db.exec('ROLLBACK');
605
+ }, error);
1368
606
  }
1369
- return rows.map((row) => {
1370
- const changes = this.db
1371
- .query('SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl')
1372
- .all(partition, row.commit_seq);
1373
- return {
1374
- commitSeq: row.commit_seq,
1375
- clientId: row.client_id,
1376
- clientCommitId: row.client_commit_id,
1377
- actorId: row.actor_id,
1378
- createdAtMs: row.created_at_ms,
1379
- changeCount: changes.reduce((sum, c) => sum + c.n, 0),
1380
- tables: changes.map((c) => c.tbl),
1381
- ...(sampleCount > 0
1382
- ? { sample: samples.get(row.commit_seq) ?? [] }
1383
- : {}),
1384
- };
1385
- });
1386
607
  }
1387
- async getCommit(partition, commitSeq) {
1388
- const meta = this.db
1389
- .query('SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?')
1390
- .get(partition, commitSeq);
1391
- if (meta === null)
1392
- return undefined;
1393
- const changes = this.db
1394
- .query('SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx')
1395
- .all(partition, commitSeq)
1396
- .map(toStoredChange);
1397
- return {
1398
- commitSeq,
1399
- clientId: meta.client_id,
1400
- clientCommitId: meta.client_commit_id,
1401
- actorId: meta.actor_id,
1402
- createdAtMs: meta.created_at_ms,
1403
- changeCount: changes.length,
1404
- tables: [...new Set(changes.map((change) => change.table))].sort(),
1405
- changes,
1406
- };
1407
- }
1408
- async listRowChanges(partition, query) {
1409
- // Retained-log read for one row: no dedicated index (the write path pays
1410
- // nothing for it), bounded by retention (§4.6).
1411
- return this.db
1412
- .query(`SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
1413
- FROM sync_changes ch
1414
- JOIN sync_commits c
1415
- ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
1416
- WHERE ch.partition=? AND ch.tbl=? AND ch.row_id=?
1417
- ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`)
1418
- .all(partition, query.table, query.rowId, query.limit)
1419
- .map((row) => ({
1420
- commitSeq: row.commit_seq,
1421
- op: row.op === 1 ? 'upsert' : 'delete',
1422
- ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
1423
- actorId: row.actor_id,
1424
- clientId: row.client_id,
1425
- createdAtMs: row.created_at_ms,
1426
- }));
1427
- }
1428
- async listRows(partition, query) {
1429
- // Keyset page over the row table's (partition, rowId) primary key: an
1430
- // index range read, no scope filter, no per-row lookup.
1431
- return this.db
1432
- .query(`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
1433
- FROM ${quoteIdent(this.table(query.table).name)}
1434
- WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
1435
- ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`)
1436
- .all(partition, query.afterRowId ?? '', query.limit)
1437
- .map(toStoredRow);
1438
- }
1439
- async countRows(partition, table) {
1440
- const record = this.db
1441
- .query(`SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`)
1442
- .get(partition);
1443
- return record?.n ?? 0;
1444
- }
1445
- async listPushResults(partition, clientCommitId) {
1446
- // Retained outcomes for one clientCommitId: no dedicated index, ordered
1447
- // by client so the read is deterministic.
1448
- return this.db
1449
- .query('SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id')
1450
- .all(partition, clientCommitId)
1451
- .map((record) => {
1452
- try {
1453
- return {
1454
- clientId: record.client_id,
1455
- result: deserializePushResult(record.result),
1456
- };
608
+ async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
609
+ // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
610
+ // lock a push takes. Nothing may observe activation without the fence.
611
+ this.db.exec('BEGIN IMMEDIATE');
612
+ try {
613
+ const fence = this.db
614
+ .query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=?')
615
+ .get(partition);
616
+ const checkpoint = this.db
617
+ .query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?')
618
+ .get(partition, name);
619
+ if (fence === null ||
620
+ checkpoint === null ||
621
+ fence.required_writer_version < checkpoint.schema_version) {
622
+ // The barrier is not installed. Activating would certify a state old
623
+ // writers can still decay; refuse instead of silently proceeding.
624
+ throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
1457
625
  }
1458
- catch {
1459
- throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
626
+ const coverage = await this.hasSourceChangesAbove(partition, sources, watermark);
627
+ if (coverage !== 'clean') {
628
+ this.db.exec('ROLLBACK');
629
+ return coverage === 'changed' ? 'stale' : 'unverifiable';
1460
630
  }
1461
- });
1462
- }
1463
- async scopeActivity(partition, query) {
1464
- // Candidate commits via the change-scope index (§3.1) — never a scan.
1465
- const rows = this.db
1466
- .query(`SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
1467
- WHERE partition=? AND var=? AND value=?
1468
- ORDER BY commit_seq DESC LIMIT ?`)
1469
- .all(partition, query.variable, query.value, query.limit);
1470
- const out = [];
1471
- for (const row of rows) {
1472
- const meta = this.db
1473
- .query('SELECT actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?')
1474
- .get(partition, row.commit_seq);
1475
- if (meta === null)
1476
- continue;
1477
- const count = this.db
1478
- .query('SELECT count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? AND tbl=?')
1479
- .get(partition, row.commit_seq, row.tbl);
1480
- out.push({
1481
- commitSeq: row.commit_seq,
1482
- table: row.tbl,
1483
- createdAtMs: meta.created_at_ms,
1484
- actorId: meta.actor_id,
1485
- changeCount: count?.n ?? 0,
1486
- });
631
+ const updated = this.db
632
+ .query(`UPDATE sync_backfill_checkpoints
633
+ SET state='activated', watermark=?, updated_at_ms=?
634
+ WHERE partition=? AND name=? AND owner_epoch=?
635
+ AND state<>'activated'`)
636
+ .run(watermark, nowMs, partition, name, ownerEpoch);
637
+ this.db.exec('COMMIT');
638
+ return Number(updated.changes) === 1 ? 'activated' : 'stale';
639
+ }
640
+ catch (error) {
641
+ rollbackAfterError(() => {
642
+ this.db.exec('ROLLBACK');
643
+ }, error);
1487
644
  }
1488
- return out;
1489
645
  }
1490
- async listPartitions() {
1491
- return (await this.listPartitionRegistry()).map((entry) => entry.partition);
646
+ async claimCheckpoint(partition, name, schemaVersion, nowMs) {
647
+ const claimed = this.db
648
+ .query(`UPDATE sync_backfill_checkpoints
649
+ SET owner_epoch=owner_epoch+1,
650
+ state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
651
+ schema_version=?, updated_at_ms=?
652
+ WHERE partition=? AND name=? AND state<>'activated'
653
+ RETURNING partition, name, schema_version, state, watermark,
654
+ owner_epoch, observed_rows, updated_at_ms`)
655
+ .get(schemaVersion, nowMs, partition, name);
656
+ if (claimed === null) {
657
+ throw new StorageQueryError('sync.storage.checkpoint_not_declared');
658
+ }
659
+ return toStoredCheckpoint(claimed);
660
+ }
661
+ async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
662
+ const result = this.db
663
+ .query(`UPDATE sync_backfill_checkpoints
664
+ SET watermark=?, observed_rows=?, updated_at_ms=?
665
+ WHERE partition=? AND name=? AND owner_epoch=?`)
666
+ .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
667
+ return Number(result.changes) === 1;
1492
668
  }
1493
669
  }