@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
package/src/d1-storage.ts CHANGED
@@ -1,21 +1,12 @@
1
- import { validateCommitPruneQuery } from './prune';
2
- import { StorageQueryError } from './storage-errors';
3
- import type { CommitPruneQuery, CommitPruneResult } from './storage';
4
- import {
5
- clientRoundState,
6
- PARTITION_TOUCH_INTERVAL_MS,
7
- rowsLiveAfterDelete,
8
- } from './storage';
9
1
  /**
10
2
  * Cloudflare D1 server storage for Workers deployments.
11
3
  *
12
4
  * D1 *is* SQLite exposed over an async, statement-at-a-time API
13
5
  * (`prepare(sql).bind(...).all()` / `.first()` / `.run()`, plus `batch([…])`
14
- * for atomic multi-statement writes). So this storage shares the schema and
15
- * value codecs with `SqliteServerStorage` via `sqlite-dialect.ts` — same
16
- * DDL, same `?` placeholders, same JSON-scope / base64-push-result
17
- * serialization — and differs only in the execution shape (async, no
18
- * interactive transaction).
6
+ * for atomic multi-statement writes). The statements it shares with
7
+ * `SqliteServerStorage` live in `SqliteFamilyStorage` (`sqlite-dialect.ts`);
8
+ * this class adds the execution seam, the published-schema guard, the
9
+ * resumable schema migration and the buffered transaction.
19
10
  *
20
11
  * ## Transaction model (the one real divergence)
21
12
  *
@@ -47,21 +38,12 @@ import {
47
38
  * This mirrors PostgreSQL's per-partition row lock, achieved by placement
48
39
  * rather than a lock D1 does not expose.
49
40
  */
