@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,29 +1,96 @@
1
1
  /**
2
2
  * Shared SQLite dialect for synchronous `SqliteServerStorage` on Bun or Node
3
3
  * and asynchronous `D1ServerStorage` on Cloudflare Workers. D1 is SQLite:
4
- * same DDL, same statement grammar,
5
- * same `?` positional placeholders, same `INSERT ... ON CONFLICT` / `INSERT
6
- * OR IGNORE` upsert idioms — so the schema and the value (de)serialization are
7
- * genuinely common ground and live here.
4
+ * same DDL, same statement grammar, same `?` positional placeholders, same
5
+ * `INSERT ... ON CONFLICT` / `INSERT OR IGNORE` upsert idioms.
8
6
  *
9
- * What is not shared: statement execution. The server SQLite driver is sync
10
- * (`db.query(sql).get(...)`) and D1 is async (`await
11
- * db.prepare(sql).bind(...).all()`); a shared execution layer would have to
12
- * pick one calling convention and adapt the other, which is uglier than two
13
- * thin storage classes that each speak their driver's native shape while
14
- * importing the same SQL text and codecs from here.
15
- * Both classes run the identical `test/storage-contract.ts`, so the
16
- * behavior is held key-for-key regardless.
7
+ * `SqliteFamilyStorage` and `SqliteFamilyTransaction` hold every statement
8
+ * and row mapping the two backends share. A backend supplies statement
9
+ * execution through a small seam (`all`, `guardedAll`, `atomic`; `run` and
10
+ * `all` inside a transaction) and keeps only what differs: connection
11
+ * handling, the request lock in SQLite, transaction execution (interactive
12
+ * `BEGIN IMMEDIATE` in SQLite, one buffered `db.batch` in D1), D1's
13
+ * bound-parameter cap and its published-schema guard. The seam returns
14
+ * promises; the synchronous SQLite driver resolves them with rows it read at
15
+ * call time. Both classes run the identical `test/storage-contract.ts`.
17
16
  */
18
17
  import type { PushOperationResult, ScopeMap } from '@syncular/core';
18
+ import {
19
+ bindAuthoritativePartition,
20
+ type BoundAuthoritativeQuery,
21
+ prepareAuthoritativeQuery,
22
+ } from './authoritative-query';
23
+ import { syncError } from './errors';
24
+ import { validateCommitPruneQuery } from './prune';
25
+ import { StorageQueryError } from './storage-errors';
26
+ import {
27
+ deleteRowSql,
28
+ deleteSqliteRowScopesSql,
29
+ indexRowPageStatement,
30
+ quoteIdent,
31
+ scanRowPageSql,
32
+ rowsReferencingBlobSql,
33
+ selectRowSql,
34
+ SYNC_COLUMN_VERSIONS_COLUMN,
35
+ SYNC_PARTITION_COLUMN,
36
+ SYNC_PAYLOAD_COLUMN,
37
+ SYNC_ROW_ID_COLUMN,
38
+ SYNC_SCOPES_COLUMN,
39
+ SYNC_VERSION_COLUMN,
40
+ commitWindowPageSql,
41
+ LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
42
+ upsertSql,
43
+ upsertValues,
44
+ } from './relational-rows';
45
+ import type { CompiledTable } from './schema';
19
46
  import { matchesEffective } from './scopes';
47
+ import type { SqliteValue } from './sqlite-driver';
48
+ import {
49
+ clientRoundState,
50
+ PARTITION_TOUCH_INTERVAL_MS,
51
+ rowsLiveAfterDelete,
52
+ } from './storage';
20
53
  import type {
54
+ AuthoritativeQueryRequest,
55
+ ClientCursorInfo,
56
+ ClientPushResult,
57
+ ClientRecord,
58
+ ClientRecordWriteOptions,
59
+ ClientSubscription,
60
+ CommitChangeSummary,
61
+ CommitDetail,
62
+ CommitMetadata,
63
+ CommitMetadataQuery,
64
+ CommitPruneQuery,
65
+ CommitPruneResult,
66
+ CommitWindowQuery,
67
+ DurableJsonValue,
68
+ IndexRowScanQuery,
69
+ NewCommit,
70
+ NewReaction,
71
+ PartitionRegistryEntry,
72
+ PrunedReactionCounts,
73
+ ReactionClaimQuery,
74
+ ReactionFailure,
75
+ ReactionFailureUpdate,
76
+ ReactionListQuery,
77
+ ReactionPruneQuery,
78
+ RowChangeRecord,
79
+ RowChangesQuery,
80
+ RowListQuery,
81
+ RowScanQuery,
82
+ ScopeActivityQuery,
83
+ ScopeCommitActivity,
21
84
  ScopeValueHistoryQuery,
85
+ ScopeValueQuery,
22
86
  StoredChange,
23
87
  StoredCommit,
24
88
  StoredPushResult,
89
+ StoredReaction,
25
90
  StoredRow,
91
+ Tombstone,
26
92
  } from './storage';
93
+ import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
27
94
 
28
95
  /**
29
96
  * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
@@ -38,11 +105,15 @@ import type {
38
105
  * the Postgres storage documents (§3.1, performance-by-
39
106
  * construction).
40
107
  *
41
- * `sync_row_scopes_by_row` is the one secondary scope index: a per-row
42
- * scope replacement predicates on `(partition, tbl, row_id)`, and `row_id`
43
- * is the LAST PRIMARY KEY column, so that predicate cannot narrow the
44
- * inverted index. Declared here so every SQLite-family storage (and D1,
45
- * which applies this same DDL) keeps the same plan shape as Postgres.
108
+ * The old `sync_row_scopes_by_row` index is dropped: with it present the
109
+ * planner answered a scope scan of two or more values by walking the index
110
+ * in `row_id` order and filtering, instead of seeking the PRIMARY KEY once
111
+ * per value. The per-row scope replacement (`deleteSqliteRowScopesSql`)
112
+ * binds `(partition, tbl, var, value, row_id)` and needs no secondary index.
113
+ * `DROP INDEX IF EXISTS` stays in the DDL so existing databases lose the
114
+ * index the next time the DDL runs: on every `SqliteServerStorage`
115
+ * construction, and on D1 in `migrate()` and the core phase of
116
+ * `migrateSchema`.
46
117
  */
47
118
  export const SQLITE_DDL = `
48
119
  CREATE TABLE IF NOT EXISTS sync_partitions(
@@ -61,8 +132,7 @@ CREATE TABLE IF NOT EXISTS sync_row_scopes(
61
132
  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
62
133
  PRIMARY KEY(partition, tbl, var, value, row_id)
63
134
  );
64
- CREATE INDEX IF NOT EXISTS sync_row_scopes_by_row
65
- ON sync_row_scopes(partition, tbl, row_id);
135
+ DROP INDEX IF EXISTS sync_row_scopes_by_row;
66
136
  CREATE TABLE IF NOT EXISTS sync_commits(
67
137
  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,
68
138
  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
@@ -128,7 +198,7 @@ CREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob
128
198
  ON sync_blob_refs(partition, blob_id);
129
199
  CREATE TABLE IF NOT EXISTS sync_tombstones(
130
200
  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
131
- commit_seq INTEGER NOT NULL,
201
+ commit_seq INTEGER NOT NULL, server_version INTEGER, scopes TEXT,
132
202
  PRIMARY KEY(partition, tbl, row_id)
133
203
  );
134
204
  CREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(
@@ -147,12 +217,15 @@ CREATE TABLE IF NOT EXISTS sync_writer_fence(
147
217
  );
148
218
  `;
149
219
 
150
- /** Columns added to `sync_clients` after its first release, by column name. */
151
- export const SYNC_CLIENT_ROUND_COLUMNS = {
152
- last_round_at_ms: 'INTEGER',
153
- last_error_code: 'TEXT',
154
- consecutive_failures: 'INTEGER NOT NULL DEFAULT 0',
155
- } as const;
220
+ /** Columns added to core tables after their first release: table, column, type. */
221
+ export const SQLITE_ADDED_COLUMNS = [
222
+ ['sync_clients', 'wire_version', 'INTEGER NOT NULL DEFAULT 1'],
223
+ ['sync_clients', 'last_round_at_ms', 'INTEGER'],
224
+ ['sync_clients', 'last_error_code', 'TEXT'],
225
+ ['sync_clients', 'consecutive_failures', 'INTEGER NOT NULL DEFAULT 0'],
226
+ ['sync_tombstones', 'server_version', 'INTEGER'],
227
+ ['sync_tombstones', 'scopes', 'TEXT'],
228
+ ] as const;
156
229
 
157
230
  /** Split the DDL into individual statements (D1 applies them one by one). */