50
- import { decodeRow, type RowValue, type ScopeMap } from '@syncular/core';
51
- import {
52
- bindAuthoritativePartition,
53
- type BoundAuthoritativeQuery,
54
- prepareAuthoritativeQuery,
55
- } from './authoritative-query';
56
- import { syncError } from './errors';
41
+ import { decodeRow, type RowValue } from '@syncular/core';
42
+ import type { BoundAuthoritativeQuery } from './authoritative-query';
57
43
  import {
58
44
  assertAppendOnlyMigration,
59
45
  assertPhysicalColumns,
60
46
  assertStoredLayouts,
61
- commitWindowPageSql,
62
- LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
63
- deleteRowSql,
64
- deleteSqliteRowScopesSql,
65
47
  dropTableDdl,
66
48
  indexRowPageStatement,
67
49
  layoutsOf,
@@ -73,12 +55,6 @@ import {
73
55
  rewriteRowSql,
74
56
  rewriteValues,
75
57
  SCHEMA_META_DDL_SQLITE,
76
- SYNC_COLUMN_VERSIONS_COLUMN,
77
- SYNC_PARTITION_COLUMN,
78
- SYNC_PAYLOAD_COLUMN,
79
- SYNC_ROW_ID_COLUMN,
80
- SYNC_SCOPES_COLUMN,
81
- SYNC_VERSION_COLUMN,
82
58
  type StoredColumnLayout,
83
59
  scanRowPageSql,
84
60
  schemaDdl,
@@ -86,77 +62,53 @@ import {
86
62
  SQLITE_TABLE_INDEXES_SQL,
87
63
  type SqliteTableIndexRow,
88
64
  sqliteIndexSignatures,
89
- selectRowScopesSql,
90
65
  selectRowSql,
66
+ selectRowsSql,
91
67
  selectRowsForRewriteSql,
92
68
  tableColumnNames,
93
69
  toSqlValue,
94
- upsertSql,
95
- upsertValues,
96
70
  } from './relational-rows';
97
71
  import type { CompiledSchema, CompiledTable } from './schema';
98
72
  import { matchesEffective } from './scopes';
99
73
  import {
100
74
  asUint8Array,
101
- collectCommitWindowPage,
102
75
  deserializePushResult,
103
76
  placeholders,
104
- ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL,
105
- eraseScopeValueHistoryParams,
106
- LIST_SCOPE_VALUE_ROWS_SQLITE_SQL,
107
- type SqliteChangeRecord,
108
- type SqliteCommitWindowRecord,
109
77
  type SqliteRowRecord,
110
- serializePushResult,
78
+ type SqliteStatementSpec,
79
+ SqliteFamilyStorage,
80
+ SqliteFamilyTransaction,
81
+ SQLITE_ADDED_COLUMNS,
82
+ type SqliteTombstoneRecord,
111
83
  sqliteDdlStatements,
112
- SYNC_CLIENT_ROUND_COLUMNS,
113
- toStoredChange,
114
84
  toStoredRow,
85
+ toTombstone,
115
86
  } from './sqlite-dialect';
87
+ import type { SqliteValue } from './sqlite-driver';
116
88
  import type {
117
89
  AuthoritativeQueryRequest,
118
90
  AuthoritativeQueryResult,
119
91
  CheckpointDeclaration,
120
- ClientCursorInfo,
121
- ClientPushResult,
122
- ClientRecord,
123
- ClientRecordWriteOptions,
124
- ClientSubscription,
125
- CommitChangeSummary,
126
- CommitDetail,
127
- CommitMetadata,
128
- CommitMetadataQuery,
129
- CommitWindowQuery,
130
- DurableJsonValue,
92
+ CommitPruneQuery,
93
+ CommitPruneResult,
131
94
  IndexRowScanQuery,
132
95
  NewCommit,
133
- NewReaction,
134
96
  PreparedPushApply,
135
- PartitionRegistryEntry,
136
- PrunedReactionCounts,
137
- ReactionClaimQuery,
138
- ReactionFailure,
139
- ReactionFailureUpdate,
140
- ReactionListQuery,
141
- ReactionPruneQuery,
142
- RowChangeRecord,
143
- RowChangesQuery,
144
- RowListQuery,
145
97
  RowScanQuery,
146
- ScopeActivityQuery,
147
- ScopeCommitActivity,
148
98
  ScopeValueHistoryQuery,
149
- ScopeValueQuery,
150
99
  ServerStorage,
151
100
  ServeGate,
152
101
  StorageTransaction,
153
- StoredCommit,
154
102
  StoredCheckpoint,
155
103
  StoredPushResult,
156
- StoredReaction,
157
104
  StoredRow,
105
+ Tombstone,
158
106
  } from './storage';
159
- import { isD1ConstraintError, StorageConstraintError } from './storage-errors';
107
+ import {
108
+ isD1ConstraintError,
109
+ StorageConstraintError,
110
+ StorageQueryError,
111
+ } from './storage-errors';
160
112
  import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
161
113
 
162
114
  // -- The subset of the D1 API this storage uses (structural typing) ---------
@@ -176,56 +128,17 @@ export interface D1Database {
176
128
  exec(query: string): Promise<unknown>;
177
129
  }
178
130
 
179
- /** A buffered write: the SQL text plus its bound parameters. */
180
- interface BufferedStatement {
181
- readonly sql: string;
182
- readonly params: readonly unknown[];
183
- }
184
-
185
- interface D1ReactionRecord {
186
- idempotency_key: string;
187
- type: string;
188
- version: number;
189
- payload: string;
190
- source_client_id: string;
191
- source_client_commit_id: string;
192
- source_commit_seq: number;
193
- created_at_ms: number;
194
- available_at_ms: number;
195
- status: StoredReaction['status'];
196
- attempts: number;
197
- max_attempts: number;
198
- lease_owner: string | null;
199
- lease_expires_at_ms: number | null;
200
- completed_at_ms: number | null;
201
- last_failure: string | null;
202
- }
203
-
204
- function toStoredReaction(record: D1ReactionRecord): StoredReaction {
205
- return {
206
- idempotencyKey: record.idempotency_key,
207
- type: record.type,
208
- version: record.version,
209
- payload: JSON.parse(record.payload) as DurableJsonValue,
210
- sourceClientId: record.source_client_id,
211
- sourceClientCommitId: record.source_client_commit_id,
212
- sourceCommitSeq: record.source_commit_seq,
213
- createdAtMs: record.created_at_ms,
214
- maxAttempts: record.max_attempts,
215
- status: record.status,
216
- attempts: record.attempts,
217
- availableAtMs: record.available_at_ms,
218
- ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
219
- ...(record.lease_expires_at_ms !== null
220
- ? { leaseExpiresAtMs: record.lease_expires_at_ms }
221
- : {}),
222
- ...(record.completed_at_ms !== null
223
- ? { completedAtMs: record.completed_at_ms }
224
- : {}),
225
- ...(record.last_failure !== null
226
- ? { lastFailure: JSON.parse(record.last_failure) as ReactionFailure }
227
- : {}),
228
- };
131
+ /** The rows of one `db.batch` result entry (`{ results }` per statement). */
132
+ function batchRows(result: unknown): unknown[] {
133
+ if (
134
+ typeof result !== 'object' ||
135
+ result === null ||
136
+ !('results' in result) ||
137
+ !Array.isArray(result.results)
138
+ ) {
139
+ throw new Error('D1 batch returned an invalid result');
140
+ }
141
+ return result.results;
229
142
  }
230
143
 
231
144
  function relationalValuesEqual(left: RowValue, right: RowValue): boolean {
@@ -250,34 +163,19 @@ async function queryAuthoritativeOn(
250
163
  .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
251
164
  .bind(partition),
252
165
  ]);
253
- const rowsResult = results[0];
254
- const cursorResult = results[1];
255
- if (
256
- typeof rowsResult !== 'object' ||
257
- rowsResult === null ||
258
- !('results' in rowsResult) ||
259
- !Array.isArray(rowsResult.results) ||
260
- typeof cursorResult !== 'object' ||
261
- cursorResult === null ||
262
- !('results' in cursorResult) ||
263
- !Array.isArray(cursorResult.results)
264
- ) {
265
- throw new Error('D1 registered query returned an invalid batch result');
266
- }
267
- const cursor = cursorResult.results[0];
268
- const maxCommitSeq =
269
- typeof cursor === 'object' &&
270
- cursor !== null &&
271
- 'max_commit_seq' in cursor &&
272
- typeof cursor.max_commit_seq === 'number'
273
- ? cursor.max_commit_seq
274
- : 0;
166
+ const cursor = batchRows(results[1])[0];
275
167
  return {
276
- rows: rowsResult.results.filter(
168
+ rows: batchRows(results[0]).filter(
277
169
  (row): row is Readonly<Record<string, unknown>> =>
278
170
  typeof row === 'object' && row !== null,
279
171
  ),
280
- maxCommitSeq,
172
+ maxCommitSeq:
173
+ typeof cursor === 'object' &&
174
+ cursor !== null &&
175
+ 'max_commit_seq' in cursor &&
176
+ typeof cursor.max_commit_seq === 'number'
177
+ ? cursor.max_commit_seq
178
+ : 0,
281
179
  };
282
180
  }
283
181
 
@@ -288,17 +186,18 @@ type PendingRow =
288
186
  readonly kind: 'deleted';
289
187
  };
290
188
 
291
- class D1Transaction implements StorageTransaction {
189
+ class D1Transaction
190
+ extends SqliteFamilyTransaction
191
+ implements StorageTransaction
192
+ {
292
193
  readonly #db: Pick<D1Database, 'prepare' | 'batch'>;
293
- readonly #partition: string;
294
194
  readonly #resolveTable: (name: string) => CompiledTable;
295
195
  /** Storage-owned relation rewrite, bound to this transaction's partition. */
296
196
  readonly #prepareQuery: (
297
197
  query: AuthoritativeQueryRequest,
298
198
  ) => BoundAuthoritativeQuery;
299
199
  readonly #pushApplySerialized: boolean;
300
- readonly #buffer: BufferedStatement[] = [];
301
- #open = true;
200
+ readonly #buffer: SqliteStatementSpec[] = [];
302
201
  /** Live snapshot of `max_commit_seq`, advanced within this transaction. */
303
202
  #maxCommitSeq: number | undefined;
304
203
  #pushApplyCheckpoint: number | undefined;
@@ -320,6 +219,19 @@ class D1Transaction implements StorageTransaction {
320
219
  */
321
220
  readonly #pending = new Map<string, PendingRow>();
322
221
  readonly #clearedTombstones = new Set<string>();
222
+ /**
223
+ * `prefetchRows` snapshot keyed `tbl\u0000rowId`: the stored row and its §5
224
+ * tombstone, `undefined` when absent. Nothing persists before `commit()`,
225
+ * so the snapshot stays exact; the `#pending` overlay still wins for rows
226
+ * this transaction wrote.
227
+ */
228
+ readonly #prefetched = new Map<
229
+ string,
230
+ {
231
+ readonly row: StoredRow | undefined;
232
+ readonly tombstone: Tombstone | undefined;
233
+ }
234
+ >();
323
235
 
324
236
  constructor(
325
237
  db: Pick<D1Database, 'prepare' | 'batch'>,
@@ -328,19 +240,31 @@ class D1Transaction implements StorageTransaction {
328
240
  prepareQuery: (query: AuthoritativeQueryRequest) => BoundAuthoritativeQuery,
329
241
  pushApplySerialized: boolean,
330
242
  ) {
243
+ super(partition);
331
244
  this.#db = db;
332
- this.#partition = partition;
333
245
  this.#resolveTable = resolveTable;
334
246
  this.#prepareQuery = prepareQuery;
335
247
  this.#pushApplySerialized = pushApplySerialized;
336
248
  }
337
249
 
338
- #assertOpen(): void {
339
- if (!this.#open) throw new Error('transaction already finished');
250
+ protected run(sql: string, params: readonly SqliteValue[]): void {
251
+ this.#buffer.push({ sql, params });
340
252
  }
341
253
 
342
- #buffer_(sql: string, params: readonly unknown[]): void {
343
- this.#buffer.push({ sql, params });
254
+ protected async all<T>(
255
+ sql: string,
256
+ params: readonly SqliteValue[],
257
+ ): Promise<T[]> {
258
+ return (
259
+ await this.#db
260
+ .prepare(sql)
261
+ .bind(...params)
262
+ .all<T>()
263
+ ).results;
264
+ }
265
+
266
+ protected table(name: string): CompiledTable {
267
+ return this.#resolveTable(name);
344
268
  }
345
269
 
346
270
  static #key(table: string, rowId: string): string {
@@ -348,88 +272,118 @@ class D1Transaction implements StorageTransaction {
348
272
  }
349
273
 
350
274
  async getRow(table: string, rowId: string): Promise<StoredRow | undefined> {
351
- this.#assertOpen();
275
+ this.assertOpen();
352
276
  const pending = this.#pending.get(D1Transaction.#key(table, rowId));
353
277
  if (pending !== undefined) {
354
278
  return pending.kind === 'row' ? pending.row : undefined;
355
279
  }
280
+ const prefetched = this.#prefetched.get(D1Transaction.#key(table, rowId));
281
+ if (prefetched !== undefined) return prefetched.row;
356
282
  const record = await this.#db
357
- .prepare(selectRowSql(this.#resolveTable(table), 'sqlite'))
358
- .bind(this.#partition, rowId)
283
+ .prepare(selectRowSql(this.table(table), 'sqlite'))
284
+ .bind(this.partition, rowId)
359
285
  .first<SqliteRowRecord>();
360
286
  return record === null ? undefined : toStoredRow(record);
361
287
  }
362
288
 
363
- async getRows(
364
- table: string,
365
- rowIds: readonly string[],
366
- ): Promise<ReadonlyMap<string, StoredRow>> {
367
- this.#assertOpen();
368
- // One lookup per id: `getRow` owns the buffered-write overlay, and a
369
- // mutable id list cannot share one bound statement across D1's limit.
370
- const rows = new Map<string, StoredRow>();
371
- for (const rowId of new Set(rowIds)) {
372
- const row = await this.getRow(table, rowId);
373
- if (row !== undefined) rows.set(rowId, row);
374
- }
375
- return rows;
376
- }
377
-
378
- async getTombstoneSeq(
289
+ override async getTombstone(
379
290
  table: string,
380
291
  rowId: string,
381
- ): Promise<number | undefined> {
382
- this.#assertOpen();
383
- if (this.#clearedTombstones.has(D1Transaction.#key(table, rowId))) {
384
- return undefined;
385
- }
292
+ ): Promise<Tombstone | undefined> {
293
+ this.assertOpen();
386
294
  // Persisted read, no #pending overlay: a delete buffered by this commit
387
295
  // records its tombstone at appendCommit, matching the SQLite/Postgres
388
296
  // adapters where the tombstone insert also runs at commit append.
389
- const record = await this.#db
390
- .prepare(
391
- 'SELECT commit_seq FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
392
- )
393
- .bind(this.#partition, table, rowId)
394
- .first<{ commit_seq: number }>();
395
- return record?.commit_seq;
297
+ const key = D1Transaction.#key(table, rowId);
298
+ if (this.#clearedTombstones.has(key)) return undefined;
299
+ const prefetched = this.#prefetched.get(key);
300
+ return prefetched === undefined
301
+ ? super.getTombstone(table, rowId)
302
+ : prefetched.tombstone;
396
303
  }
397
304
 
398
- async clearTombstone(table: string, rowId: string): Promise<void> {
399
- this.#assertOpen();
400
- this.#clearedTombstones.add(D1Transaction.#key(table, rowId));
401
- this.#buffer_(
402
- 'DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
403
- [this.#partition, table, rowId],
305
+ /**
306
+ * Read every named row and its tombstone in one `db.batch` (two statements
307
+ * per table, ids bound as a JSON array), so a multi-operation push pays one
308
+ * round trip instead of up to two per operation.
309
+ */
310
+ async prefetchRows(
311
+ targets: readonly {
312
+ readonly table: string;
313
+ readonly rowIds: readonly string[];
314
+ }[],
315
+ ): Promise<void> {
316
+ this.assertOpen();
317
+ const specs = targets
318
+ .map(({ table, rowIds }) => ({
319
+ table,
320
+ ids: [...new Set(rowIds)].filter(
321
+ (rowId) => !this.#prefetched.has(D1Transaction.#key(table, rowId)),
322
+ ),
323
+ }))
324
+ .filter(({ ids }) => ids.length > 0);
325
+ if (specs.length === 0) return;
326
+ const results = await this.#db.batch(
327
+ specs.flatMap(({ table, ids }) => {
328
+ const bound = JSON.stringify(ids);
329
+ return [
330
+ this.#db
331
+ .prepare(selectRowsSql(this.table(table), 'sqlite'))
332
+ .bind(this.partition, bound),
333
+ this.#db
334
+ .prepare(
335
+ 'SELECT row_id, commit_seq, server_version, scopes FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id IN (SELECT value FROM json_each(?))',
336
+ )
337
+ .bind(this.partition, table, bound),
338
+ ];
339
+ }),
404
340
  );
341
+ specs.forEach(({ table, ids }, i) => {
342
+ const rows = new Map(
343
+ (batchRows(results[2 * i]) as SqliteRowRecord[]).map((record) => [
344
+ record.row_id,
345
+ toStoredRow(record),
346
+ ]),
347
+ );
348
+ const tombstones = new Map(
349
+ (
350
+ batchRows(results[2 * i + 1]) as (SqliteTombstoneRecord & {
351
+ row_id: string;
352
+ })[]
353
+ ).map((record) => [record.row_id, toTombstone(record)]),
354
+ );
355
+ for (const rowId of ids) {
356
+ this.#prefetched.set(D1Transaction.#key(table, rowId), {
357
+ row: rows.get(rowId),
358
+ tombstone: tombstones.get(rowId),
359
+ });
360
+ }
361
+ });
362
+ }
363
+
364
+ override async clearTombstone(table: string, rowId: string): Promise<void> {
365
+ await super.clearTombstone(table, rowId);
366
+ this.#clearedTombstones.add(D1Transaction.#key(table, rowId));
405
367
  }
406
368
 
407
369
  async getPushResult(
408
370
  clientId: string,
409
371
  clientCommitId: string,
410
372
  ): Promise<StoredPushResult | undefined> {
411
- this.#assertOpen();
373
+ this.assertOpen();
412
374
  // D1 reads run in autocommit; the push layer's duplicate re-check happens
413
375
  // before this transaction buffers any write, so a direct read is exact.
414
- const record = await this.#db
415
- .prepare(
416
- 'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
417
- )
418
- .bind(this.#partition, clientId, clientCommitId)
419
- .first<{ result: string }>();
420
- if (record === null) return undefined;
421
- try {
422
- return deserializePushResult(record.result);
423
- } catch {
424
- throw syncError(
425
- 'sync.idempotency_cache_miss',
426
- 'persisted push result unreadable (§6.3)',
427
- );
428
- }
376
+ const [record] = await this.all<{ result: string }>(
377
+ 'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
378
+ [this.partition, clientId, clientCommitId],
379
+ );
380
+ return record === undefined
381
+ ? undefined
382
+ : deserializePushResult(record.result);
429
383
  }
430
384
 
431
385
  async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
432
- this.#assertOpen();
386
+ this.assertOpen();
433
387
  const firstVariable = assertScopeIndexedScan(query);
434
388
  const firstValues = query.scopeFilter[firstVariable] ?? [];
435
389
  if (firstValues.length === 0) return [];
@@ -439,7 +393,7 @@ class D1Transaction implements StorageTransaction {
439
393
  );
440
394
  const persistedLimit = query.limit + pendingForTable.length;
441
395
  const sql = scanRowPageSql(
442
- this.#resolveTable(query.table),
396
+ this.table(query.table),
443
397
  firstValues.length,
444
398
  'sqlite',
445
399
  );
@@ -450,13 +404,13 @@ class D1Transaction implements StorageTransaction {
450
404
  const { results: records } = await this.#db
451
405
  .prepare(sql)
452
406
  .bind(
453
- this.#partition,
407
+ this.partition,
454
408
  query.table,
455
409
  firstVariable,
456
- ...firstValues,
410
+ JSON.stringify(firstValues),
457
411
  afterRowId,
458
412
  batchSize,
459
- this.#partition,
413
+ this.partition,
460
414
  )
461
415
  .all<SqliteRowRecord & { payload: Uint8Array | null }>();
462
416
  if (records.length === 0) break;
@@ -492,8 +446,8 @@ class D1Transaction implements StorageTransaction {
492
446
  }
493
447
 
494
448
  async scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
495
- this.#assertOpen();
496
- const table = this.#resolveTable(query.table);
449
+ this.assertOpen();
450
+ const table = this.table(query.table);
497
451
  const index = resolveIndexRowScan(table, query);
498
452
  const pendingForTable = [...this.#pending.entries()].filter(([key]) =>
499
453
  key.startsWith(`${query.table}\u0000`),
@@ -503,7 +457,7 @@ class D1Transaction implements StorageTransaction {
503
457
  table,
504
458
  index,
505
459
  query.values,
506
- this.#partition,
460
+ this.partition,
507
461
  query.afterRowId,
508
462
  persistedLimit,
509
463
  'sqlite',
@@ -550,7 +504,7 @@ class D1Transaction implements StorageTransaction {
550
504
  async queryAuthoritative(
551
505
  query: AuthoritativeQueryRequest,
552
506
  ): Promise<AuthoritativeQueryResult> {
553
- this.#assertOpen();
507
+ this.assertOpen();
554
508
  // D1 buffers writes until commit() and cannot overlay them on generated
555
509
  // SQL, so a read over a written table would return committed state
556
510
  // without this transaction's staged rows. Refuse it instead.
@@ -561,7 +515,7 @@ class D1Transaction implements StorageTransaction {
561
515
  }
562
516
  return queryAuthoritativeOn(
563
517
  this.#db,
564
- this.#partition,
518
+ this.partition,
565
519
  this.#prepareQuery(query),
566
520
  );
567
521
  }
@@ -575,7 +529,7 @@ class D1Transaction implements StorageTransaction {
575
529
  readonly rowIds: readonly string[];
576
530
  }[] = [],
577
531
  ): Promise<PreparedPushApply> {
578
- this.#assertOpen();
532
+ this.assertOpen();
579
533
  if (!this.#pushApplySerialized) {
580
534
  throw new Error(
581
535
  'D1 push apply requires externally serialized partition writes',
@@ -604,7 +558,7 @@ class D1Transaction implements StorageTransaction {
604
558
  }
605
559
 
606
560
  async readServeGate(_runningSchemaVersion: number): Promise<ServeGate> {
607
- this.#assertOpen();
561
+ this.assertOpen();
608
562
  const marker = await this.#db
609
563
  .prepare('SELECT schema_version FROM sync_schema_meta WHERE id=1')
610
564
  .first<{ schema_version: number }>();
@@ -620,7 +574,7 @@ class D1Transaction implements StorageTransaction {
620
574
  clientCommitId: string,
621
575
  result: StoredPushResult,
622
576
  ): Promise<StoredPushResult> {
623
- this.#assertOpen();
577
+ this.assertOpen();
624
578
  const checkpoint = this.#pushApplyCheckpoint;
625
579
  if (checkpoint === undefined) {
626
580
  throw new Error('push rejection requires its apply checkpoint');
@@ -693,7 +647,7 @@ class D1Transaction implements StorageTransaction {
693
647
  });
694
648
  const persisted = await this.#db
695
649
  .prepare(sql)
696
- .bind(this.#partition, ...bind, row.rowId)
650
+ .bind(this.partition, ...bind, row.rowId)
697
651
  .first<{ row_id: string }>();
698
652
  if (persisted === null) continue;
699
653
 
@@ -720,9 +674,12 @@ class D1Transaction implements StorageTransaction {
720
674
  row: StoredRow,
721
675
  context?: { readonly opIndex: number },
722
676
  ): Promise<void> {
723
- this.#assertOpen();
724
- const compiled = this.#resolveTable(table);
725
- await this.#assertNoUniqueCollision(compiled, row, context?.opIndex);
677
+ this.assertOpen();
678
+ await this.#assertNoUniqueCollision(
679
+ this.table(table),
680
+ row,
681
+ context?.opIndex,
682
+ );
726
683
  if (context?.opIndex !== undefined) {
727
684
  this.#applicationOpIndexes.add(context.opIndex);
728
685
  }
@@ -730,91 +687,33 @@ class D1Transaction implements StorageTransaction {
730
687
  kind: 'row',
731
688
  row,
732
689
  });
733
- const p = this.#partition;
734
- // Scope index maintenance: delete only the old keys the new scope map no
735
- // longer carries, then insert the new keys. Keys present in both are left
736
- // alone, so the `INSERT OR IGNORE` below finds them and writes nothing.
737
- // This DELETE precedes the row upsert in the same atomic batch, and its
738
- // subquery reads the row's pre-upsert scope map.
739
- const scopesJson = JSON.stringify(row.scopes);
740
- this.#buffer_(
741
- `${deleteSqliteRowScopesSql(compiled)}
742
- AND (var, value) NOT IN (
743
- SELECT key, value FROM json_each(?)
744
- )`,
745
- [p, table, row.rowId, p, row.rowId, scopesJson],
746
- );
747
- this.#buffer_(
748
- upsertSql(compiled, 'sqlite'),
749
- upsertValues(compiled, p, row, 'sqlite'),
750
- );
751
- for (const [variable, value] of Object.entries(row.scopes)) {
752
- this.#buffer_(
753
- 'INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)',
754
- [p, table, variable, value, row.rowId],
755
- );
756
- }
690
+ this.writeRow(table, row);
757
691
  }
758
692
 
759
- async deleteRow(table: string, rowId: string): Promise<void> {
760
- this.#assertOpen();
693
+ override async deleteRow(table: string, rowId: string): Promise<void> {
694
+ await super.deleteRow(table, rowId);
761
695
  this.#pending.set(D1Transaction.#key(table, rowId), { kind: 'deleted' });
762
- const p = this.#partition;
763
- const compiled = this.#resolveTable(table);
764
- this.#buffer_(deleteSqliteRowScopesSql(compiled), [
765
- p,
766
- table,
767
- rowId,
768
- p,
769
- rowId,
770
- ]);
771
- this.#buffer_(deleteRowSql(compiled, 'sqlite'), [p, rowId]);
772
- // §5.9.4: a deleted row references no blobs.
773
- this.#buffer_(
774
- 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
775
- [p, table, rowId],
776
- );
777
- }
778
-
779
- async setBlobRefs(
780
- table: string,
781
- rowId: string,
782
- blobIds: readonly string[],
783
- ): Promise<void> {
784
- this.#assertOpen();
785
- const p = this.#partition;
786
- this.#buffer_(
787
- 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
788
- [p, table, rowId],
789
- );
790
- for (const blobId of blobIds) {
791
- this.#buffer_(
792
- 'INSERT OR IGNORE INTO sync_blob_refs(partition, tbl, row_id, blob_id) VALUES (?,?,?,?)',
793
- [p, table, rowId, blobId],
794
- );
795
- }
796
696
  }
797
697
 
798
- async appendCommit(commit: NewCommit): Promise<number> {
799
- this.#assertOpen();
800
- const p = this.#partition;
698
+ protected async appendCommitRow(commit: NewCommit): Promise<number> {
699
+ const p = this.partition;
801
700
  // Read the live counter once, then advance it in memory for this tx; the
802
701
  // increment is buffered and lands atomically at commit() (see header for
803
702
  // the concurrency posture).
804
703
  if (this.#maxCommitSeq === undefined) {
805
- const row = await this.#db
806
- .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
807
- .bind(p)
808
- .first<{ max_commit_seq: number }>();
704
+ const [row] = await this.all<{ max_commit_seq: number }>(
705
+ 'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
706
+ [p],
707
+ );
809
708
  this.#maxCommitSeq = row?.max_commit_seq ?? 0;
810
709
  }
811
710
  const commitSeq = this.#maxCommitSeq + 1;
812
711
  this.#maxCommitSeq = commitSeq;
813
- this.#buffer_(
712
+ this.run(
814
713
  'INSERT INTO sync_partitions(partition, max_commit_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET max_commit_seq=excluded.max_commit_seq',
815
714
  [p, commitSeq],
816
715
  );
817
- this.#buffer_(
716
+ this.run(
818
717
  'INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms) VALUES (?,?,?,?,?,?)',
819
718
  [
820
719
  p,
@@ -825,87 +724,13 @@ class D1Transaction implements StorageTransaction {
825
724
  commit.createdAtMs,
826
725
  ],
827
726
  );
828
- const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
829
- commit.changes.forEach((change, idx) => {
830
- this.#buffer_(
831
- 'INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)',
832
- [
833
- p,
834
- commitSeq,
835
- idx,
836
- change.table,
837
- change.rowId,
838
- change.op === 'upsert' ? 1 : 2,
839
- change.rowVersion ?? null,
840
- JSON.stringify(change.scopes),
841
- change.payload ?? null,
842
- ],
843
- );
844
- if (
845
- change.op === 'delete' &&
846
- !liveAfterDelete.has(`${change.table}\u0000${change.rowId}`)
847
- ) {
848
- // §5 delete precedence: every applied delete leaves a tombstone,
849
- // pruned with the commit log (§4.6). A delete that the same commit
850
- // follows with an upsert is a §2.2 scope move, not a deletion.
851
- this.#buffer_(
852
- `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq) VALUES (?,?,?,?)
853
- ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq`,
854
- [p, change.table, change.rowId, commitSeq],
855
- );
856
- }
857
- for (const [variable, value] of Object.entries(change.scopes)) {
858
- this.#buffer_(
859
- 'INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)',
860
- [p, change.table, variable, value, commitSeq],
861
- );
862
- }
863
- });
864
727
  return commitSeq;
865
728
  }
866
729
 
867
- async putPushResult(
868
- clientId: string,
869
- clientCommitId: string,
870
- result: StoredPushResult,
871
- ): Promise<void> {
872
- this.#assertOpen();
873
- this.#buffer_(
874
- 'INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
875
- [this.#partition, clientId, clientCommitId, serializePushResult(result)],
876
- );
877
- }
878
-
879
- async enqueueReactions(reactions: readonly NewReaction[]): Promise<void> {
880
- this.#assertOpen();
881
- for (const reaction of reactions) {
882
- this.#buffer_(
883
- `INSERT INTO sync_reactions(
884
- partition, idempotency_key, type, version, payload,
885
- source_client_id, source_client_commit_id, source_commit_seq,
886
- created_at_ms, available_at_ms, status, attempts, max_attempts
887
- ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`,
888
- [
889
- this.#partition,
890
- reaction.idempotencyKey,
891
- reaction.type,
892
- reaction.version,
893
- JSON.stringify(reaction.payload),
894
- reaction.sourceClientId,
895
- reaction.sourceClientCommitId,
896
- reaction.sourceCommitSeq,
897
- reaction.createdAtMs,
898
- reaction.createdAtMs,
899
- reaction.maxAttempts,
900
- ],
901
- );
902
- }
903
- }
904
-
905
730
  async commit(): Promise<void> {
906
- this.#assertOpen();
731
+ this.assertOpen();
907
732
  if (this.#buffer.length === 0) {
908
- this.#open = false;
733
+ this.open = false;
909
734
  return;
910
735
  }
911
736
  const statements = this.#buffer.map((entry) =>
@@ -914,7 +739,7 @@ class D1Transaction implements StorageTransaction {
914
739
  // One atomic D1 batch — the §6.4 all-or-nothing commit.
915
740
  try {
916
741
  await this.#db.batch(statements);
917
- this.#open = false;
742
+ this.open = false;
918
743
  } catch (error) {
919
744
  if (isD1ConstraintError(error)) {
920
745
  // D1 batches are atomic. Keep this logical transaction open so the
@@ -932,18 +757,12 @@ class D1Transaction implements StorageTransaction {
932
757
  }
933
758
 
934
759
  async rollback(): Promise<void> {
935
- if (!this.#open) return;
936
- this.#open = false;
760
+ if (!this.open) return;
761
+ this.open = false;
937
762
  this.#buffer.length = 0;
938
763
  }
939
764
  }
940
765
 
941
- /**
942
- * D1 caps bound parameters at 100 per statement; the relational upsert
943
- * binds one per app column plus the five `_sync_*` meta columns.
944
- */
945
- const D1_MAX_BIND_PARAMS = 100;
946
-
947
766
  export interface D1ServerStorageOptions {
948
767
  /**
949
768
  * Assert that all writes for a partition reach this storage serially.
@@ -998,7 +817,7 @@ interface D1MigrationClaim {
998
817
  state: string;
999
818
  }
1000
819
 
1001
- /** The reads queued for one `D1ServerStorage#batchedAll` round trip. */
820
+ /** The reads queued for one `D1ServerStorage.guardedAll` round trip. */
1002
821
  interface PendingReads {
1003
822
  readonly db: Pick<D1Database, 'prepare' | 'batch'>;
1004
823
  readonly entries: {
@@ -1008,12 +827,17 @@ interface PendingReads {
1008
827
  }[];
1009
828
  }
1010
829
 
1011
- export class D1ServerStorage implements ServerStorage {
830
+ export class D1ServerStorage
831
+ extends SqliteFamilyStorage
832
+ implements ServerStorage
833
+ {
1012
834
  readonly #db: D1Database;
1013
835
  readonly #pushApplySerialized: boolean;
1014
- /** Set by `ensureSchema`: app-table lookup for the relational row store. */
1015
- #tables: ReadonlyMap<string, CompiledTable> | undefined;
1016
- #schemaVersion: number | undefined;
836
+ /**
837
+ * D1 caps bound parameters at 100 per statement; the relational upsert
838
+ * binds one per app column plus the five `_sync_*` meta columns.
839
+ */
840
+ protected readonly maxBindParams = 100;
1017
841
  /**
1018
842
  * Page reads waiting for the end of the current microtask turn. A pull
1019
843
  * starts the window read (or first snapshot page) of every subscription
@@ -1023,45 +847,110 @@ export class D1ServerStorage implements ServerStorage {
1023
847
  #pendingReads: PendingReads | undefined;
1024
848
 
1025
849
  constructor(db: D1Database, options: D1ServerStorageOptions = {}) {
850
+ super();
1026
851
  this.#db = db;
1027
852
  this.#pushApplySerialized =
1028
853
  options.pushApplySerialized === true ||
1029
854
  options.commitValidationSerialized === true;
1030
855
  }
1031
856
 
857
+ protected async all<T>(
858
+ sql: string,
859
+ params: readonly SqliteValue[],
860
+ ): Promise<T[]> {
861
+ return (
862
+ await this.#db
863
+ .prepare(sql)
864
+ .bind(...params)
865
+ .all<T>()
866
+ ).results;
867
+ }
868
+
869
+ /** Queue one read into the current turn's `db.batch` (see `#pendingReads`). */
870
+ protected guardedAll<T>(
871
+ sql: string,
872
+ params: readonly SqliteValue[],
873
+ ): Promise<T[]> {
874
+ let pending = this.#pendingReads;
875
+ if (pending === undefined) {
876
+ const created: PendingReads = {
877
+ db: this.#schemaDatabase(),
878
+ entries: [],
879
+ };
880
+ pending = created;
881
+ this.#pendingReads = created;
882
+ queueMicrotask(() => {
883
+ this.#pendingReads = undefined;
884
+ created.db.batch(created.entries.map((entry) => entry.statement)).then(
885
+ (results) => {
886
+ created.entries.forEach((entry, i) => {
887
+ try {
888
+ entry.resolve(batchRows(results[i]));
889
+ } catch (error) {
890
+ entry.reject(error);
891
+ }
892
+ });
893
+ },
894
+ (error: unknown) => {
895
+ for (const entry of created.entries) entry.reject(error);
896
+ },
897
+ );
898
+ });
899
+ }
900
+ const target = pending;
901
+ const statement = target.db.prepare(sql).bind(...params);
902
+ return new Promise<T[]>((resolve, reject) => {
903
+ target.entries.push({
904
+ statement,
905
+ resolve: (rows) => resolve(rows as T[]),
906
+ reject,
907
+ });
908
+ });
909
+ }
910
+
911
+ protected async atomic(
912
+ statements: readonly SqliteStatementSpec[],
913
+ ): Promise<unknown[][]> {
914
+ const results = await this.#db.batch(
915
+ statements.map(({ sql, params }) =>
916
+ this.#db.prepare(sql).bind(...params),
917
+ ),
918
+ );
919
+ return results.map(batchRows);
920
+ }
921
+
1032
922
  /** Apply the schema DDL (idempotent). Call once before use. */
1033
923
  async migrate(): Promise<void> {
1034
924
  for (const statement of sqliteDdlStatements()) {
1035
925
  await this.#db.exec(`${statement.replace(/\s+/g, ' ')};`);
1036
926
  }
1037
- const { results } = await this.#db
1038
- .prepare('PRAGMA table_info("sync_clients")')
1039
- .all<{ name: string }>();
1040
- if (!results.some((column) => column.name === 'wire_version')) {
1041
- await this.#db.exec(
1042
- 'ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1;',
1043
- );
1044
- }
1045
- for (const [name, definition] of Object.entries(
1046
- SYNC_CLIENT_ROUND_COLUMNS,
1047
- )) {
1048
- if (!results.some((column) => column.name === name)) {
1049
- await this.#db.exec(
1050
- `ALTER TABLE sync_clients ADD COLUMN ${name} ${definition};`,
1051
- );
1052
- }
927
+ for (const sql of await this.#addedColumnDdl()) {
928
+ await this.#db.exec(`${sql};`);
1053
929
  }
1054
930
  }
1055
931
 
1056
- /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
1057
- table(name: string): CompiledTable {
1058
- const table = this.#tables?.get(name);
1059
- if (table === undefined) {
1060
- throw new Error(
1061
- `unknown table ${JSON.stringify(name)} — ensureSchema(schema) must run before row operations`,
1062
- );
1063
- }
1064
- return table;
932
+ /**
933
+ * `ALTER TABLE` statements for the `SQLITE_ADDED_COLUMNS` this database
934
+ * lacks, read in one statement.
935
+ */
936
+ async #addedColumnDdl(): Promise<string[]> {
937
+ const { results } = await this.#db
938
+ .prepare(
939
+ 'SELECT t.value AS tbl, c.name AS name FROM json_each(?) AS t, pragma_table_info(t.value) AS c',
940
+ )
941
+ .bind(
942
+ JSON.stringify([
943
+ ...new Set(SQLITE_ADDED_COLUMNS.map(([table]) => table)),
944
+ ]),
945
+ )
946
+ .all<{ tbl: string; name: string }>();
947
+ return SQLITE_ADDED_COLUMNS.filter(
948
+ ([table, name]) =>
949
+ !results.some((column) => column.tbl === table && column.name === name),
950
+ ).map(
951
+ ([table, name, definition]) =>
952
+ `ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`,
953
+ );
1065
954
  }
1066
955
 
1067
956
  async ensureSchema(
@@ -1073,7 +962,7 @@ export class D1ServerStorage implements ServerStorage {
1073
962
  // visibility here; refuse instead of accepting a weaker guarantee.
1074
963
  throw new StorageQueryError('sync.storage.checkpoint_unsupported');
1075
964
  }
1076
- if (this.#schemaVersion === schema.version) {
965
+ if (this.schemaVersion === schema.version) {
1077
966
  await this.#schemaDatabase().batch([]);
1078
967
  return;
1079
968
  }
@@ -1102,7 +991,7 @@ export class D1ServerStorage implements ServerStorage {
1102
991
  a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
1103
992
  );
1104
993
  for (const table of tables) {
1105
- if (tableColumnNames(table).length > D1_MAX_BIND_PARAMS) {
994
+ if (tableColumnNames(table).length > this.maxBindParams) {
1106
995
  throw new Error('D1 caps statements at 100 bound parameters');
1107
996
  }
1108
997
  }
@@ -1181,25 +1070,11 @@ export class D1ServerStorage implements ServerStorage {
1181
1070
  'sqlite',
1182
1071
  );
1183
1072
  }
1184
- // A database from before the round-state columns gains them in place.
1073
+ // A database from before a core-table column gains it in place.
1185
1074
  statementsExecuted++;
1186
- const clientColumns = await this.#db
1187
- .prepare('PRAGMA table_info("sync_clients")')
1188
- .all<{ name: string }>();
1189
- const missingRoundColumns = Object.entries(
1190
- SYNC_CLIENT_ROUND_COLUMNS,
1191
- ).filter(
1192
- ([name]) =>
1193
- !clientColumns.results.some((column) => column.name === name),
1194
- );
1195
- if (missingRoundColumns.length > 0) {
1196
- await batch(
1197
- missingRoundColumns.map(([name, definition]) =>
1198
- this.#db.prepare(
1199
- `ALTER TABLE sync_clients ADD COLUMN ${name} ${definition}`,
1200
- ),
1201
- ),
1202
- );
1075
+ const added = await this.#addedColumnDdl();
1076
+ if (added.length > 0) {
1077
+ await batch(added.map((sql) => this.#db.prepare(sql)));
1203
1078
  }
1204
1079
  // Server-only indexes reconcile at every open of a database already at
1205
1080
  // this version: they never reach a client, so no version bump is needed.
@@ -1219,8 +1094,8 @@ export class D1ServerStorage implements ServerStorage {
1219
1094
  if (reconcile.length > 0) {
1220
1095
  await batch(reconcile.map((sql) => this.#db.prepare(sql)));
1221
1096
  }
1222
- this.#tables = schema.tables;
1223
- this.#schemaVersion = schema.version;
1097
+ this.tables = schema.tables;
1098
+ this.schemaVersion = schema.version;
1224
1099
  return { complete: true, statementsExecuted };
1225
1100
  }
1226
1101
  if (marker !== null && marker.schema_version > schema.version) {
@@ -1333,25 +1208,15 @@ export class D1ServerStorage implements ServerStorage {
1333
1208
  break;
1334
1209
  continue;
1335
1210
  }
1211
+ // The column read, the checkpoint pair, and every missing column.
1336
1212
  if (remaining < 4) break;
1337
1213
  statementsExecuted++;
1338
- const columns = await this.#db
1339
- .prepare('PRAGMA table_info("sync_clients")')
1340
- .all<{ name: string }>();
1341
- const missingColumns = Object.entries({
1342
- wire_version: 'INTEGER NOT NULL DEFAULT 1',
1343
- ...SYNC_CLIENT_ROUND_COLUMNS,
1344
- }).filter(
1345
- ([name]) => !columns.results.some((column) => column.name === name),
1346
- );
1214
+ const added = await this.#addedColumnDdl();
1215
+ if (remaining < 3 + added.length) break;
1347
1216
  if (
1348
1217
  !(await save(
1349
1218
  { ...state, phase: 'prepare', offset: 0 },
1350
- missingColumns.map(([name, definition]) =>
1351
- this.#db.prepare(
1352
- `ALTER TABLE sync_clients ADD COLUMN ${name} ${definition}`,
1353
- ),
1354
- ),
1219
+ added.map((sql) => this.#db.prepare(sql)),
1355
1220
  ))
1356
1221
  )
1357
1222
  break;
@@ -1488,8 +1353,8 @@ export class D1ServerStorage implements ServerStorage {
1488
1353
  ))
1489
1354
  )
1490
1355
  break;
1491
- this.#tables = schema.tables;
1492
- this.#schemaVersion = schema.version;
1356
+ this.tables = schema.tables;
1357
+ this.schemaVersion = schema.version;
1493
1358
  return { complete: true, statementsExecuted };
1494
1359
  }
1495
1360
  const table = schema.tables.get(plan.table);
@@ -1547,58 +1412,11 @@ export class D1ServerStorage implements ServerStorage {
1547
1412
  }
1548
1413
 
1549
1414
  /** Every protected read or write shares a transaction with its schema check. */
1550
- /** Queue one read into the current turn's `db.batch` (see `#pendingReads`). */
1551
- #batchedAll<T>(sql: string, params: unknown[]): Promise<T[]> {
1552
- let pending = this.#pendingReads;
1553
- if (pending === undefined) {
1554
- const created: PendingReads = {
1555
- db: this.#schemaDatabase(),
1556
- entries: [],
1557
- };
1558
- pending = created;
1559
- this.#pendingReads = created;
1560
- queueMicrotask(() => {
1561
- this.#pendingReads = undefined;
1562
- created.db.batch(created.entries.map((entry) => entry.statement)).then(
1563
- (results) => {
1564
- created.entries.forEach((entry, i) => {
1565
- const result = results[i];
1566
- if (
1567
- typeof result !== 'object' ||
1568
- result === null ||
1569
- !('results' in result) ||
1570
- !Array.isArray(result.results)
1571
- ) {
1572
- entry.reject(
1573
- new Error('D1 query returned an invalid batch result'),
1574
- );
1575
- } else {
1576
- entry.resolve(result.results);
1577
- }
1578
- });
1579
- },
1580
- (error: unknown) => {
1581
- for (const entry of created.entries) entry.reject(error);
1582
- },
1583
- );
1584
- });
1585
- }
1586
- const target = pending;
1587
- const statement = target.db.prepare(sql).bind(...params);
1588
- return new Promise<T[]>((resolve, reject) => {
1589
- target.entries.push({
1590
- statement,
1591
- resolve: (rows) => resolve(rows as T[]),
1592
- reject,
1593
- });
1594
- });
1595
- }
1596
-
1597
1415
  #schemaDatabase(): Pick<D1Database, 'prepare' | 'batch'> {
1598
- if (this.#schemaVersion === undefined)
1416
+ if (this.schemaVersion === undefined)
1599
1417
  throw new StorageQueryError('sync.storage.schema_changed');
1600
1418
  const db = this.#db;
1601
- const version = this.#schemaVersion;
1419
+ const version = this.schemaVersion;
1602
1420
  const sources = new WeakMap<D1PreparedStatement, D1PreparedStatement>();
1603
1421
  const execute = async (
1604
1422
  statements: D1PreparedStatement[],
@@ -1633,16 +1451,9 @@ export class D1ServerStorage implements ServerStorage {
1633
1451
  ): D1PreparedStatement => {
1634
1452
  const source = db.prepare(sql).bind(...params);
1635
1453
  const all = async <T>(): Promise<{ results: T[] }> => {
1636
- const result = (await execute([source]))[0];
1637
- if (
1638
- typeof result !== 'object' ||
1639
- result === null ||
1640
- !('results' in result) ||
1641
- !Array.isArray(result.results)
1642
- ) {
1643
- throw new Error('D1 query returned an invalid batch result');
1644
- }
1645
- return { results: result.results as T[] };
1454
+ return {
1455
+ results: batchRows((await execute([source]))[0]) as T[],
1456
+ };
1646
1457
  };
1647
1458
  const statement: D1PreparedStatement = {
1648
1459
  bind: (...values) => prepare(sql, values),
@@ -1667,108 +1478,8 @@ export class D1ServerStorage implements ServerStorage {
1667
1478
  };
1668
1479
  }
1669
1480
 
1670
- async touchPartition(
1671
- partition: string,
1672
- authenticatedAtMs: number,
1673
- initialLogEpoch: string,
1674
- ): Promise<PartitionRegistryEntry> {
1675
- if (initialLogEpoch.length === 0) {
1676
- throw new Error('initial log epoch must be non-empty');
1677
- }
1678
- const select = this.#db
1679
- .prepare(
1680
- `SELECT log_epoch, epoch_required, last_authenticated_at_ms
1681
- FROM sync_partition_registry WHERE partition=?`,
1682
- )
1683
- .bind(partition);
1684
- let row = await select.first<{
1685
- log_epoch: string;
1686
- epoch_required: number;
1687
- last_authenticated_at_ms: number;
1688
- }>();
1689
- if (
1690
- row === null ||
1691
- authenticatedAtMs - row.last_authenticated_at_ms >=
1692
- PARTITION_TOUCH_INTERVAL_MS
1693
- ) {
1694
- await this.#db
1695
- .prepare(
1696
- `INSERT INTO sync_partition_registry(
1697
- partition, log_epoch, last_authenticated_at_ms
1698
- ) VALUES (?,?,?)
1699
- ON CONFLICT(partition) DO UPDATE SET
1700
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`,
1701
- )
1702
- .bind(partition, initialLogEpoch, authenticatedAtMs)
1703
- .run();
1704
- row = await select.first<{
1705
- log_epoch: string;
1706
- epoch_required: number;
1707
- last_authenticated_at_ms: number;
1708
- }>();
1709
- }
1710
- if (row === null)
1711
- throw new Error('partition registry write did not persist');
1712
- return {
1713
- partition,
1714
- logEpoch: row.log_epoch,
1715
- epochRequired: row.epoch_required === 1,
1716
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
1717
- };
1718
- }
1719
-
1720
- async rotatePartitionLogEpoch(
1721
- partition: string,
1722
- logEpoch: string,
1723
- authenticatedAtMs: number,
1724
- ): Promise<PartitionRegistryEntry> {
1725
- if (logEpoch.length === 0) throw new Error('log epoch must be non-empty');
1726
- await this.#db.batch([
1727
- this.#db
1728
- .prepare(
1729
- `INSERT INTO sync_partition_registry(
1730
- partition, log_epoch, epoch_required, last_authenticated_at_ms
1731
- ) VALUES (?,?,1,?)
1732
- ON CONFLICT(partition) DO UPDATE SET
1733
- log_epoch=excluded.log_epoch,
1734
- epoch_required=1,
1735
- last_authenticated_at_ms=excluded.last_authenticated_at_ms`,
1736
- )
1737
- .bind(partition, logEpoch, authenticatedAtMs),
1738
- this.#db
1739
- .prepare('DELETE FROM sync_clients WHERE partition=?')
1740
- .bind(partition),
1741
- ]);
1742
- return {
1743
- partition,
1744
- logEpoch,
1745
- epochRequired: true,
1746
- lastAuthenticatedAtMs: authenticatedAtMs,
1747
- };
1748
- }
1749
-
1750
- async listPartitionRegistry(): Promise<PartitionRegistryEntry[]> {
1751
- const { results } = await this.#db
1752
- .prepare(
1753
- `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
1754
- FROM sync_partition_registry ORDER BY partition`,
1755
- )
1756
- .all<{
1757
- partition: string;
1758
- log_epoch: string;
1759
- epoch_required: number;
1760
- last_authenticated_at_ms: number;
1761
- }>();
1762
- return results.map((row) => ({
1763
- partition: row.partition,
1764
- logEpoch: row.log_epoch,
1765
- epochRequired: row.epoch_required === 1,
1766
- lastAuthenticatedAtMs: row.last_authenticated_at_ms,
1767
- }));
1768
- }
1769
-
1770
1481
  async begin(partition: string): Promise<StorageTransaction> {
1771
- const tables = this.#tables;
1482
+ const tables = this.tables;
1772
1483
  const db = this.#schemaDatabase();
1773
1484
  return new D1Transaction(
1774
1485
  db,
@@ -1779,19 +1490,11 @@ export class D1ServerStorage implements ServerStorage {
1779
1490
  throw new StorageQueryError('sync.storage.schema_changed');
1780
1491
  return table;
1781
1492
  },
1782
- (query) => this.#prepareAuthoritativeQuery(partition, query),
1493
+ (query) => this.prepareAuthoritativeQuery(partition, query),
1783
1494
  this.#pushApplySerialized,
1784
1495
  );
1785
1496
  }
1786
1497
 
1787
- async getMaxCommitSeq(partition: string): Promise<number> {
1788
- const row = await this.#db
1789
- .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
1790
- .bind(partition)
1791
- .first<{ max_commit_seq: number }>();
1792
- return row?.max_commit_seq ?? 0;
1793
- }
1794
-
1795
1498
  async queryAuthoritative(
1796
1499
  partition: string,
1797
1500
  query: AuthoritativeQueryRequest,
@@ -1804,139 +1507,19 @@ export class D1ServerStorage implements ServerStorage {
1804
1507
  return queryAuthoritativeOn(
1805
1508
  db,
1806
1509
  partition,
1807
- this.#prepareAuthoritativeQuery(partition, query),
1510
+ this.prepareAuthoritativeQuery(partition, query),
1808
1511
  );
1809
1512
  }
1810
1513
 
1811
- #prepareAuthoritativeQuery(
1514
+ override async pruneCommitsThrough(
1812
1515
  partition: string,
1813
- query: AuthoritativeQueryRequest,
1814
- ): BoundAuthoritativeQuery {
1815
- if (this.#tables === undefined) {
1516
+ query: CommitPruneQuery,
1517
+ ): Promise<CommitPruneResult> {
1518
+ if (!this.#pushApplySerialized)
1816
1519
  throw new Error(
1817
- 'ensureSchema(schema) must run before registered queries',
1520
+ 'D1 pruning requires externally serialized partition writes',
1818
1521
  );
1819
- }
1820
- return bindAuthoritativePartition(
1821
- prepareAuthoritativeQuery(
1822
- query.plan,
1823
- query.params,
1824
- query.tables,
1825
- this.#tables,
1826
- ),
1827
- partition,
1828
- );
1829
- }
1830
-
1831
- async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
1832
- const row = await this.#db
1833
- .prepare(
1834
- 'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
1835
- )
1836
- .bind(partition)
1837
- .first<{ log_epoch: string }>();
1838
- return row?.log_epoch;
1839
- }
1840
-
1841
- async getHorizonSeq(partition: string): Promise<number> {
1842
- const row = await this.#db
1843
- .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
1844
- .bind(partition)
1845
- .first<{ horizon_seq: number }>();
1846
- return row?.horizon_seq ?? 0;
1847
- }
1848
-
1849
- async setHorizonSeq(partition: string, seq: number): Promise<void> {
1850
- await this.#db
1851
- .prepare(
1852
- 'INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?) ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)',
1853
- )
1854
- .bind(partition, seq)
1855
- .run();
1856
- }
1857
-
1858
- async pruneCommitsThrough(
1859
- partition: string,
1860
- query: CommitPruneQuery,
1861
- ): Promise<CommitPruneResult> {
1862
- validateCommitPruneQuery(query);
1863
- if (!this.#pushApplySerialized)
1864
- throw new Error(
1865
- 'D1 pruning requires externally serialized partition writes',
1866
- );
1867
- const epochGuard =
1868
- 'EXISTS (SELECT 1 FROM sync_partition_registry WHERE partition=? AND log_epoch=?)';
1869
- const horizon =
1870
- '(SELECT horizon_seq FROM sync_partitions WHERE partition=?)';
1871
- const results = await this.#db.batch([
1872
- this.#db
1873
- .prepare(
1874
- `SELECT log_epoch, coalesce(${horizon},0) AS previous_horizon_seq FROM sync_partition_registry WHERE partition=?`,
1875
- )
1876
- .bind(partition, partition),
1877
- this.#db
1878
- .prepare(`INSERT INTO sync_partitions(partition,horizon_seq) SELECT ?,? WHERE ${epochGuard}
1879
- ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
1880
- .bind(partition, query.throughSeq, partition, query.logEpoch),
1881
- this.#db
1882
- .prepare(
1883
- `SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`,
1884
- )
1885
- .bind(partition, partition, partition),
1886
- ...[
1887
- 'sync_commits',
1888
- 'sync_changes',
1889
- 'sync_change_scopes',
1890
- 'sync_tombstones',
1891
- ].map((table) =>
1892
- this.#db
1893
- .prepare(
1894
- `DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`,
1895
- )
1896
- .bind(partition, partition, partition, query.logEpoch),
1897
- ),
1898
- ]);
1899
- const [before, after] = [results[0], results[2]].map((result) => {
1900
- if (
1901
- typeof result !== 'object' ||
1902
- result === null ||
1903
- !('results' in result) ||
1904
- !Array.isArray(result.results)
1905
- ) {
1906
- throw new Error('D1 pruning returned an invalid batch result');
1907
- }
1908
- const row: unknown = result.results[0];
1909
- return typeof row === 'object' && row !== null
1910
- ? (row as Readonly<Record<string, unknown>>)
1911
- : undefined;
1912
- });
1913
- if (before?.log_epoch !== query.logEpoch)
1914
- throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
1915
- if (
1916
- typeof before.previous_horizon_seq !== 'number' ||
1917
- typeof after?.horizon_seq !== 'number' ||
1918
- typeof after.removed_commits !== 'number'
1919
- ) {
1920
- throw new Error('D1 pruning returned invalid horizon metadata');
1921
- }
1922
- return {
1923
- previousHorizonSeq: before.previous_horizon_seq,
1924
- horizonSeq: after.horizon_seq,
1925
- removedCommits: after.removed_commits,
1926
- };
1927
- }
1928
-
1929
- async getCommitSeqBefore(
1930
- partition: string,
1931
- createdBeforeMs: number,
1932
- ): Promise<number> {
1933
- const row = await this.#db
1934
- .prepare(
1935
- 'SELECT max(commit_seq) AS seq FROM sync_commits WHERE partition=? AND created_at_ms<?',
1936
- )
1937
- .bind(partition, createdBeforeMs)
1938
- .first<{ seq: number | null }>();
1939
- return row?.seq ?? 0;
1522
+ return super.pruneCommitsThrough(partition, query);
1940
1523
  }
1941
1524
 
1942
1525
  async readCheckpoints(_partition: string): Promise<StoredCheckpoint[]> {
@@ -2002,635 +1585,7 @@ export class D1ServerStorage implements ServerStorage {
2002
1585
  throw new StorageQueryError('sync.storage.checkpoint_unsupported');
2003
1586
  }
2004
1587
 
2005
- async sourceCoverageSeq(
2006
- partition: string,
2007
- tables: readonly string[],
2008
- ): Promise<number> {
2009
- if (tables.length === 0) return 0;
2010
- const tableParams = tables.map(() => '?').join(',');
2011
- const row = await this.#db
2012
- .prepare(
2013
- `SELECT max(commit_seq) AS seq FROM sync_changes
2014
- WHERE partition=? AND tbl IN (${tableParams})`,
2015
- )
2016
- .bind(partition, ...tables)
2017
- .first<{ seq: number | null }>();
2018
- return row?.seq ?? 0;
2019
- }
2020
-
2021
- async hasSourceChangesAbove(
2022
- partition: string,
2023
- tables: readonly string[],
2024
- seq: number,
2025
- ): Promise<'clean' | 'changed' | 'unverifiable'> {
2026
- // Read the horizon before the window scan: a horizon past `seq` means the
2027
- // history that would answer the question is gone, so an empty scan proves
2028
- // nothing and must not be reported as `clean`.
2029
- const horizon = await this.getHorizonSeq(partition);
2030
- if (tables.length === 0) return 'clean';
2031
- const tableParams = tables.map(() => '?').join(',');
2032
- const hit = await this.#db
2033
- .prepare(
2034
- `SELECT 1 AS hit FROM sync_changes
2035
- WHERE partition=? AND tbl IN (${tableParams}) AND commit_seq>?
2036
- LIMIT 1`,
2037
- )
2038
- .bind(partition, ...tables, seq)
2039
- .first<{ hit: number }>();
2040
- if (hit !== null) return 'changed';
2041
- return horizon > seq ? 'unverifiable' : 'clean';
2042
- }
2043
-
2044
- async getRow(
2045
- partition: string,
2046
- table: string,
2047
- rowId: string,
2048
- ): Promise<StoredRow | undefined> {
2049
- const db = this.#schemaDatabase();
2050
- const record = await db
2051
- .prepare(selectRowSql(this.table(table), 'sqlite'))
2052
- .bind(partition, rowId)
2053
- .first<SqliteRowRecord>();
2054
- return record === null ? undefined : toStoredRow(record);
2055
- }
2056
-
2057
- async getPushResult(
2058
- partition: string,
2059
- clientId: string,
2060
- clientCommitId: string,
2061
- ): Promise<StoredPushResult | undefined> {
2062
- const db = this.#schemaDatabase();
2063
- const record = await db
2064
- .prepare(
2065
- 'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
2066
- )
2067
- .bind(partition, clientId, clientCommitId)
2068
- .first<{ result: string }>();
2069
- if (record === null) return undefined;
2070
- try {
2071
- return deserializePushResult(record.result);
2072
- } catch {
2073
- throw syncError(
2074
- 'sync.idempotency_cache_miss',
2075
- 'persisted push result unreadable (§6.3)',
2076
- );
2077
- }
2078
- }
2079
-
2080
- async claimReactions(
2081
- partition: string,
2082
- query: ReactionClaimQuery,
2083
- ): Promise<StoredReaction[]> {
2084
- if (query.types.length === 0 || query.limit <= 0) return [];
2085
- if (query.types.length + 7 > D1_MAX_BIND_PARAMS) {
2086
- throw new Error('D1 reaction claim exceeds the bound-parameter limit');
2087
- }
2088
- const typeParams = query.types.map(() => '?').join(',');
2089
- const { results } = await this.#db
2090
- .prepare(
2091
- `UPDATE sync_reactions
2092
- SET status='leased', attempts=attempts+1,
2093
- lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
2094
- WHERE (partition, idempotency_key) IN (
2095
- SELECT partition, idempotency_key
2096
- FROM sync_reactions
2097
- WHERE partition=? AND type IN (${typeParams})
2098
- AND ((status='pending' AND available_at_ms<=?)
2099
- OR (status='leased' AND lease_expires_at_ms<=?))
2100
- ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
2101
- ELSE available_at_ms END,
2102
- created_at_ms, idempotency_key
2103
- LIMIT ?
2104
- )
2105
- RETURNING *`,
2106
- )
2107
- .bind(
2108
- query.leaseOwner,
2109
- Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs),
2110
- partition,
2111
- ...query.types,
2112
- query.nowMs,
2113
- query.nowMs,
2114
- query.limit,
2115
- )
2116
- .all<D1ReactionRecord>();
2117
- return results
2118
- .map(toStoredReaction)
2119
- .sort(
2120
- (a, b) =>
2121
- a.createdAtMs - b.createdAtMs ||
2122
- a.idempotencyKey.localeCompare(b.idempotencyKey),
2123
- );
2124
- }
2125
-
2126
- async completeReaction(
2127
- partition: string,
2128
- idempotencyKey: string,
2129
- leaseOwner: string,
2130
- completedAtMs: number,
2131
- ): Promise<boolean> {
2132
- const record = await this.#db
2133
- .prepare(
2134
- `UPDATE sync_reactions
2135
- SET status='completed', completed_at_ms=?,
2136
- lease_owner=NULL, lease_expires_at_ms=NULL
2137
- WHERE partition=? AND idempotency_key=?
2138
- AND status='leased' AND lease_owner=?
2139
- RETURNING idempotency_key`,
2140
- )
2141
- .bind(completedAtMs, partition, idempotencyKey, leaseOwner)
2142
- .first<{ idempotency_key: string }>();
2143
- return record !== null;
2144
- }
2145
-
2146
- async extendReactionLease(
2147
- partition: string,
2148
- idempotencyKey: string,
2149
- leaseOwner: string,
2150
- leaseExpiresAtMs: number,
2151
- ): Promise<boolean> {
2152
- const record = await this.#db
2153
- .prepare(
2154
- `UPDATE sync_reactions SET lease_expires_at_ms=?
2155
- WHERE partition=? AND idempotency_key=?
2156
- AND status='leased' AND lease_owner=?
2157
- RETURNING idempotency_key`,
2158
- )
2159
- .bind(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner)
2160
- .first<{ idempotency_key: string }>();
2161
- return record !== null;
2162
- }
2163
-
2164
- async failReaction(
2165
- partition: string,
2166
- idempotencyKey: string,
2167
- update: ReactionFailureUpdate,
2168
- ): Promise<boolean> {
2169
- const record = await this.#db
2170
- .prepare(
2171
- `UPDATE sync_reactions
2172
- SET status=?, available_at_ms=?, last_failure=?,
2173
- lease_owner=NULL, lease_expires_at_ms=NULL
2174
- WHERE partition=? AND idempotency_key=?
2175
- AND status='leased' AND lease_owner=?
2176
- RETURNING idempotency_key`,
2177
- )
2178
- .bind(
2179
- update.retryAtMs === undefined ? 'dead-letter' : 'pending',
2180
- update.retryAtMs ?? update.failure.atMs,
2181
- JSON.stringify(update.failure),
2182
- partition,
2183
- idempotencyKey,
2184
- update.leaseOwner,
2185
- )
2186
- .first<{ idempotency_key: string }>();
2187
- return record !== null;
2188
- }
2189
-
2190
- async retryReaction(
2191
- partition: string,
2192
- idempotencyKey: string,
2193
- nowMs: number,
2194
- ): Promise<boolean> {
2195
- const record = await this.#db
2196
- .prepare(
2197
- `UPDATE sync_reactions
2198
- SET status='pending', attempts=0, available_at_ms=?,
2199
- last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
2200
- completed_at_ms=NULL
2201
- WHERE partition=? AND idempotency_key=? AND status='dead-letter'
2202
- RETURNING idempotency_key`,
2203
- )
2204
- .bind(nowMs, partition, idempotencyKey)
2205
- .first<{ idempotency_key: string }>();
2206
- return record !== null;
2207
- }
2208
-
2209
- async getReaction(
2210
- partition: string,
2211
- idempotencyKey: string,
2212
- ): Promise<StoredReaction | undefined> {
2213
- const record = await this.#db
2214
- .prepare(
2215
- 'SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?',
2216
- )
2217
- .bind(partition, idempotencyKey)
2218
- .first<D1ReactionRecord>();
2219
- return record === null ? undefined : toStoredReaction(record);
2220
- }
2221
-
2222
- async listReactions(
2223
- partition: string,
2224
- query: ReactionListQuery,
2225
- ): Promise<StoredReaction[]> {
2226
- const where = ['partition=?'];
2227
- const params: (string | number)[] = [partition];
2228
- if (query.statuses !== undefined && query.statuses.length > 0) {
2229
- where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
2230
- params.push(...query.statuses);
2231
- }
2232
- if (query.types !== undefined && query.types.length > 0) {
2233
- where.push(`type IN (${query.types.map(() => '?').join(',')})`);
2234
- params.push(...query.types);
2235
- }
2236
- if (params.length + 1 > D1_MAX_BIND_PARAMS) {
2237
- throw new Error('D1 reaction list exceeds the bound-parameter limit');
2238
- }
2239
- params.push(query.limit);
2240
- const { results } = await this.#db
2241
- .prepare(
2242
- `SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
2243
- ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`,
2244
- )
2245
- .bind(...params)
2246
- .all<D1ReactionRecord>();
2247
- return results.map(toStoredReaction);
2248
- }
2249
-
2250
- async pruneReactions(
2251
- partition: string,
2252
- query: ReactionPruneQuery,
2253
- ): Promise<PrunedReactionCounts> {
2254
- if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
2255
- const { results } = await this.#db
2256
- .prepare(
2257
- `DELETE FROM sync_reactions
2258
- WHERE partition=? AND idempotency_key IN (
2259
- SELECT idempotency_key FROM sync_reactions
2260
- WHERE partition=?
2261
- AND ((status='completed' AND completed_at_ms IS NOT NULL
2262
- AND completed_at_ms<?)
2263
- OR (status='dead-letter' AND available_at_ms<?))
2264
- ORDER BY CASE WHEN status='completed' THEN completed_at_ms
2265
- ELSE available_at_ms END,
2266
- idempotency_key
2267
- LIMIT ?
2268
- )
2269
- AND ((status='completed' AND completed_at_ms IS NOT NULL
2270
- AND completed_at_ms<?)
2271
- OR (status='dead-letter' AND available_at_ms<?))
2272
- RETURNING status`,
2273
- )
2274
- .bind(
2275
- partition,
2276
- partition,
2277
- query.completedBeforeMs,
2278
- query.deadLetterBeforeMs,
2279
- query.limit,
2280
- query.completedBeforeMs,
2281
- query.deadLetterBeforeMs,
2282
- )
2283
- .all<{ status: 'completed' | 'dead-letter' }>();
2284
- return {
2285
- completed: results.filter((row) => row.status === 'completed').length,
2286
- deadLetter: results.filter((row) => row.status === 'dead-letter').length,
2287
- };
2288
- }
2289
-
2290
- async latestScopedChangeSeq(
2291
- partition: string,
2292
- query: { readonly table: string; readonly scopeFilter: ScopeMap },
2293
- ): Promise<number> {
2294
- const firstVariable = Object.keys(query.scopeFilter).sort()[0];
2295
- const values =
2296
- firstVariable === undefined
2297
- ? []
2298
- : (query.scopeFilter[firstVariable] ?? []);
2299
- if (firstVariable === undefined || values.length === 0) return 0;
2300
- // Concurrent reads of a pull share one `db.batch` round trip.
2301
- const [row] = await this.#batchedAll<{ seq: number | null }>(
2302
- LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
2303
- [partition, query.table, firstVariable, JSON.stringify(values)],
2304
- );
2305
- return row?.seq ?? 0;
2306
- }
2307
-
2308
- async readCommitWindow(
2309
- partition: string,
2310
- query: CommitWindowQuery,
2311
- ): Promise<StoredCommit[]> {
2312
- const variables = Object.keys(query.scopeFilter).sort();
2313
- const firstVariable = variables[0];
2314
- if (firstVariable === undefined) return [];
2315
- const firstValues = query.scopeFilter[firstVariable] ?? [];
2316
- if (firstValues.length === 0) return [];
2317
- // Candidates via the inverted index (one variable) LEFT JOINed to the
2318
- // commit meta + the table's changes — one statement per page, never two
2319
- // per candidate (see `commitWindowPageSql`), and concurrent pages share
2320
- // one D1 round trip. Exact multi-variable verification against the
2321
- // stored scope map in `collectCommitWindowPage`.
2322
- const sql = commitWindowPageSql(firstValues.length, 'sqlite');
2323
- const commits: StoredCommit[] = [];
2324
- let deliveredChanges = 0;
2325
- let afterSeq = query.afterSeq;
2326
- const batchSize = Math.max(64, query.limitChanges);
2327
- while (deliveredChanges < query.limitChanges) {
2328
- const records = await this.#batchedAll<SqliteCommitWindowRecord>(sql, [
2329
- partition,
2330
- query.table,
2331
- firstVariable,
2332
- ...firstValues,
2333
- afterSeq,
2334
- query.throughSeq,
2335
- batchSize,
2336
- partition,
2337
- partition,
2338
- query.table,
2339
- ]);
2340
- if (records.length === 0) break;
2341
- const page = collectCommitWindowPage(
2342
- records,
2343
- query.scopeFilter,
2344
- query.limitChanges - deliveredChanges,
2345
- );
2346
- commits.push(...page.commits);
2347
- deliveredChanges += page.delivered;
2348
- afterSeq = page.lastSeq;
2349
- if (page.candidateCount < batchSize) break;
2350
- }
2351
- return commits;
2352
- }
2353
-
2354
- async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
2355
- const firstVariable = assertScopeIndexedScan(query);
2356
- const firstValues = query.scopeFilter[firstVariable] ?? [];
2357
- if (firstValues.length === 0) return [];
2358
- // Candidates via the inverted index LEFT JOINed to the row table — one
2359
- // statement per page, never one per row (see `scanRowPageSql`), and
2360
- // concurrent pages share one D1 round trip.
2361
- // Exact multi-variable verification against the stored scope map below.
2362
- const sql = scanRowPageSql(
2363
- this.table(query.table),
2364
- firstValues.length,
2365
- 'sqlite',
2366
- );
2367
- const rows: StoredRow[] = [];
2368
- let afterRowId = query.afterRowId ?? '';
2369
- const batchSize = Math.max(64, query.limit);
2370
- while (rows.length < query.limit) {
2371
- const records = await this.#batchedAll<
2372
- SqliteRowRecord & { payload: Uint8Array | null }
2373
- >(sql, [
2374
- partition,
2375
- query.table,
2376
- firstVariable,
2377
- ...firstValues,
2378
- afterRowId,
2379
- batchSize,
2380
- partition,
2381
- ]);
2382
- if (records.length === 0) break;
2383
- for (const record of records) {
2384
- afterRowId = record.row_id;
2385
- // NULL payload: an index candidate whose row vanished — it still
2386
- // advances the keyset cursor (LEFT JOIN contract) but yields no row.
2387
- if (record.payload === null) continue;
2388
- const stored = toStoredRow(record);
2389
- if (!matchesEffective(stored.scopes, query.scopeFilter)) continue;
2390
- rows.push(stored);
2391
- if (rows.length >= query.limit) break;
2392
- }
2393
- if (records.length < batchSize) break;
2394
- }
2395
- return rows;
2396
- }
2397
-
2398
- async scanRowsByIndex(
2399
- partition: string,
2400
- query: IndexRowScanQuery,
2401
- ): Promise<StoredRow[]> {
2402
- const db = this.#schemaDatabase();
2403
- const table = this.table(query.table);
2404
- const index = resolveIndexRowScan(table, query);
2405
- const statement = indexRowPageStatement(
2406
- table,
2407
- index,
2408
- query.values,
2409
- partition,
2410
- query.afterRowId,
2411
- query.limit,
2412
- 'sqlite',
2413
- );
2414
- const { results } = await db
2415
- .prepare(statement.sql)
2416
- .bind(...statement.params)
2417
- .all<SqliteRowRecord>();
2418
- return results.map(toStoredRow);
2419
- }
2420
-
2421
- async getClientRecord(
2422
- partition: string,
2423
- clientId: string,
2424
- ): Promise<ClientRecord | undefined> {
2425
- const record = await this.#db
2426
- .prepare(
2427
- '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=?',
2428
- )
2429
- .bind(partition, clientId)
2430
- .first<{
2431
- client_id: string;
2432
- actor_id: string;
2433
- wire_version: number;
2434
- cursor: number;
2435
- subscriptions: string;
2436
- updated_at_ms: number;
2437
- last_round_at_ms: number | null;
2438
- last_error_code: string | null;
2439
- consecutive_failures: number;
2440
- }>();
2441
- if (record === null) return undefined;
2442
- return {
2443
- clientId: record.client_id,
2444
- actorId: record.actor_id,
2445
- wireVersion: record.wire_version,
2446
- cursor: record.cursor,
2447
- updatedAtMs: record.updated_at_ms,
2448
- subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
2449
- ...clientRoundState(
2450
- record.last_round_at_ms,
2451
- record.last_error_code,
2452
- record.consecutive_failures,
2453
- ),
2454
- };
2455
- }
2456
-
2457
- async putClientRecord(
2458
- partition: string,
2459
- record: ClientRecord,
2460
- options?: ClientRecordWriteOptions,
2461
- ): Promise<void> {
2462
- // Update the existing record in place, so the table keeps one row per
2463
- // (partition, client_id). Every non-key field is written from the new
2464
- // record; a delete-and-insert would drop and recreate the row instead.
2465
- // `keepRoundOutcome` leaves the round-state columns alone (§1.5, §4.5).
2466
- await this.#db
2467
- .prepare(
2468
- `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
2469
- ON CONFLICT(partition, client_id) DO UPDATE SET
2470
- actor_id=excluded.actor_id,
2471
- wire_version=excluded.wire_version,
2472
- cursor=excluded.cursor,
2473
- subscriptions=excluded.subscriptions,
2474
- updated_at_ms=excluded.updated_at_ms,
2475
- last_round_at_ms=excluded.last_round_at_ms${
2476
- options?.keepRoundOutcome === true
2477
- ? ''
2478
- : `,
2479
- last_error_code=NULL,
2480
- consecutive_failures=0`
2481
- }`,
2482
- )
2483
- .bind(
2484
- partition,
2485
- record.clientId,
2486
- record.actorId,
2487
- record.wireVersion,
2488
- record.cursor,
2489
- JSON.stringify(record.subscriptions),
2490
- record.updatedAtMs,
2491
- record.updatedAtMs,
2492
- )
2493
- .run();
2494
- }
2495
-
2496
- async recordClientRoundFailure(
2497
- partition: string,
2498
- clientId: string,
2499
- actorId: string,
2500
- errorCode: string,
2501
- atMs: number,
2502
- ): Promise<void> {
2503
- await this.#db
2504
- .prepare(
2505
- `UPDATE sync_clients
2506
- SET last_round_at_ms=?, last_error_code=?,
2507
- consecutive_failures=consecutive_failures+1
2508
- WHERE partition=? AND client_id=? AND actor_id=?`,
2509
- )
2510
- .bind(atMs, errorCode, partition, clientId, actorId)
2511
- .run();
2512
- }
2513
-
2514
- async advanceClientCursor(
2515
- partition: string,
2516
- clientId: string,
2517
- actorId: string,
2518
- logEpoch: string,
2519
- cursor: number,
2520
- updatedAtMs: number,
2521
- ): Promise<void> {
2522
- await this.#db
2523
- .prepare(`UPDATE sync_clients
2524
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
2525
- WHERE partition=? AND client_id=? AND actor_id=?
2526
- AND EXISTS (SELECT 1 FROM sync_partition_registry
2527
- WHERE partition=sync_clients.partition AND log_epoch=?)`)
2528
- .bind(cursor, updatedAtMs, partition, clientId, actorId, logEpoch)
2529
- .run();
2530
- }
2531
-
2532
- async updateClientCursor(
2533
- partition: string,
2534
- clientId: string,
2535
- cursor: number,
2536
- updatedAtMs: number,
2537
- ): Promise<void> {
2538
- await this.#db
2539
- .prepare(
2540
- `UPDATE sync_clients
2541
- SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
2542
- WHERE partition=? AND client_id=?`,
2543
- )
2544
- .bind(cursor, updatedAtMs, partition, clientId)
2545
- .run();
2546
- }
2547
-
2548
- async getActiveClientCursorFloor(
2549
- partition: string,
2550
- cutoffMs: number,
2551
- ): Promise<number | null> {
2552
- const row = await this.#db
2553
- .prepare(
2554
- 'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?',
2555
- )
2556
- .bind(partition, cutoffMs)
2557
- .first<{ cursor: number | null }>();
2558
- return row!.cursor;
2559
- }
2560
-
2561
- async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
2562
- const { results } = await this.#db
2563
- .prepare(
2564
- 'SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?',
2565
- )
2566
- .bind(partition)
2567
- .all<{ client_id: string; cursor: number; updated_at_ms: number }>();
2568
- return results.map((r) => ({
2569
- clientId: r.client_id,
2570
- cursor: r.cursor,
2571
- updatedAtMs: r.updated_at_ms,
2572
- }));
2573
- }
2574
-
2575
- async listRowsReferencingBlob(
2576
- partition: string,
2577
- blobId: string,
2578
- ): Promise<
2579
- {
2580
- readonly table: string;
2581
- readonly rowId: string;
2582
- readonly scopes: Record<string, string>;
2583
- }[]
2584
- > {
2585
- const db = this.#schemaDatabase();
2586
- const { results: refs } = await db
2587
- .prepare(
2588
- 'SELECT tbl, row_id FROM sync_blob_refs WHERE partition=? AND blob_id=?',
2589
- )
2590
- .bind(partition, blobId)
2591
- .all<{ tbl: string; row_id: string }>();
2592
- const out: {
2593
- table: string;
2594
- rowId: string;
2595
- scopes: Record<string, string>;
2596
- }[] = [];
2597
- for (const ref of refs) {
2598
- const compiled = this.#tables?.get(ref.tbl);
2599
- if (compiled === undefined) continue; // table no longer in the schema
2600
- const row = await db
2601
- .prepare(selectRowScopesSql(compiled, 'sqlite'))
2602
- .bind(partition, ref.row_id)
2603
- .first<{ scopes: string }>();
2604
- if (row === null) continue;
2605
- out.push({
2606
- table: ref.tbl,
2607
- rowId: ref.row_id,
2608
- scopes: JSON.parse(row.scopes) as Record<string, string>,
2609
- });
2610
- }
2611
- return out;
2612
- }
2613
-
2614
- async listReferencedBlobIds(partition: string): Promise<string[]> {
2615
- const { results } = await this.#db
2616
- .prepare('SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=?')
2617
- .bind(partition)
2618
- .all<{ blob_id: string }>();
2619
- return results.map((r) => r.blob_id);
2620
- }
2621
-
2622
- async listScopeValueRows(
2623
- partition: string,
2624
- query: ScopeValueQuery,
2625
- ): Promise<string[]> {
2626
- const { results } = await this.#db
2627
- .prepare(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
2628
- .bind(partition, query.table, query.variable, query.value, query.limit)
2629
- .all<{ row_id: string }>();
2630
- return results.map((row) => row.row_id);
2631
- }
2632
-
2633
- async eraseScopeValueHistory(
1588
+ override async eraseScopeValueHistory(
2634
1589
  partition: string,
2635
1590
  query: ScopeValueHistoryQuery,
2636
1591
  ): Promise<number> {
@@ -2638,327 +1593,6 @@ export class D1ServerStorage implements ServerStorage {
2638
1593
  throw new Error(
2639
1594
  'D1 erasure requires externally serialized partition writes',
2640
1595
  );
2641
- const params = eraseScopeValueHistoryParams(partition, query);
2642
- const results = await this.#db.batch(
2643
- ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL.map((sql) =>
2644
- this.#db.prepare(sql).bind(...params),
2645
- ),
2646
- );
2647
- let removed = 0;
2648
- for (const result of results) {
2649
- if (
2650
- typeof result !== 'object' ||
2651
- result === null ||
2652
- !('results' in result) ||
2653
- !Array.isArray(result.results)
2654
- ) {
2655
- throw new Error('D1 erasure returned an invalid batch result');
2656
- }
2657
- removed += result.results.length;
2658
- }
2659
- return removed;
2660
- }
2661
-
2662
- // -- admin/console read surface --------------------------------------------
2663
-
2664
- async listClientRecords(partition: string): Promise<ClientRecord[]> {
2665
- const { results } = await this.#db
2666
- .prepare(
2667
- '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',
2668
- )
2669
- .bind(partition)
2670
- .all<{
2671
- client_id: string;
2672
- actor_id: string;
2673
- wire_version: number;
2674
- cursor: number;
2675
- subscriptions: string;
2676
- updated_at_ms: number;
2677
- last_round_at_ms: number | null;
2678
- last_error_code: string | null;
2679
- consecutive_failures: number;
2680
- }>();
2681
- return results.map((record) => ({
2682
- clientId: record.client_id,
2683
- actorId: record.actor_id,
2684
- wireVersion: record.wire_version,
2685
- cursor: record.cursor,
2686
- updatedAtMs: record.updated_at_ms,
2687
- subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
2688
- ...clientRoundState(
2689
- record.last_round_at_ms,
2690
- record.last_error_code,
2691
- record.consecutive_failures,
2692
- ),
2693
- }));
2694
- }
2695
-
2696
- async listCommitMetadata(
2697
- partition: string,
2698
- query: CommitMetadataQuery,
2699
- ): Promise<CommitMetadata[]> {
2700
- // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
2701
- // ended by `beforeSeq` (exclusive upper bound) when paging older. An
2702
- // omitted bound is the largest safe commitSeq, so one statement serves
2703
- // both the bounded and unbounded read.
2704
- const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
2705
- const { results: rows } = query.table
2706
- ? await this.#db
2707
- .prepare(
2708
- `SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
2709
- FROM sync_commits c
2710
- WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
2711
- AND EXISTS (SELECT 1 FROM sync_changes ch
2712
- WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
2713
- ORDER BY c.commit_seq DESC LIMIT ?`,
2714
- )
2715
- .bind(partition, query.afterSeq, beforeSeq, query.table, query.limit)
2716
- .all<{
2717
- commit_seq: number;
2718
- client_id: string;
2719
- client_commit_id: string;
2720
- actor_id: string;
2721
- created_at_ms: number;
2722
- }>()
2723
- : await this.#db
2724
- .prepare(
2725
- `SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
2726
- FROM sync_commits
2727
- WHERE partition=? AND commit_seq>? AND commit_seq<?
2728
- ORDER BY commit_seq DESC LIMIT ?`,
2729
- )
2730
- .bind(partition, query.afterSeq, beforeSeq, query.limit)
2731
- .all<{
2732
- commit_seq: number;
2733
- client_id: string;
2734
- client_commit_id: string;
2735
- actor_id: string;
2736
- created_at_ms: number;
2737
- }>();
2738
- const out: CommitMetadata[] = [];
2739
- // `changeSample`: extra statement(s) for the whole page — the first
2740
- // `sample` changes (change-index order) of every listed commit.
2741
- const sampleCount =
2742
- query.changeSample !== undefined &&
2743
- Number.isInteger(query.changeSample) &&
2744
- query.changeSample > 0
2745
- ? query.changeSample
2746
- : 0;
2747
- const samples = new Map<number, CommitChangeSummary[]>();
2748
- if (sampleCount > 0 && rows.length > 0) {
2749
- const seqs = rows.map((row) => row.commit_seq);
2750
- // D1 caps the bound parameters of one statement, so a page larger than
2751
- // that cap splits into a few chunk statements, never one per commit.
2752
- const chunkSize = D1_MAX_BIND_PARAMS - 2;
2753
- for (let offset = 0; offset < seqs.length; offset += chunkSize) {
2754
- const chunk = seqs.slice(offset, offset + chunkSize);
2755
- const { results: changes } = await this.#db
2756
- .prepare(
2757
- `SELECT commit_seq, tbl, row_id, op FROM sync_changes
2758
- WHERE partition=? AND commit_seq IN (${placeholders(chunk.length)}) AND idx<?
2759
- ORDER BY commit_seq, idx`,
2760
- )
2761
- .bind(partition, ...chunk, sampleCount)
2762
- .all<{
2763
- commit_seq: number;
2764
- tbl: string;
2765
- row_id: string;
2766
- op: number;
2767
- }>();
2768
- for (const change of changes) {
2769
- const sample = samples.get(change.commit_seq) ?? [];
2770
- sample.push({
2771
- table: change.tbl,
2772
- rowId: change.row_id,
2773
- op: change.op === 1 ? 'upsert' : 'delete',
2774
- });
2775
- samples.set(change.commit_seq, sample);
2776
- }
2777
- }
2778
- }
2779
- for (const row of rows) {
2780
- const { results: changes } = await this.#db
2781
- .prepare(
2782
- 'SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? GROUP BY tbl',
2783
- )
2784
- .bind(partition, row.commit_seq)
2785
- .all<{ tbl: string; n: number }>();
2786
- out.push({
2787
- commitSeq: row.commit_seq,
2788
- clientId: row.client_id,
2789
- clientCommitId: row.client_commit_id,
2790
- actorId: row.actor_id,
2791
- createdAtMs: row.created_at_ms,
2792
- changeCount: changes.reduce((sum, c) => sum + c.n, 0),
2793
- tables: changes.map((c) => c.tbl),
2794
- ...(sampleCount > 0
2795
- ? { sample: samples.get(row.commit_seq) ?? [] }
2796
- : {}),
2797
- });
2798
- }
2799
- return out;
2800
- }
2801
-
2802
- async getCommit(
2803
- partition: string,
2804
- commitSeq: number,
2805
- ): Promise<CommitDetail | undefined> {
2806
- const meta = await this.#db
2807
- .prepare(
2808
- 'SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
2809
- )
2810
- .bind(partition, commitSeq)
2811
- .first<{
2812
- client_id: string;
2813
- client_commit_id: string;
2814
- actor_id: string;
2815
- created_at_ms: number;
2816
- }>();
2817
- if (meta === null) return undefined;
2818
- const { results: changeRows } = await this.#db
2819
- .prepare(
2820
- 'SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx',
2821
- )
2822
- .bind(partition, commitSeq)
2823
- .all<SqliteChangeRecord>();
2824
- const changes = changeRows.map(toStoredChange);
2825
- return {
2826
- commitSeq,
2827
- clientId: meta.client_id,
2828
- clientCommitId: meta.client_commit_id,
2829
- actorId: meta.actor_id,
2830
- createdAtMs: meta.created_at_ms,
2831
- changeCount: changes.length,
2832
- tables: [...new Set(changes.map((change) => change.table))].sort(),
2833
- changes,
2834
- };
2835
- }
2836
-
2837
- async listRowChanges(
2838
- partition: string,
2839
- query: RowChangesQuery,
2840
- ): Promise<RowChangeRecord[]> {
2841
- // Retained-log read for one row: no dedicated index (the write path pays
2842
- // nothing for it), bounded by retention (§4.6).
2843
- const { results: rows } = await this.#db
2844
- .prepare(
2845
- `SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
2846
- FROM sync_changes ch
2847
- JOIN sync_commits c
2848
- ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
2849
- WHERE ch.partition=? AND ch.tbl=? AND ch.row_id=?
2850
- ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`,
2851
- )
2852
- .bind(partition, query.table, query.rowId, query.limit)
2853
- .all<{
2854
- commit_seq: number;
2855
- op: number;
2856
- row_version: number | null;
2857
- actor_id: string;
2858
- client_id: string;
2859
- created_at_ms: number;
2860
- }>();
2861
- return rows.map((row) => ({
2862
- commitSeq: row.commit_seq,
2863
- op: row.op === 1 ? 'upsert' : 'delete',
2864
- ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
2865
- actorId: row.actor_id,
2866
- clientId: row.client_id,
2867
- createdAtMs: row.created_at_ms,
2868
- }));
2869
- }
2870
-
2871
- async listRows(partition: string, query: RowListQuery): Promise<StoredRow[]> {
2872
- // Keyset page over the row table's (partition, rowId) primary key: an
2873
- // index range read, no scope filter, no per-row lookup.
2874
- const { results } = await this.#schemaDatabase()
2875
- .prepare(
2876
- `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
2877
- FROM ${quoteIdent(this.table(query.table).name)}
2878
- WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
2879
- ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`,
2880
- )
2881
- .bind(partition, query.afterRowId ?? '', query.limit)
2882
- .all<SqliteRowRecord>();
2883
- return results.map(toStoredRow);
2884
- }
2885
-
2886
- async countRows(partition: string, table: string): Promise<number> {
2887
- const record = await this.#schemaDatabase()
2888
- .prepare(
2889
- `SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`,
2890
- )
2891
- .bind(partition)
2892
- .first<{ n: number }>();
2893
- return record?.n ?? 0;
2894
- }
2895
-
2896
- async listPushResults(
2897
- partition: string,
2898
- clientCommitId: string,
2899
- ): Promise<ClientPushResult[]> {
2900
- // Retained outcomes for one clientCommitId: no dedicated index, ordered
2901
- // by client so the read is deterministic.
2902
- const { results } = await this.#schemaDatabase()
2903
- .prepare(
2904
- 'SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id',
2905
- )
2906
- .bind(partition, clientCommitId)
2907
- .all<{ client_id: string; result: string }>();
2908
- return results.map((record) => {
2909
- try {
2910
- return {
2911
- clientId: record.client_id,
2912
- result: deserializePushResult(record.result),
2913
- };
2914
- } catch {
2915
- throw syncError(
2916
- 'sync.idempotency_cache_miss',
2917
- 'persisted push result unreadable (§6.3)',
2918
- );
2919
- }
2920
- });
2921
- }
2922
-
2923
- async scopeActivity(
2924
- partition: string,
2925
- query: ScopeActivityQuery,
2926
- ): Promise<ScopeCommitActivity[]> {
2927
- const { results: rows } = await this.#db
2928
- .prepare(
2929
- `SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
2930
- WHERE partition=? AND var=? AND value=?
2931
- ORDER BY commit_seq DESC LIMIT ?`,
2932
- )
2933
- .bind(partition, query.variable, query.value, query.limit)
2934
- .all<{ commit_seq: number; tbl: string }>();
2935
- const out: ScopeCommitActivity[] = [];
2936
- for (const row of rows) {
2937
- const meta = await this.#db
2938
- .prepare(
2939
- 'SELECT actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
2940
- )
2941
- .bind(partition, row.commit_seq)
2942
- .first<{ actor_id: string; created_at_ms: number }>();
2943
- if (meta === null) continue;
2944
- const count = await this.#db
2945
- .prepare(
2946
- 'SELECT count(*) AS n FROM sync_changes WHERE partition=? AND commit_seq=? AND tbl=?',
2947
- )
2948
- .bind(partition, row.commit_seq, row.tbl)
2949
- .first<{ n: number }>();
2950
- out.push({
2951
- commitSeq: row.commit_seq,
2952
- table: row.tbl,
2953
- createdAtMs: meta.created_at_ms,
2954
- actorId: meta.actor_id,
2955
- changeCount: count?.n ?? 0,
2956
- });
2957
- }
2958
- return out;
2959
- }
2960
-
2961
- async listPartitions(): Promise<string[]> {
2962
- return (await this.listPartitionRegistry()).map((entry) => entry.partition);
1596
+ return super.eraseScopeValueHistory(partition, query);
2963
1597
  }
2964
1598
  }