158
231
  export function sqliteDdlStatements(): string[] {
@@ -161,48 +234,6 @@ export function sqliteDdlStatements(): string[] {
161
234
  .filter((statement) => statement.length > 0);
162
235
  }
163
236
 
164
- /** §4.6.1: rowIds of one table bound to one scope value, budgeted. */
165
- export const LIST_SCOPE_VALUE_ROWS_SQLITE_SQL =
166
- 'SELECT row_id FROM sync_row_scopes WHERE partition=? AND tbl=? AND var=? AND value=? ORDER BY row_id LIMIT ?';
167
-
168
- /**
169
- * §4.6.1 history scrub, bound by `eraseScopeValueHistoryParams`: upsert change
170
- * records of the binding first, then the change scope entries whose commit
171
- * no longer holds a change of the binding. Each returns one row per removed
172
- * record (D1 batch results carry no reliable change count).
173
- */
174
- export const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL = [
175
- `DELETE FROM sync_changes WHERE rowid IN (
176
- SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c
177
- ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl
178
- WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
179
- AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value
180
- LIMIT ?7) RETURNING 1 AS removed`,
181
- `DELETE FROM sync_change_scopes WHERE rowid IN (
182
- SELECT s.rowid FROM sync_change_scopes s
183
- WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
184
- AND s.commit_seq<=?5 AND NOT EXISTS (
185
- SELECT 1 FROM sync_changes c
186
- WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
187
- AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)
188
- LIMIT ?7) RETURNING 1 AS removed`,
189
- ] as const;
190
-
191
- export function eraseScopeValueHistoryParams(
192
- partition: string,
193
- query: ScopeValueHistoryQuery,
194
- ): [string, string, string, string, number, string, number] {
195
- return [
196
- partition,
197
- query.table,
198
- query.variable,
199
- query.value,
200
- query.throughSeq,
201
- `$.${JSON.stringify(query.variable)}`,
202
- query.limit,
203
- ];
204
- }
205
-
206
237
  /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
207
238
  export function placeholders(count: number): string {
208
239
  return new Array(count).fill('?').join(',');
@@ -277,53 +308,63 @@ export function serializePushResult(result: StoredPushResult): string {
277
308
  });
278
309
  }
279
310
 
311
+ /** Parse a stored push result; an unreadable record is a §6.3 cache miss. */
280
312
  export function deserializePushResult(text: string): StoredPushResult {
281
- const parsed = JSON.parse(text) as {
282
- status: 'applied' | 'rejected';
283
- commitSeq?: number;
284
- recordedAtMs?: number;
285
- cacheIdentity?: string;
286
- conflictAuthorization?: StoredPushResult['conflictAuthorization'];
287
- results: SerializedResult[];
288
- };
289
- const results: PushOperationResult[] = parsed.results.map((record) => {
290
- if (record.status === 'conflict') {
291
- return {
292
- opIndex: record.opIndex,
293
- status: 'conflict',
294
- code: record.code ?? '',
295
- message: record.message ?? '',
296
- serverVersion: record.serverVersion ?? 0,
297
- serverRow: base64ToBytes(record.serverRow ?? ''),
298
- conflictColumns: base64ToBytes(record.conflictColumns ?? ''),
299
- };
300
- }
301
- if (record.status === 'error') {
302
- return {
303
- opIndex: record.opIndex,
304
- status: 'error',
305
- code: record.code ?? '',
306
- message: record.message ?? '',
307
- retryable: record.retryable ?? false,
308
- ...(record.details !== undefined ? { details: record.details } : {}),
309
- };
310
- }
311
- return { opIndex: record.opIndex, status: 'applied' };
312
- });
313
- return {
314
- status: parsed.status,
315
- ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
316
- ...(parsed.recordedAtMs !== undefined
317
- ? { recordedAtMs: parsed.recordedAtMs }
318
- : {}),
319
- ...(parsed.cacheIdentity !== undefined
320
- ? { cacheIdentity: parsed.cacheIdentity }
321
- : {}),
322
- ...(parsed.conflictAuthorization !== undefined
323
- ? { conflictAuthorization: parsed.conflictAuthorization }
324
- : {}),
325
- results,
326
- };
313
+ try {
314
+ const parsed = JSON.parse(text) as {
315
+ status: 'applied' | 'rejected';
316
+ commitSeq?: number;
317
+ recordedAtMs?: number;
318
+ cacheIdentity?: string;
319
+ conflictAuthorization?: StoredPushResult['conflictAuthorization'];
320
+ results: SerializedResult[];
321
+ };
322
+ const results: PushOperationResult[] = parsed.results.map((record) => {
323
+ if (record.status === 'conflict') {
324
+ return {
325
+ opIndex: record.opIndex,
326
+ status: 'conflict',
327
+ code: record.code ?? '',
328
+ message: record.message ?? '',
329
+ serverVersion: record.serverVersion ?? 0,
330
+ serverRow: base64ToBytes(record.serverRow ?? ''),
331
+ conflictColumns: base64ToBytes(record.conflictColumns ?? ''),
332
+ };
333
+ }
334
+ if (record.status === 'error') {
335
+ return {
336
+ opIndex: record.opIndex,
337
+ status: 'error',
338
+ code: record.code ?? '',
339
+ message: record.message ?? '',
340
+ retryable: record.retryable ?? false,
341
+ ...(record.details !== undefined ? { details: record.details } : {}),
342
+ };
343
+ }
344
+ return { opIndex: record.opIndex, status: 'applied' };
345
+ });
346
+ return {
347
+ status: parsed.status,
348
+ ...(parsed.commitSeq !== undefined
349
+ ? { commitSeq: parsed.commitSeq }
350
+ : {}),
351
+ ...(parsed.recordedAtMs !== undefined
352
+ ? { recordedAtMs: parsed.recordedAtMs }
353
+ : {}),
354
+ ...(parsed.cacheIdentity !== undefined
355
+ ? { cacheIdentity: parsed.cacheIdentity }
356
+ : {}),
357
+ ...(parsed.conflictAuthorization !== undefined
358
+ ? { conflictAuthorization: parsed.conflictAuthorization }
359
+ : {}),
360
+ results,
361
+ };
362
+ } catch {
363
+ throw syncError(
364
+ 'sync.idempotency_cache_miss',
365
+ 'persisted push result unreadable (§6.3)',
366
+ );
367
+ }
327
368
  }
328
369
 
329
370
  /** Row-record shape the SQLite `SELECT`s in both storages return. */
@@ -364,6 +405,24 @@ export function toStoredRow(record: SqliteRowRecord): StoredRow {
364
405
  };
365
406
  }
366
407
 
408
+ export interface SqliteTombstoneRecord {
409
+ commit_seq: number;
410
+ server_version: number | null;
411
+ scopes: string | null;
412
+ }
413
+
414
+ export function toTombstone(record: SqliteTombstoneRecord): Tombstone {
415
+ return {
416
+ commitSeq: record.commit_seq,
417
+ ...(record.server_version !== null
418
+ ? { serverVersion: record.server_version }
419
+ : {}),
420
+ ...(record.scopes !== null
421
+ ? { scopes: JSON.parse(record.scopes) as Record<string, string> }
422
+ : {}),
423
+ };
424
+ }
425
+
367
426
  export function toStoredChange(record: SqliteChangeRecord): StoredChange {
368
427
  return {
369
428
  table: record.tbl,
@@ -472,3 +531,1437 @@ export function collectCommitWindowPage(
472
531
  }
473
532
  return { commits, delivered, lastSeq, candidateCount };
474
533
  }
534
+
535
+ interface SqliteReactionRecord {
536
+ idempotency_key: string;
537
+ type: string;
538
+ version: number;
539
+ payload: string;
540
+ source_client_id: string;
541
+ source_client_commit_id: string;
542
+ source_commit_seq: number;
543
+ created_at_ms: number;
544
+ available_at_ms: number;
545
+ status: StoredReaction['status'];
546
+ attempts: number;
547
+ max_attempts: number;
548
+ lease_owner: string | null;
549
+ lease_expires_at_ms: number | null;
550
+ completed_at_ms: number | null;
551
+ last_failure: string | null;
552
+ }
553
+
554
+ function toStoredReaction(record: SqliteReactionRecord): StoredReaction {
555
+ return {
556
+ idempotencyKey: record.idempotency_key,
557
+ type: record.type,
558
+ version: record.version,
559
+ payload: JSON.parse(record.payload) as DurableJsonValue,
560
+ sourceClientId: record.source_client_id,
561
+ sourceClientCommitId: record.source_client_commit_id,
562
+ sourceCommitSeq: record.source_commit_seq,
563
+ createdAtMs: record.created_at_ms,
564
+ maxAttempts: record.max_attempts,
565
+ status: record.status,
566
+ attempts: record.attempts,
567
+ availableAtMs: record.available_at_ms,
568
+ ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
569
+ ...(record.lease_expires_at_ms !== null
570
+ ? { leaseExpiresAtMs: record.lease_expires_at_ms }
571
+ : {}),
572
+ ...(record.completed_at_ms !== null
573
+ ? { completedAtMs: record.completed_at_ms }
574
+ : {}),
575
+ ...(record.last_failure !== null
576
+ ? { lastFailure: JSON.parse(record.last_failure) as ReactionFailure }
577
+ : {}),
578
+ };
579
+ }
580
+
581
+ interface SqliteClientRecord {
582
+ client_id: string;
583
+ actor_id: string;
584
+ wire_version: number;
585
+ cursor: number;
586
+ subscriptions: string;
587
+ updated_at_ms: number;
588
+ last_round_at_ms: number | null;
589
+ last_error_code: string | null;
590
+ consecutive_failures: number;
591
+ }
592
+
593
+ function toClientRecord(record: SqliteClientRecord): ClientRecord {
594
+ return {
595
+ clientId: record.client_id,
596
+ actorId: record.actor_id,
597
+ wireVersion: record.wire_version,
598
+ cursor: record.cursor,
599
+ updatedAtMs: record.updated_at_ms,
600
+ subscriptions: JSON.parse(record.subscriptions) as ClientSubscription[],
601
+ ...clientRoundState(
602
+ record.last_round_at_ms,
603
+ record.last_error_code,
604
+ record.consecutive_failures,
605
+ ),
606
+ };
607
+ }
608
+
609
+ interface SqlitePartitionRegistryRecord {
610
+ partition: string;
611
+ log_epoch: string;
612
+ epoch_required: number;
613
+ last_authenticated_at_ms: number;
614
+ }
615
+
616
+ function toPartitionRegistryEntry(
617
+ row: SqlitePartitionRegistryRecord,
618
+ ): PartitionRegistryEntry {
619
+ return {
620
+ partition: row.partition,
621
+ logEpoch: row.log_epoch,
622
+ epochRequired: row.epoch_required === 1,
623
+ lastAuthenticatedAtMs: row.last_authenticated_at_ms,
624
+ };
625
+ }
626
+
627
+ /** One statement of an atomic unit: its SQL text and bound parameters. */
628
+ export interface SqliteStatementSpec {
629
+ readonly sql: string;
630
+ readonly params: readonly SqliteValue[];
631
+ }
632
+
633
+ /**
634
+ * The `ServerStorage` methods SQLite and D1 share. A subclass supplies the
635
+ * execution seam and implements the rest of the interface: schema migration,
636
+ * `begin`, registered queries, the serve gate and checkpoints.
637
+ */
638
+ export abstract class SqliteFamilyStorage {
639
+ /** Set by `ensureSchema`: app-table lookup for the relational row store. */
640
+ protected tables: ReadonlyMap<string, CompiledTable> | undefined;
641
+ protected schemaVersion: number | undefined;
642
+ /** Bound parameters one statement accepts. */
643
+ protected abstract readonly maxBindParams: number;
644
+
645
+ /** Run one statement and return its rows. */
646
+ protected abstract all<T>(
647
+ sql: string,
648
+ params: readonly SqliteValue[],
649
+ ): Promise<T[]>;
650
+
651
+ /**
652
+ * Run one read of schema-dependent state (row tables, the commit window,
653
+ * push results). D1 runs it behind its published-schema guard and joins the
654
+ * reads of one microtask turn into one batch; SQLite runs it as `all`.
655
+ */
656
+ protected abstract guardedAll<T>(
657
+ sql: string,
658
+ params: readonly SqliteValue[],
659
+ ): Promise<T[]>;
660
+
661
+ /** Run statements as one all-or-nothing unit; returns each one's rows. */
662
+ protected abstract atomic(
663
+ statements: readonly SqliteStatementSpec[],
664
+ ): Promise<unknown[][]>;
665
+
666
+ /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
667
+ table(name: string): CompiledTable {
668
+ const table = this.tables?.get(name);
669
+ if (table === undefined) {
670
+ throw new Error(
671
+ `unknown table ${JSON.stringify(name)} — ensureSchema(schema) must run before row operations`,
672
+ );
673
+ }
674
+ return table;
675
+ }
676
+
677
+ protected prepareAuthoritativeQuery(
678
+ partition: string,
679
+ query: AuthoritativeQueryRequest,
680
+ ): BoundAuthoritativeQuery {
681
+ if (this.tables === undefined) {
682
+ throw new Error(
683
+ 'ensureSchema(schema) must run before registered queries',
684
+ );
685
+ }
686
+ return bindAuthoritativePartition(
687
+ prepareAuthoritativeQuery(
688
+ query.plan,
689
+ query.params,
690
+ query.tables,
691
+ this.tables,
692
+ ),
693
+ partition,
694
+ );
695
+ }
696
+
697
+ async touchPartition(
698
+ partition: string,
699
+ authenticatedAtMs: number,
700
+ initialLogEpoch: string,
701
+ ): Promise<PartitionRegistryEntry> {
702
+ if (initialLogEpoch.length === 0) {
703
+ throw new Error('initial log epoch must be non-empty');
704
+ }
705
+ // One atomic unit, so an idle SQLite connection runs both statements at
706
+ // call time, before a `close()` in the same tick. The upsert writes only
707
+ // a new partition or one whose last authentication is a full interval old.
708
+ const [, rows] = await this.atomic([
709
+ {
710
+ sql: `INSERT INTO sync_partition_registry(
711
+ partition, log_epoch, last_authenticated_at_ms
712
+ ) VALUES (?,?,?)
713
+ ON CONFLICT(partition) DO UPDATE SET
714
+ last_authenticated_at_ms=excluded.last_authenticated_at_ms
715
+ WHERE excluded.last_authenticated_at_ms - last_authenticated_at_ms >= ?`,
716
+ params: [
717
+ partition,
718
+ initialLogEpoch,
719
+ authenticatedAtMs,
720
+ PARTITION_TOUCH_INTERVAL_MS,
721
+ ],
722
+ },
723
+ {
724
+ sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
725
+ FROM sync_partition_registry WHERE partition=?`,
726
+ params: [partition],
727
+ },
728
+ ]);
729
+ const row = rows?.[0] as SqlitePartitionRegistryRecord | undefined;
730
+ if (row === undefined)
731
+ throw new Error('partition registry write did not persist');
732
+ return toPartitionRegistryEntry(row);
733
+ }
734
+
735
+ async rotatePartitionLogEpoch(
736
+ partition: string,
737
+ logEpoch: string,
738
+ authenticatedAtMs: number,
739
+ ): Promise<PartitionRegistryEntry> {
740
+ if (logEpoch.length === 0) throw new Error('log epoch must be non-empty');
741
+ await this.atomic([
742
+ {
743
+ sql: `INSERT INTO sync_partition_registry(
744
+ partition, log_epoch, epoch_required, last_authenticated_at_ms
745
+ ) VALUES (?,?,1,?)
746
+ ON CONFLICT(partition) DO UPDATE SET
747
+ log_epoch=excluded.log_epoch,
748
+ epoch_required=1,
749
+ last_authenticated_at_ms=excluded.last_authenticated_at_ms`,
750
+ params: [partition, logEpoch, authenticatedAtMs],
751
+ },
752
+ {
753
+ sql: 'DELETE FROM sync_clients WHERE partition=?',
754
+ params: [partition],
755
+ },
756
+ ]);
757
+ return {
758
+ partition,
759
+ logEpoch,
760
+ epochRequired: true,
761
+ lastAuthenticatedAtMs: authenticatedAtMs,
762
+ };
763
+ }
764
+
765
+ async listPartitionRegistry(): Promise<PartitionRegistryEntry[]> {
766
+ return (
767
+ await this.all<SqlitePartitionRegistryRecord>(
768
+ `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
769
+ FROM sync_partition_registry ORDER BY partition`,
770
+ [],
771
+ )
772
+ ).map(toPartitionRegistryEntry);
773
+ }
774
+
775
+ async getMaxCommitSeq(partition: string): Promise<number> {
776
+ const [row] = await this.all<{ max_commit_seq: number }>(
777
+ 'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
778
+ [partition],
779
+ );
780
+ return row?.max_commit_seq ?? 0;
781
+ }
782
+
783
+ async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
784
+ const [row] = await this.all<{ log_epoch: string }>(
785
+ 'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
786
+ [partition],
787
+ );
788
+ return row?.log_epoch;
789
+ }
790
+
791
+ async getHorizonSeq(partition: string): Promise<number> {
792
+ const [row] = await this.all<{ horizon_seq: number }>(
793
+ 'SELECT horizon_seq FROM sync_partitions WHERE partition=?',
794
+ [partition],
795
+ );
796
+ return row?.horizon_seq ?? 0;
797
+ }
798
+
799
+ async setHorizonSeq(partition: string, seq: number): Promise<void> {
800
+ await this.all(
801
+ `INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
802
+ ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`,
803
+ [partition, seq],
804
+ );
805
+ }
806
+
807
+ async pruneCommitsThrough(
808
+ partition: string,
809
+ query: CommitPruneQuery,
810
+ ): Promise<CommitPruneResult> {
811
+ validateCommitPruneQuery(query);
812
+ // Every write re-checks the epoch, so the unit needs no read before its
813
+ // writes: on a mismatch it changes nothing and the first row reports it.
814
+ const epochGuard =
815
+ 'EXISTS (SELECT 1 FROM sync_partition_registry WHERE partition=? AND log_epoch=?)';
816
+ const horizon =
817
+ '(SELECT horizon_seq FROM sync_partitions WHERE partition=?)';
818
+ const results = await this.atomic([
819
+ {
820
+ sql: `SELECT log_epoch, coalesce(${horizon},0) AS previous_horizon_seq FROM sync_partition_registry WHERE partition=?`,
821
+ params: [partition, partition],
822
+ },
823
+ {
824
+ sql: `INSERT INTO sync_partitions(partition,horizon_seq) SELECT ?,? WHERE ${epochGuard}
825
+ ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`,
826
+ params: [partition, query.throughSeq, partition, query.logEpoch],
827
+ },
828
+ {
829
+ sql: `SELECT horizon_seq, (SELECT count(*) FROM sync_commits WHERE partition=? AND commit_seq<=${horizon}) AS removed_commits FROM sync_partitions WHERE partition=?`,
830
+ params: [partition, partition, partition],
831
+ },
832
+ // Change-scope entries go first, by the keys of the changes being
833
+ // pruned: a predicate on `commit_seq` alone would scan the partition's
834
+ // whole scope index, because `commit_seq` is its last key column.
835
+ {
836
+ sql: `DELETE FROM sync_change_scopes WHERE (partition, tbl, var, value, commit_seq) IN (
837
+ SELECT c.partition, c.tbl, j.key, j.value, c.commit_seq
838
+ FROM sync_changes c, json_each(c.scopes) j
839
+ WHERE c.partition=? AND c.commit_seq<=${horizon})
840
+ AND ${epochGuard}`,
841
+ params: [partition, partition, partition, query.logEpoch],
842
+ },
843
+ // §4.6: tombstones prune in the same pass as the commit log.
844
+ ...['sync_commits', 'sync_changes', 'sync_tombstones'].map((table) => ({
845
+ sql: `DELETE FROM ${table} WHERE partition=? AND commit_seq<=${horizon} AND ${epochGuard}`,
846
+ params: [partition, partition, partition, query.logEpoch],
847
+ })),
848
+ ]);
849
+ const [before, after] = [results[0], results[2]].map((rows) => {
850
+ const row: unknown = rows?.[0];
851
+ return typeof row === 'object' && row !== null
852
+ ? (row as Readonly<Record<string, unknown>>)
853
+ : undefined;
854
+ });
855
+ if (before?.log_epoch !== query.logEpoch)
856
+ throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
857
+ if (
858
+ typeof before.previous_horizon_seq !== 'number' ||
859
+ typeof after?.horizon_seq !== 'number' ||
860
+ typeof after.removed_commits !== 'number'
861
+ ) {
862
+ throw new Error('pruning returned invalid horizon metadata');
863
+ }
864
+ return {
865
+ previousHorizonSeq: before.previous_horizon_seq,
866
+ horizonSeq: after.horizon_seq,
867
+ removedCommits: after.removed_commits,
868
+ };
869
+ }
870
+
871
+ async getCommitSeqBefore(
872
+ partition: string,
873
+ createdBeforeMs: number,
874
+ ): Promise<number> {
875
+ const [row] = await this.all<{ seq: number | null }>(
876
+ 'SELECT max(commit_seq) AS seq FROM sync_commits WHERE partition=? AND created_at_ms<?',
877
+ [partition, createdBeforeMs],
878
+ );
879
+ return row?.seq ?? 0;
880
+ }
881
+
882
+ async sourceCoverageSeq(
883
+ partition: string,
884
+ tables: readonly string[],
885
+ ): Promise<number> {
886
+ if (tables.length === 0) return 0;
887
+ const [row] = await this.all<{ seq: number | null }>(
888
+ `SELECT max(commit_seq) AS seq FROM sync_changes
889
+ WHERE partition=? AND tbl IN (${placeholders(tables.length)})`,
890
+ [partition, ...tables],
891
+ );
892
+ return row?.seq ?? 0;
893
+ }
894
+
895
+ async hasSourceChangesAbove(
896
+ partition: string,
897
+ tables: readonly string[],
898
+ seq: number,
899
+ ): Promise<'clean' | 'changed' | 'unverifiable'> {
900
+ // Read the horizon before the window scan: a horizon past `seq` means the
901
+ // history that would answer the question is gone, so an empty scan proves
902
+ // nothing and must not be reported as `clean`.
903
+ const horizon = await this.getHorizonSeq(partition);
904
+ if (tables.length === 0) return 'clean';
905
+ const hit = await this.all<{ hit: number }>(
906
+ `SELECT 1 AS hit FROM sync_changes
907
+ WHERE partition=? AND tbl IN (${placeholders(tables.length)})
908
+ AND commit_seq>? LIMIT 1`,
909
+ [partition, ...tables, seq],
910
+ );
911
+ if (hit.length > 0) return 'changed';
912
+ return horizon > seq ? 'unverifiable' : 'clean';
913
+ }
914
+
915
+ async getRow(
916
+ partition: string,
917
+ table: string,
918
+ rowId: string,
919
+ ): Promise<StoredRow | undefined> {
920
+ const [record] = await this.guardedAll<SqliteRowRecord>(
921
+ selectRowSql(this.table(table), 'sqlite'),
922
+ [partition, rowId],
923
+ );
924
+ return record === undefined ? undefined : toStoredRow(record);
925
+ }
926
+
927
+ async getPushResult(
928
+ partition: string,
929
+ clientId: string,
930
+ clientCommitId: string,
931
+ ): Promise<StoredPushResult | undefined> {
932
+ const [record] = await this.guardedAll<{ result: string }>(
933
+ 'SELECT result FROM sync_push_results WHERE partition=? AND client_id=? AND client_commit_id=?',
934
+ [partition, clientId, clientCommitId],
935
+ );
936
+ return record === undefined
937
+ ? undefined
938
+ : deserializePushResult(record.result);
939
+ }
940
+
941
+ async claimReactions(
942
+ partition: string,
943
+ query: ReactionClaimQuery,
944
+ ): Promise<StoredReaction[]> {
945
+ if (query.types.length === 0 || query.limit <= 0) return [];
946
+ if (query.types.length + 7 > this.maxBindParams) {
947
+ throw new Error('D1 reaction claim exceeds the bound-parameter limit');
948
+ }
949
+ const records = await this.all<SqliteReactionRecord>(
950
+ `UPDATE sync_reactions
951
+ SET status='leased', attempts=attempts+1,
952
+ lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
953
+ WHERE (partition, idempotency_key) IN (
954
+ SELECT partition, idempotency_key
955
+ FROM sync_reactions
956
+ WHERE partition=? AND type IN (${placeholders(query.types.length)})
957
+ AND ((status='pending' AND available_at_ms<=?)
958
+ OR (status='leased' AND lease_expires_at_ms<=?))
959
+ ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
960
+ ELSE available_at_ms END,
961
+ created_at_ms, idempotency_key
962
+ LIMIT ?
963
+ )
964
+ RETURNING *`,
965
+ [
966
+ query.leaseOwner,
967
+ Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs),
968
+ partition,
969
+ ...query.types,
970
+ query.nowMs,
971
+ query.nowMs,
972
+ query.limit,
973
+ ],
974
+ );
975
+ return records
976
+ .map(toStoredReaction)
977
+ .sort(
978
+ (a, b) =>
979
+ a.createdAtMs - b.createdAtMs ||
980
+ a.idempotencyKey.localeCompare(b.idempotencyKey),
981
+ );
982
+ }
983
+
984
+ async completeReaction(
985
+ partition: string,
986
+ idempotencyKey: string,
987
+ leaseOwner: string,
988
+ completedAtMs: number,
989
+ ): Promise<boolean> {
990
+ const updated = await this.all(
991
+ `UPDATE sync_reactions
992
+ SET status='completed', completed_at_ms=?,
993
+ lease_owner=NULL, lease_expires_at_ms=NULL
994
+ WHERE partition=? AND idempotency_key=?
995
+ AND status='leased' AND lease_owner=?
996
+ RETURNING idempotency_key`,
997
+ [completedAtMs, partition, idempotencyKey, leaseOwner],
998
+ );
999
+ return updated.length === 1;
1000
+ }
1001
+
1002
+ async extendReactionLease(
1003
+ partition: string,
1004
+ idempotencyKey: string,
1005
+ leaseOwner: string,
1006
+ leaseExpiresAtMs: number,
1007
+ ): Promise<boolean> {
1008
+ const updated = await this.all(
1009
+ `UPDATE sync_reactions SET lease_expires_at_ms=?
1010
+ WHERE partition=? AND idempotency_key=?
1011
+ AND status='leased' AND lease_owner=?
1012
+ RETURNING idempotency_key`,
1013
+ [leaseExpiresAtMs, partition, idempotencyKey, leaseOwner],
1014
+ );
1015
+ return updated.length === 1;
1016
+ }
1017
+
1018
+ async failReaction(
1019
+ partition: string,
1020
+ idempotencyKey: string,
1021
+ update: ReactionFailureUpdate,
1022
+ ): Promise<boolean> {
1023
+ const updated = await this.all(
1024
+ `UPDATE sync_reactions
1025
+ SET status=?, available_at_ms=?, last_failure=?,
1026
+ lease_owner=NULL, lease_expires_at_ms=NULL
1027
+ WHERE partition=? AND idempotency_key=?
1028
+ AND status='leased' AND lease_owner=?
1029
+ RETURNING idempotency_key`,
1030
+ [
1031
+ update.retryAtMs === undefined ? 'dead-letter' : 'pending',
1032
+ update.retryAtMs ?? update.failure.atMs,
1033
+ JSON.stringify(update.failure),
1034
+ partition,
1035
+ idempotencyKey,
1036
+ update.leaseOwner,
1037
+ ],
1038
+ );
1039
+ return updated.length === 1;
1040
+ }
1041
+
1042
+ async retryReaction(
1043
+ partition: string,
1044
+ idempotencyKey: string,
1045
+ nowMs: number,
1046
+ ): Promise<boolean> {
1047
+ const updated = await this.all(
1048
+ `UPDATE sync_reactions
1049
+ SET status='pending', attempts=0, available_at_ms=?,
1050
+ last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
1051
+ completed_at_ms=NULL
1052
+ WHERE partition=? AND idempotency_key=? AND status='dead-letter'
1053
+ RETURNING idempotency_key`,
1054
+ [nowMs, partition, idempotencyKey],
1055
+ );
1056
+ return updated.length === 1;
1057
+ }
1058
+
1059
+ async getReaction(
1060
+ partition: string,
1061
+ idempotencyKey: string,
1062
+ ): Promise<StoredReaction | undefined> {
1063
+ const [record] = await this.all<SqliteReactionRecord>(
1064
+ 'SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?',
1065
+ [partition, idempotencyKey],
1066
+ );
1067
+ return record === undefined ? undefined : toStoredReaction(record);
1068
+ }
1069
+
1070
+ async listReactions(
1071
+ partition: string,
1072
+ query: ReactionListQuery,
1073
+ ): Promise<StoredReaction[]> {
1074
+ const where = ['partition=?'];
1075
+ const params: (string | number)[] = [partition];
1076
+ if (query.statuses !== undefined && query.statuses.length > 0) {
1077
+ where.push(`status IN (${placeholders(query.statuses.length)})`);
1078
+ params.push(...query.statuses);
1079
+ }
1080
+ if (query.types !== undefined && query.types.length > 0) {
1081
+ where.push(`type IN (${placeholders(query.types.length)})`);
1082
+ params.push(...query.types);
1083
+ }
1084
+ if (params.length + 1 > this.maxBindParams) {
1085
+ throw new Error('D1 reaction list exceeds the bound-parameter limit');
1086
+ }
1087
+ params.push(query.limit);
1088
+ const records = await this.all<SqliteReactionRecord>(
1089
+ `SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
1090
+ ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`,
1091
+ params,
1092
+ );
1093
+ return records.map(toStoredReaction);
1094
+ }
1095
+
1096
+ async pruneReactions(
1097
+ partition: string,
1098
+ query: ReactionPruneQuery,
1099
+ ): Promise<PrunedReactionCounts> {
1100
+ if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
1101
+ const records = await this.all<{ status: 'completed' | 'dead-letter' }>(
1102
+ `DELETE FROM sync_reactions
1103
+ WHERE partition=? AND idempotency_key IN (
1104
+ SELECT idempotency_key FROM sync_reactions
1105
+ WHERE partition=?
1106
+ AND ((status='completed' AND completed_at_ms IS NOT NULL
1107
+ AND completed_at_ms<?)
1108
+ OR (status='dead-letter' AND available_at_ms<?))
1109
+ ORDER BY CASE WHEN status='completed' THEN completed_at_ms
1110
+ ELSE available_at_ms END,
1111
+ idempotency_key
1112
+ LIMIT ?
1113
+ )
1114
+ AND ((status='completed' AND completed_at_ms IS NOT NULL
1115
+ AND completed_at_ms<?)
1116
+ OR (status='dead-letter' AND available_at_ms<?))
1117
+ RETURNING status`,
1118
+ [
1119
+ partition,
1120
+ partition,
1121
+ query.completedBeforeMs,
1122
+ query.deadLetterBeforeMs,
1123
+ query.limit,
1124
+ query.completedBeforeMs,
1125
+ query.deadLetterBeforeMs,
1126
+ ],
1127
+ );
1128
+ return {
1129
+ completed: records.filter((record) => record.status === 'completed')
1130
+ .length,
1131
+ deadLetter: records.filter((record) => record.status === 'dead-letter')
1132
+ .length,
1133
+ };
1134
+ }
1135
+
1136
+ async latestScopedChangeSeq(
1137
+ partition: string,
1138
+ query: { readonly table: string; readonly scopeFilter: ScopeMap },
1139
+ ): Promise<number> {
1140
+ const firstVariable = Object.keys(query.scopeFilter).sort()[0];
1141
+ const values =
1142
+ firstVariable === undefined
1143
+ ? []
1144
+ : (query.scopeFilter[firstVariable] ?? []);
1145
+ if (firstVariable === undefined || values.length === 0) return 0;
1146
+ const [row] = await this.guardedAll<{ seq: number | null }>(
1147
+ LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL,
1148
+ [partition, query.table, firstVariable, JSON.stringify(values)],
1149
+ );
1150
+ return row?.seq ?? 0;
1151
+ }
1152
+
1153
+ async readCommitWindow(
1154
+ partition: string,
1155
+ query: CommitWindowQuery,
1156
+ ): Promise<StoredCommit[]> {
1157
+ const variables = Object.keys(query.scopeFilter).sort();
1158
+ const firstVariable = variables[0];
1159
+ if (firstVariable === undefined) return [];
1160
+ const firstValues = query.scopeFilter[firstVariable] ?? [];
1161
+ if (firstValues.length === 0) return [];
1162
+ // Candidates via the inverted index (one variable) LEFT JOINed to the
1163
+ // commit meta + the table's changes — one statement per page, never two
1164
+ // per candidate (see `commitWindowPageSql`). Exact multi-variable
1165
+ // verification against the stored scope map in `collectCommitWindowPage`.
1166
+ const sql = commitWindowPageSql(firstValues.length, 'sqlite');
1167
+ const commits: StoredCommit[] = [];
1168
+ let deliveredChanges = 0;
1169
+ let afterSeq = query.afterSeq;
1170
+ const batchSize = Math.max(64, query.limitChanges);
1171
+ while (deliveredChanges < query.limitChanges) {
1172
+ const records = await this.guardedAll<SqliteCommitWindowRecord>(sql, [
1173
+ partition,
1174
+ query.table,
1175
+ firstVariable,
1176
+ JSON.stringify(firstValues),
1177
+ afterSeq,
1178
+ query.throughSeq,
1179
+ batchSize,
1180
+ partition,
1181
+ partition,
1182
+ query.table,
1183
+ ]);
1184
+ if (records.length === 0) break;
1185
+ const page = collectCommitWindowPage(
1186
+ records,
1187
+ query.scopeFilter,
1188
+ query.limitChanges - deliveredChanges,
1189
+ );
1190
+ commits.push(...page.commits);
1191
+ deliveredChanges += page.delivered;
1192
+ afterSeq = page.lastSeq;
1193
+ if (page.candidateCount < batchSize) break;
1194
+ }
1195
+ return commits;
1196
+ }
1197
+
1198
+ async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
1199
+ const firstVariable = assertScopeIndexedScan(query);
1200
+ const firstValues = query.scopeFilter[firstVariable] ?? [];
1201
+ if (firstValues.length === 0) return [];
1202
+ // Candidates via the inverted index LEFT JOINed to the row table — one
1203
+ // statement per page, never one per row (see `scanRowPageSql`). Exact
1204
+ // multi-variable verification against the stored scope map below.
1205
+ const sql = scanRowPageSql(
1206
+ this.table(query.table),
1207
+ firstValues.length,
1208
+ 'sqlite',
1209
+ );
1210
+ const rows: StoredRow[] = [];
1211
+ let afterRowId = query.afterRowId ?? '';
1212
+ const batchSize = Math.max(64, query.limit);
1213
+ while (rows.length < query.limit) {
1214
+ const records = await this.guardedAll<
1215
+ SqliteRowRecord & { payload: Uint8Array | null }
1216
+ >(sql, [
1217
+ partition,
1218
+ query.table,
1219
+ firstVariable,
1220
+ JSON.stringify(firstValues),
1221
+ afterRowId,
1222
+ batchSize,
1223
+ partition,
1224
+ ]);
1225
+ if (records.length === 0) break;
1226
+ for (const record of records) {
1227
+ afterRowId = record.row_id;
1228
+ // NULL payload: an index candidate whose row vanished — it still
1229
+ // advances the keyset cursor (LEFT JOIN contract) but yields no row.
1230
+ if (record.payload === null) continue;
1231
+ const stored = toStoredRow(record);
1232
+ if (!matchesEffective(stored.scopes, query.scopeFilter)) continue;
1233
+ rows.push(stored);
1234
+ if (rows.length >= query.limit) break;
1235
+ }
1236
+ if (records.length < batchSize) break;
1237
+ }
1238
+ return rows;
1239
+ }
1240
+
1241
+ async scanRowsByIndex(
1242
+ partition: string,
1243
+ query: IndexRowScanQuery,
1244
+ ): Promise<StoredRow[]> {
1245
+ const table = this.table(query.table);
1246
+ const statement = indexRowPageStatement(
1247
+ table,
1248
+ resolveIndexRowScan(table, query),
1249
+ query.values,
1250
+ partition,
1251
+ query.afterRowId,
1252
+ query.limit,
1253
+ 'sqlite',
1254
+ );
1255
+ return (
1256
+ await this.guardedAll<SqliteRowRecord>(statement.sql, statement.params)
1257
+ ).map(toStoredRow);
1258
+ }
1259
+
1260
+ async getClientRecord(
1261
+ partition: string,
1262
+ clientId: string,
1263
+ ): Promise<ClientRecord | undefined> {
1264
+ const [record] = await this.all<SqliteClientRecord>(
1265
+ '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=?',
1266
+ [partition, clientId],
1267
+ );
1268
+ return record === undefined ? undefined : toClientRecord(record);
1269
+ }
1270
+
1271
+ async putClientRecord(
1272
+ partition: string,
1273
+ record: ClientRecord,
1274
+ options?: ClientRecordWriteOptions,
1275
+ ): Promise<void> {
1276
+ // One row per (partition, client_id): every non-key field is written
1277
+ // from the new record. `keepRoundOutcome` leaves the round-state columns
1278
+ // alone (§1.5, §4.5).
1279
+ await this.all(
1280
+ `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms) VALUES (?,?,?,?,?,?,?,?)
1281
+ ON CONFLICT(partition, client_id) DO UPDATE SET
1282
+ actor_id=excluded.actor_id,
1283
+ wire_version=excluded.wire_version,
1284
+ cursor=excluded.cursor,
1285
+ subscriptions=excluded.subscriptions,
1286
+ updated_at_ms=excluded.updated_at_ms,
1287
+ last_round_at_ms=excluded.last_round_at_ms${
1288
+ options?.keepRoundOutcome === true
1289
+ ? ''
1290
+ : `,
1291
+ last_error_code=NULL,
1292
+ consecutive_failures=0`
1293
+ }`,
1294
+ [
1295
+ partition,
1296
+ record.clientId,
1297
+ record.actorId,
1298
+ record.wireVersion,
1299
+ record.cursor,
1300
+ JSON.stringify(record.subscriptions),
1301
+ record.updatedAtMs,
1302
+ record.updatedAtMs,
1303
+ ],
1304
+ );
1305
+ }
1306
+
1307
+ async recordClientRoundFailure(
1308
+ partition: string,
1309
+ clientId: string,
1310
+ actorId: string,
1311
+ errorCode: string,
1312
+ atMs: number,
1313
+ ): Promise<void> {
1314
+ await this.all(
1315
+ `UPDATE sync_clients
1316
+ SET last_round_at_ms=?, last_error_code=?,
1317
+ consecutive_failures=consecutive_failures+1
1318
+ WHERE partition=? AND client_id=? AND actor_id=?`,
1319
+ [atMs, errorCode, partition, clientId, actorId],
1320
+ );
1321
+ }
1322
+
1323
+ async advanceClientCursor(
1324
+ partition: string,
1325
+ clientId: string,
1326
+ actorId: string,
1327
+ logEpoch: string,
1328
+ cursor: number,
1329
+ updatedAtMs: number,
1330
+ ): Promise<void> {
1331
+ await this.all(
1332
+ `UPDATE sync_clients
1333
+ SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
1334
+ WHERE partition=? AND client_id=? AND actor_id=?
1335
+ AND EXISTS (SELECT 1 FROM sync_partition_registry
1336
+ WHERE partition=sync_clients.partition AND log_epoch=?)`,
1337
+ [cursor, updatedAtMs, partition, clientId, actorId, logEpoch],
1338
+ );
1339
+ }
1340
+
1341
+ async updateClientCursor(
1342
+ partition: string,
1343
+ clientId: string,
1344
+ cursor: number,
1345
+ updatedAtMs: number,
1346
+ ): Promise<void> {
1347
+ await this.all(
1348
+ `UPDATE sync_clients
1349
+ SET cursor=MAX(cursor, ?), updated_at_ms=MAX(updated_at_ms, ?)
1350
+ WHERE partition=? AND client_id=?`,
1351
+ [cursor, updatedAtMs, partition, clientId],
1352
+ );
1353
+ }
1354
+
1355
+ async getActiveClientCursorFloor(
1356
+ partition: string,
1357
+ cutoffMs: number,
1358
+ ): Promise<number | null> {
1359
+ const [row] = await this.all<{ cursor: number | null }>(
1360
+ 'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=? AND cursor>=0',
1361
+ [partition, cutoffMs],
1362
+ );
1363
+ return row!.cursor;
1364
+ }
1365
+
1366
+ async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
1367
+ const records = await this.all<{
1368
+ client_id: string;
1369
+ cursor: number;
1370
+ updated_at_ms: number;
1371
+ }>(
1372
+ 'SELECT client_id, cursor, updated_at_ms FROM sync_clients WHERE partition=?',
1373
+ [partition],
1374
+ );
1375
+ return records.map((r) => ({
1376
+ clientId: r.client_id,
1377
+ cursor: r.cursor,
1378
+ updatedAtMs: r.updated_at_ms,
1379
+ }));
1380
+ }
1381
+
1382
+ async listRowsReferencingBlob(
1383
+ partition: string,
1384
+ blobId: string,
1385
+ ): Promise<
1386
+ {
1387
+ readonly table: string;
1388
+ readonly rowId: string;
1389
+ readonly scopes: Record<string, string>;
1390
+ }[]
1391
+ > {
1392
+ // One statement: the by-blob index (§5.9.4/§5.9.5) supplies the candidate
1393
+ // rows and each row's stored scopes come from its row table for the §3.4
1394
+ // authorization test (see `rowsReferencingBlobSql`).
1395
+ if (this.tables === undefined || this.tables.size === 0) return [];
1396
+ return (
1397
+ await this.guardedAll<{
1398
+ tbl: string;
1399
+ row_id: string;
1400
+ scopes: string | null;
1401
+ }>(rowsReferencingBlobSql(this.tables.values(), 'sqlite'), [
1402
+ partition,
1403
+ blobId,
1404
+ ])
1405
+ ).flatMap((row) =>
1406
+ row.scopes === null
1407
+ ? []
1408
+ : [
1409
+ {
1410
+ table: row.tbl,
1411
+ rowId: row.row_id,
1412
+ scopes: JSON.parse(row.scopes) as Record<string, string>,
1413
+ },
1414
+ ],
1415
+ );
1416
+ }
1417
+
1418
+ async listReferencedBlobIds(partition: string): Promise<string[]> {
1419
+ const rows = await this.all<{ blob_id: string }>(
1420
+ 'SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=?',
1421
+ [partition],
1422
+ );
1423
+ return rows.map((r) => r.blob_id);
1424
+ }
1425
+
1426
+ async listScopeValueRows(
1427
+ partition: string,
1428
+ query: ScopeValueQuery,
1429
+ ): Promise<string[]> {
1430
+ // §4.6.1: rowIds of one table bound to one scope value, budgeted.
1431
+ const rows = await this.all<{ row_id: string }>(
1432
+ 'SELECT row_id FROM sync_row_scopes WHERE partition=? AND tbl=? AND var=? AND value=? ORDER BY row_id LIMIT ?',
1433
+ [partition, query.table, query.variable, query.value, query.limit],
1434
+ );
1435
+ return rows.map((row) => row.row_id);
1436
+ }
1437
+
1438
+ async eraseScopeValueHistory(
1439
+ partition: string,
1440
+ query: ScopeValueHistoryQuery,
1441
+ ): Promise<number> {
1442
+ const params = [
1443
+ partition,
1444
+ query.table,
1445
+ query.variable,
1446
+ query.value,
1447
+ query.throughSeq,
1448
+ `$.${JSON.stringify(query.variable)}`,
1449
+ query.limit,
1450
+ ];
1451
+ // §4.6.1 history scrub: upsert change records of the binding first, then
1452
+ // the change scope entries whose commit no longer holds a change of the
1453
+ // binding, then `serverRow` of stored conflict results whose conflict
1454
+ // authorization scopes carry the binding. Each statement returns one row
1455
+ // per changed record (D1 batch results carry no reliable change count).
1456
+ const results = await this.atomic(
1457
+ [
1458
+ `DELETE FROM sync_changes WHERE rowid IN (
1459
+ SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c
1460
+ ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl
1461
+ WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
1462
+ AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value
1463
+ LIMIT ?7) RETURNING 1 AS removed`,
1464
+ `DELETE FROM sync_change_scopes WHERE rowid IN (
1465
+ SELECT s.rowid FROM sync_change_scopes s
1466
+ WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
1467
+ AND s.commit_seq<=?5 AND NOT EXISTS (
1468
+ SELECT 1 FROM sync_changes c
1469
+ WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
1470
+ AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)
1471
+ LIMIT ?7) RETURNING 1 AS removed`,
1472
+ `UPDATE sync_push_results SET result=json_set(result, '$.results', json((
1473
+ SELECT json_group_array(json(json_remove(e.value, '$.serverRow')))
1474
+ FROM (SELECT value FROM json_each(sync_push_results.result, '$.results')
1475
+ ORDER BY key) e)))
1476
+ WHERE rowid IN (
1477
+ SELECT rowid FROM sync_push_results
1478
+ WHERE partition=?1
1479
+ AND json_extract(result, '$.conflictAuthorization.table')=?2
1480
+ AND json_extract(result,
1481
+ '$.conflictAuthorization.scopes' || substr(?6, 2))=?4
1482
+ AND EXISTS (SELECT 1 FROM json_each(result, '$.results') r
1483
+ WHERE json_type(r.value, '$.serverRow') IS NOT NULL)
1484
+ LIMIT ?7) RETURNING 1 AS removed`,
1485
+ ].map((sql) => ({ sql, params })),
1486
+ );
1487
+ return results.reduce((removed, rows) => removed + rows.length, 0);
1488
+ }
1489
+
1490
+ // -- admin/console read surface --------------------------------------------
1491
+
1492
+ async listClientRecords(partition: string): Promise<ClientRecord[]> {
1493
+ return (
1494
+ await this.all<SqliteClientRecord>(
1495
+ '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',
1496
+ [partition],
1497
+ )
1498
+ ).map(toClientRecord);
1499
+ }
1500
+
1501
+ async listCommitMetadata(
1502
+ partition: string,
1503
+ query: CommitMetadataQuery,
1504
+ ): Promise<CommitMetadata[]> {
1505
+ // Newest-first window, resumed by `afterSeq` (exclusive lower bound) and
1506
+ // ended by `beforeSeq` (exclusive upper bound) when paging older. An
1507
+ // omitted bound is the largest safe commitSeq, so one statement serves
1508
+ // both the bounded and unbounded read.
1509
+ const beforeSeq = query.beforeSeq ?? Number.MAX_SAFE_INTEGER;
1510
+ const rows = await this.all<{
1511
+ commit_seq: number;
1512
+ client_id: string;
1513
+ client_commit_id: string;
1514
+ actor_id: string;
1515
+ created_at_ms: number;
1516
+ }>(
1517
+ query.table
1518
+ ? `SELECT c.commit_seq, c.client_id, c.client_commit_id, c.actor_id, c.created_at_ms
1519
+ FROM sync_commits c
1520
+ WHERE c.partition=? AND c.commit_seq>? AND c.commit_seq<?
1521
+ AND EXISTS (SELECT 1 FROM sync_changes ch
1522
+ WHERE ch.partition=c.partition AND ch.commit_seq=c.commit_seq AND ch.tbl=?)
1523
+ ORDER BY c.commit_seq DESC LIMIT ?`
1524
+ : `SELECT commit_seq, client_id, client_commit_id, actor_id, created_at_ms
1525
+ FROM sync_commits
1526
+ WHERE partition=? AND commit_seq>? AND commit_seq<?
1527
+ ORDER BY commit_seq DESC LIMIT ?`,
1528
+ query.table
1529
+ ? [partition, query.afterSeq, beforeSeq, query.table, query.limit]
1530
+ : [partition, query.afterSeq, beforeSeq, query.limit],
1531
+ );
1532
+ // One grouped statement for the page's per-table change counts and, with
1533
+ // `changeSample`, one for the first `sample` changes (change-index order)
1534
+ // of every listed commit. The commit ids bind as one JSON array, so the
1535
+ // statement count does not grow with the page.
1536
+ const sampleCount =
1537
+ query.changeSample !== undefined &&
1538
+ Number.isInteger(query.changeSample) &&
1539
+ query.changeSample > 0
1540
+ ? query.changeSample
1541
+ : 0;
1542
+ const seqs = JSON.stringify(rows.map((row) => row.commit_seq));
1543
+ const counts = new Map<number, { tbl: string; n: number }[]>();
1544
+ for (const count of rows.length === 0
1545
+ ? []
1546
+ : await this.all<{ commit_seq: number; tbl: string; n: number }>(
1547
+ `SELECT commit_seq, tbl, count(*) AS n FROM sync_changes
1548
+ WHERE partition=? AND commit_seq IN (SELECT value FROM json_each(?))
1549
+ GROUP BY commit_seq, tbl ORDER BY commit_seq, tbl`,
1550
+ [partition, seqs],
1551
+ )) {
1552
+ counts.set(count.commit_seq, [
1553
+ ...(counts.get(count.commit_seq) ?? []),
1554
+ count,
1555
+ ]);
1556
+ }
1557
+ const samples = new Map<number, CommitChangeSummary[]>();
1558
+ for (const change of sampleCount === 0 || rows.length === 0
1559
+ ? []
1560
+ : await this.all<{
1561
+ commit_seq: number;
1562
+ tbl: string;
1563
+ row_id: string;
1564
+ op: number;
1565
+ }>(
1566
+ `SELECT commit_seq, tbl, row_id, op FROM sync_changes
1567
+ WHERE partition=? AND commit_seq IN (SELECT value FROM json_each(?)) AND idx<?
1568
+ ORDER BY commit_seq, idx`,
1569
+ [partition, seqs, sampleCount],
1570
+ )) {
1571
+ samples.set(change.commit_seq, [
1572
+ ...(samples.get(change.commit_seq) ?? []),
1573
+ {
1574
+ table: change.tbl,
1575
+ rowId: change.row_id,
1576
+ op: change.op === 1 ? 'upsert' : 'delete',
1577
+ },
1578
+ ]);
1579
+ }
1580
+ const out: CommitMetadata[] = [];
1581
+ for (const row of rows) {
1582
+ const changes = counts.get(row.commit_seq) ?? [];
1583
+ out.push({
1584
+ commitSeq: row.commit_seq,
1585
+ clientId: row.client_id,
1586
+ clientCommitId: row.client_commit_id,
1587
+ actorId: row.actor_id,
1588
+ createdAtMs: row.created_at_ms,
1589
+ changeCount: changes.reduce((sum, c) => sum + c.n, 0),
1590
+ tables: changes.map((c) => c.tbl),
1591
+ ...(sampleCount > 0
1592
+ ? { sample: samples.get(row.commit_seq) ?? [] }
1593
+ : {}),
1594
+ });
1595
+ }
1596
+ return out;
1597
+ }
1598
+
1599
+ async getCommit(
1600
+ partition: string,
1601
+ commitSeq: number,
1602
+ ): Promise<CommitDetail | undefined> {
1603
+ const [meta] = await this.all<{
1604
+ client_id: string;
1605
+ client_commit_id: string;
1606
+ actor_id: string;
1607
+ created_at_ms: number;
1608
+ }>(
1609
+ 'SELECT client_id, client_commit_id, actor_id, created_at_ms FROM sync_commits WHERE partition=? AND commit_seq=?',
1610
+ [partition, commitSeq],
1611
+ );
1612
+ if (meta === undefined) return undefined;
1613
+ const changes = (
1614
+ await this.all<SqliteChangeRecord>(
1615
+ 'SELECT tbl, row_id, op, row_version, scopes, payload FROM sync_changes WHERE partition=? AND commit_seq=? ORDER BY idx',
1616
+ [partition, commitSeq],
1617
+ )
1618
+ ).map(toStoredChange);
1619
+ return {
1620
+ commitSeq,
1621
+ clientId: meta.client_id,
1622
+ clientCommitId: meta.client_commit_id,
1623
+ actorId: meta.actor_id,
1624
+ createdAtMs: meta.created_at_ms,
1625
+ changeCount: changes.length,
1626
+ tables: [...new Set(changes.map((change) => change.table))].sort(),
1627
+ changes,
1628
+ };
1629
+ }
1630
+
1631
+ async listRowChanges(
1632
+ partition: string,
1633
+ query: RowChangesQuery,
1634
+ ): Promise<RowChangeRecord[]> {
1635
+ // Retained-log read for one row: no dedicated index (the write path pays
1636
+ // nothing for it), bounded by retention (§4.6).
1637
+ const rows = await this.all<{
1638
+ commit_seq: number;
1639
+ op: number;
1640
+ row_version: number | null;
1641
+ actor_id: string;
1642
+ client_id: string;
1643
+ created_at_ms: number;
1644
+ }>(
1645
+ `SELECT ch.commit_seq, ch.op, ch.row_version, c.actor_id, c.client_id, c.created_at_ms
1646
+ FROM sync_changes ch
1647
+ JOIN sync_commits c
1648
+ ON c.partition=ch.partition AND c.commit_seq=ch.commit_seq
1649
+ WHERE ch.partition=? AND ch.tbl=? AND ch.row_id=?
1650
+ ORDER BY ch.commit_seq DESC, ch.idx DESC LIMIT ?`,
1651
+ [partition, query.table, query.rowId, query.limit],
1652
+ );
1653
+ return rows.map((row) => ({
1654
+ commitSeq: row.commit_seq,
1655
+ op: row.op === 1 ? 'upsert' : 'delete',
1656
+ ...(row.row_version !== null ? { rowVersion: row.row_version } : {}),
1657
+ actorId: row.actor_id,
1658
+ clientId: row.client_id,
1659
+ createdAtMs: row.created_at_ms,
1660
+ }));
1661
+ }
1662
+
1663
+ async listRows(partition: string, query: RowListQuery): Promise<StoredRow[]> {
1664
+ // Keyset page over the row table's (partition, rowId) primary key: an
1665
+ // index range read, no scope filter, no per-row lookup.
1666
+ return (
1667
+ await this.guardedAll<SqliteRowRecord>(
1668
+ `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
1669
+ FROM ${quoteIdent(this.table(query.table).name)}
1670
+ WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>?
1671
+ ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ?`,
1672
+ [partition, query.afterRowId ?? '', query.limit],
1673
+ )
1674
+ ).map(toStoredRow);
1675
+ }
1676
+
1677
+ async countRows(partition: string, table: string): Promise<number> {
1678
+ const [record] = await this.guardedAll<{ n: number }>(
1679
+ `SELECT count(*) AS n FROM ${quoteIdent(this.table(table).name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?`,
1680
+ [partition],
1681
+ );
1682
+ return record?.n ?? 0;
1683
+ }
1684
+
1685
+ async listPushResults(
1686
+ partition: string,
1687
+ clientCommitId: string,
1688
+ ): Promise<ClientPushResult[]> {
1689
+ // Retained outcomes for one clientCommitId: no dedicated index, ordered
1690
+ // by client so the read is deterministic.
1691
+ const records = await this.guardedAll<{
1692
+ client_id: string;
1693
+ result: string;
1694
+ }>(
1695
+ 'SELECT client_id, result FROM sync_push_results WHERE partition=? AND client_commit_id=? ORDER BY client_id',
1696
+ [partition, clientCommitId],
1697
+ );
1698
+ return records.map((record) => ({
1699
+ clientId: record.client_id,
1700
+ result: deserializePushResult(record.result),
1701
+ }));
1702
+ }
1703
+
1704
+ async scopeActivity(
1705
+ partition: string,
1706
+ query: ScopeActivityQuery,
1707
+ ): Promise<ScopeCommitActivity[]> {
1708
+ // One statement for the page: candidate (commit, table) pairs from the
1709
+ // change-scope index, joined to the commit metadata with the table's
1710
+ // change count. `tbl` sits between `partition` and `var` in the index key,
1711
+ // so the `var`/`value` filter ranges over the partition's change-scope
1712
+ // entries; only the LIMIT bounds the output. A candidate whose commit was
1713
+ // pruned has no metadata and is skipped.
1714
+ return (
1715
+ await this.all<{
1716
+ commit_seq: number;
1717
+ tbl: string;
1718
+ actor_id: string;
1719
+ created_at_ms: number;
1720
+ n: number;
1721
+ }>(
1722
+ `SELECT s.commit_seq, s.tbl, m.actor_id, m.created_at_ms,
1723
+ (SELECT count(*) FROM sync_changes ch
1724
+ WHERE ch.partition=? AND ch.commit_seq=s.commit_seq AND ch.tbl=s.tbl) AS n
1725
+ FROM (SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
1726
+ WHERE partition=? AND var=? AND value=?
1727
+ ORDER BY commit_seq DESC LIMIT ?) s
1728
+ JOIN sync_commits m ON m.partition=? AND m.commit_seq=s.commit_seq
1729
+ ORDER BY s.commit_seq DESC`,
1730
+ [
1731
+ partition,
1732
+ partition,
1733
+ query.variable,
1734
+ query.value,
1735
+ query.limit,
1736
+ partition,
1737
+ ],
1738
+ )
1739
+ ).map((row) => ({
1740
+ commitSeq: row.commit_seq,
1741
+ table: row.tbl,
1742
+ createdAtMs: row.created_at_ms,
1743
+ actorId: row.actor_id,
1744
+ changeCount: row.n,
1745
+ }));
1746
+ }
1747
+
1748
+ async listPartitions(): Promise<string[]> {
1749
+ return (await this.listPartitionRegistry()).map((entry) => entry.partition);
1750
+ }
1751
+ }
1752
+
1753
+ /**
1754
+ * The `StorageTransaction` writes SQLite and D1 share. `run` executes a write
1755
+ * at call time on SQLite, inside its `BEGIN IMMEDIATE`; D1 buffers it for the
1756
+ * one `db.batch` at `commit()`.
1757
+ */
1758
+ export abstract class SqliteFamilyTransaction {
1759
+ protected readonly partition: string;
1760
+ protected open = true;
1761
+
1762
+ constructor(partition: string) {
1763
+ this.partition = partition;
1764
+ }
1765
+
1766
+ /** Execute (SQLite) or buffer (D1) one write of this transaction. */
1767
+ protected abstract run(sql: string, params: readonly SqliteValue[]): void;
1768
+
1769
+ /** Read persisted state from inside this transaction. */
1770
+ protected abstract all<T>(
1771
+ sql: string,
1772
+ params: readonly SqliteValue[],
1773
+ ): Promise<T[]>;
1774
+
1775
+ protected abstract table(name: string): CompiledTable;
1776
+
1777
+ /** Allocate the next dense commitSeq (§2.1) and write its `sync_commits` row. */
1778
+ protected abstract appendCommitRow(commit: NewCommit): Promise<number>;
1779
+
1780
+ abstract getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
1781
+
1782
+ protected assertOpen(): void {
1783
+ if (!this.open) throw new Error('transaction already finished');
1784
+ }
1785
+
1786
+ async getRows(
1787
+ table: string,
1788
+ rowIds: readonly string[],
1789
+ ): Promise<ReadonlyMap<string, StoredRow>> {
1790
+ this.assertOpen();
1791
+ // One indexed lookup per id: SQLite is in-process, and on D1 `getRow`
1792
+ // owns the buffered-write overlay.
1793
+ const rows = new Map<string, StoredRow>();
1794
+ for (const rowId of new Set(rowIds)) {
1795
+ const row = await this.getRow(table, rowId);
1796
+ if (row !== undefined) rows.set(rowId, row);
1797
+ }
1798
+ return rows;
1799
+ }
1800
+
1801
+ async getTombstone(
1802
+ table: string,
1803
+ rowId: string,
1804
+ ): Promise<Tombstone | undefined> {
1805
+ this.assertOpen();
1806
+ const [row] = await this.all<SqliteTombstoneRecord>(
1807
+ 'SELECT commit_seq, server_version, scopes FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
1808
+ [this.partition, table, rowId],
1809
+ );
1810
+ return row === undefined ? undefined : toTombstone(row);
1811
+ }
1812
+
1813
+ async clearTombstone(table: string, rowId: string): Promise<void> {
1814
+ this.assertOpen();
1815
+ this.run(
1816
+ 'DELETE FROM sync_tombstones WHERE partition=? AND tbl=? AND row_id=?',
1817
+ [this.partition, table, rowId],
1818
+ );
1819
+ }
1820
+
1821
+ /**
1822
+ * Write a row and refresh its scope-index entries. The DELETE drops only
1823
+ * the keys the new scope map no longer carries and runs before the upsert,
1824
+ * so its subquery reads the pre-upsert scope map; keys present in both
1825
+ * maps are left alone and the `INSERT OR IGNORE` writes nothing for them.
1826
+ */
1827
+ protected writeRow(table: string, row: StoredRow): void {
1828
+ const p = this.partition;
1829
+ const compiled = this.table(table);
1830
+ this.run(
1831
+ `${deleteSqliteRowScopesSql(compiled)}
1832
+ AND (var, value) NOT IN (SELECT key, value FROM json_each(?))`,
1833
+ [p, table, row.rowId, p, row.rowId, JSON.stringify(row.scopes)],
1834
+ );
1835
+ this.run(
1836
+ upsertSql(compiled, 'sqlite'),
1837
+ upsertValues(compiled, p, row, 'sqlite'),
1838
+ );
1839
+ for (const [variable, value] of Object.entries(row.scopes)) {
1840
+ this.run(
1841
+ 'INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)',
1842
+ [p, table, variable, value, row.rowId],
1843
+ );
1844
+ }
1845
+ }
1846
+
1847
+ async deleteRow(table: string, rowId: string): Promise<void> {
1848
+ this.assertOpen();
1849
+ const p = this.partition;
1850
+ const compiled = this.table(table);
1851
+ this.run(deleteSqliteRowScopesSql(compiled), [p, table, rowId, p, rowId]);
1852
+ this.run(deleteRowSql(compiled, 'sqlite'), [p, rowId]);
1853
+ // §5.9.4: a deleted row references no blobs.
1854
+ this.run(
1855
+ 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
1856
+ [p, table, rowId],
1857
+ );
1858
+ }
1859
+
1860
+ async setBlobRefs(
1861
+ table: string,
1862
+ rowId: string,
1863
+ blobIds: readonly string[],
1864
+ ): Promise<void> {
1865
+ this.assertOpen();
1866
+ const p = this.partition;
1867
+ // Replace the row's reference set atomically (§5.9.4).
1868
+ this.run(
1869
+ 'DELETE FROM sync_blob_refs WHERE partition=? AND tbl=? AND row_id=?',
1870
+ [p, table, rowId],
1871
+ );
1872
+ for (const blobId of blobIds) {
1873
+ this.run(
1874
+ 'INSERT OR IGNORE INTO sync_blob_refs(partition, tbl, row_id, blob_id) VALUES (?,?,?,?)',
1875
+ [p, table, rowId, blobId],
1876
+ );
1877
+ }
1878
+ }
1879
+
1880
+ async appendCommit(commit: NewCommit): Promise<number> {
1881
+ this.assertOpen();
1882
+ const p = this.partition;
1883
+ const commitSeq = await this.appendCommitRow(commit);
1884
+ const liveAfterDelete = rowsLiveAfterDelete(commit.changes);
1885
+ commit.changes.forEach((change, idx) => {
1886
+ this.run(
1887
+ 'INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)',
1888
+ [
1889
+ p,
1890
+ commitSeq,
1891
+ idx,
1892
+ change.table,
1893
+ change.rowId,
1894
+ change.op === 'upsert' ? 1 : 2,
1895
+ change.rowVersion ?? null,
1896
+ JSON.stringify(change.scopes),
1897
+ change.payload ?? null,
1898
+ ],
1899
+ );
1900
+ if (
1901
+ change.op === 'delete' &&
1902
+ !liveAfterDelete.has(`${change.table}\u0000${change.rowId}`)
1903
+ ) {
1904
+ // §5 delete precedence: every applied delete leaves a tombstone,
1905
+ // pruned with the commit log (§4.6). A delete that the same commit
1906
+ // follows with an upsert is a §2.2 scope move, not a deletion.
1907
+ this.run(
1908
+ `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq, server_version, scopes) VALUES (?,?,?,?,?,?)
1909
+ ON CONFLICT(partition, tbl, row_id) DO UPDATE SET commit_seq=excluded.commit_seq, server_version=excluded.server_version, scopes=excluded.scopes`,
1910
+ [
1911
+ p,
1912
+ change.table,
1913
+ change.rowId,
1914
+ commitSeq,
1915
+ change.deletedVersion ?? null,
1916
+ JSON.stringify(change.scopes),
1917
+ ],
1918
+ );
1919
+ }
1920
+ for (const [variable, value] of Object.entries(change.scopes)) {
1921
+ this.run(
1922
+ 'INSERT OR IGNORE INTO sync_change_scopes(partition, tbl, var, value, commit_seq) VALUES (?,?,?,?,?)',
1923
+ [p, change.table, variable, value, commitSeq],
1924
+ );
1925
+ }
1926
+ });
1927
+ return commitSeq;
1928
+ }
1929
+
1930
+ async putPushResult(
1931
+ clientId: string,
1932
+ clientCommitId: string,
1933
+ result: StoredPushResult,
1934
+ ): Promise<void> {
1935
+ this.assertOpen();
1936
+ this.run(
1937
+ 'INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)',
1938
+ [this.partition, clientId, clientCommitId, serializePushResult(result)],
1939
+ );
1940
+ }
1941
+
1942
+ async enqueueReactions(reactions: readonly NewReaction[]): Promise<void> {
1943
+ this.assertOpen();
1944
+ for (const reaction of reactions) {
1945
+ this.run(
1946
+ `INSERT INTO sync_reactions(
1947
+ partition, idempotency_key, type, version, payload,
1948
+ source_client_id, source_client_commit_id, source_commit_seq,
1949
+ created_at_ms, available_at_ms, status, attempts, max_attempts
1950
+ ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`,
1951
+ [
1952
+ this.partition,
1953
+ reaction.idempotencyKey,
1954
+ reaction.type,
1955
+ reaction.version,
1956
+ JSON.stringify(reaction.payload),
1957
+ reaction.sourceClientId,
1958
+ reaction.sourceClientCommitId,
1959
+ reaction.sourceCommitSeq,
1960
+ reaction.createdAtMs,
1961
+ reaction.createdAtMs,
1962
+ reaction.maxAttempts,
1963
+ ],
1964
+ );
1965
+ }
1966
+ }
1967
+ }