@syncular/server 0.58.0 → 0.60.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 (103) hide show
  1. package/README.md +49 -36
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +46 -40
  4. package/dist/blob-handlers.d.ts +25 -31
  5. package/dist/blob-handlers.js +63 -41
  6. package/dist/blob-store.d.ts +42 -24
  7. package/dist/blob-store.js +0 -0
  8. package/dist/bucket-blob-store.d.ts +12 -8
  9. package/dist/bucket-blob-store.js +54 -45
  10. package/dist/bucket-segment-store.js +18 -16
  11. package/dist/content-encoding.d.ts +5 -2
  12. package/dist/content-encoding.js +42 -13
  13. package/dist/context.d.ts +19 -5
  14. package/dist/context.js +19 -1
  15. package/dist/d1-storage.d.ts +14 -98
  16. package/dist/d1-storage.js +249 -1119
  17. package/dist/errors.js +16 -0
  18. package/dist/events.d.ts +36 -18
  19. package/dist/frame-bytes.js +24 -6
  20. package/dist/handler.js +503 -208
  21. package/dist/local-authority.d.ts +2 -0
  22. package/dist/local-authority.js +24 -12
  23. package/dist/object-bucket.d.ts +2 -0
  24. package/dist/operations-realtime.js +69 -50
  25. package/dist/operations.d.ts +5 -2
  26. package/dist/operations.js +20 -29
  27. package/dist/pg-executor-pglite.d.ts +5 -6
  28. package/dist/pg-executor-pglite.js +22 -14
  29. package/dist/pg-executor.d.ts +4 -1
  30. package/dist/postgres-storage.d.ts +24 -19
  31. package/dist/postgres-storage.js +420 -262
  32. package/dist/pull.d.ts +70 -47
  33. package/dist/pull.js +270 -301
  34. package/dist/push.d.ts +12 -3
  35. package/dist/push.js +361 -173
  36. package/dist/realtime.d.ts +85 -39
  37. package/dist/realtime.js +355 -219
  38. package/dist/relational-rows.d.ts +21 -66
  39. package/dist/relational-rows.js +28 -109
  40. package/dist/s3-blob-store.d.ts +11 -12
  41. package/dist/s3-blob-store.js +20 -13
  42. package/dist/s3-object-bucket.d.ts +8 -1
  43. package/dist/s3-object-bucket.js +16 -3
  44. package/dist/schema.d.ts +14 -0
  45. package/dist/schema.js +23 -0
  46. package/dist/scopes.d.ts +6 -2
  47. package/dist/scopes.js +22 -4
  48. package/dist/seed.js +10 -16
  49. package/dist/segment-download.d.ts +4 -1
  50. package/dist/segment-download.js +22 -6
  51. package/dist/signed-url.d.ts +2 -2
  52. package/dist/signed-url.js +9 -2
  53. package/dist/sigv4.d.ts +8 -2
  54. package/dist/sigv4.js +8 -4
  55. package/dist/sqlite-blob-store.d.ts +1 -1
  56. package/dist/sqlite-blob-store.js +23 -22
  57. package/dist/sqlite-dialect.d.ts +164 -84
  58. package/dist/sqlite-dialect.js +1145 -150
  59. package/dist/sqlite-lease-store.js +13 -18
  60. package/dist/sqlite-storage.d.ts +9 -62
  61. package/dist/sqlite-storage.js +303 -1123
  62. package/dist/storage-query.d.ts +30 -1
  63. package/dist/storage-query.js +68 -0
  64. package/dist/storage.d.ts +185 -63
  65. package/dist/storage.js +15 -0
  66. package/package.json +2 -2
  67. package/src/admin.ts +99 -57
  68. package/src/blob-handlers.ts +91 -72
  69. package/src/blob-store.ts +0 -0
  70. package/src/bucket-blob-store.ts +75 -48
  71. package/src/bucket-segment-store.ts +20 -15
  72. package/src/content-encoding.ts +48 -16
  73. package/src/context.ts +33 -6
  74. package/src/d1-storage.ts +350 -1700
  75. package/src/errors.ts +16 -0
  76. package/src/events.ts +37 -18
  77. package/src/frame-bytes.ts +26 -6
  78. package/src/handler.ts +654 -261
  79. package/src/local-authority.ts +27 -14
  80. package/src/object-bucket.ts +2 -0
  81. package/src/operations-realtime.ts +85 -61
  82. package/src/operations.ts +44 -42
  83. package/src/pg-executor-pglite.ts +27 -23
  84. package/src/pg-executor.ts +5 -1
  85. package/src/postgres-storage.ts +557 -354
  86. package/src/pull.ts +406 -440
  87. package/src/push.ts +466 -220
  88. package/src/realtime.ts +447 -290
  89. package/src/relational-rows.ts +43 -121
  90. package/src/s3-blob-store.ts +23 -13
  91. package/src/s3-object-bucket.ts +20 -2
  92. package/src/schema.ts +31 -0
  93. package/src/scopes.ts +23 -3
  94. package/src/seed.ts +13 -20
  95. package/src/segment-download.ts +33 -7
  96. package/src/signed-url.ts +10 -4
  97. package/src/sigv4.ts +17 -4
  98. package/src/sqlite-blob-store.ts +27 -26
  99. package/src/sqlite-dialect.ts +1851 -199
  100. package/src/sqlite-lease-store.ts +12 -23
  101. package/src/sqlite-storage.ts +390 -1821
  102. package/src/storage-query.ts +102 -0
  103. package/src/storage.ts +215 -67
@@ -4,6 +4,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage';
4
4
  import {
5
5
  clientRoundState,
6
6
  PARTITION_TOUCH_INTERVAL_MS,
7
+ commitDeleteFloor,
7
8
  rowsLiveAfterDelete,
8
9
  serveGateRefusal,
9
10
  } from './storage';
@@ -18,13 +19,13 @@ import { serveNotReadyError } from './readiness';
18
19
  *
19
20
  * - both the commit log and the current-row table carry a (table, var,
20
21
  * value) inverted scope index;
21
- * - `readCommitWindow`/`scanRows` select candidates through that index
22
- * (`sync_change_scopes` / `sync_row_scopes`), ordered + LIMITed at the
23
- * index, then verify the full multi-variable match against the stored
24
- * scope map — never a log or table scan;
22
+ * - `readLiveWindow`/`scanRows` select candidates through an index
23
+ * (`sync_change_scopes_by_key` / `sync_row_scopes`), ordered + LIMITed
24
+ * at the index, then verify the full multi-variable match against the
25
+ * stored scope map — never a log or table scan;
25
26
  * - the candidate indexes are *covering* for their selection: the ordered
26
- * column (`commit_seq` / `row_id`) sits in the index key after
27
- * (tbl, var, value), so the planner does an index range scan and returns
27
+ * column (`commit_seq` / `row_id`) sits in the index key after the scope
28
+ * key, so the planner does an index range scan and returns
28
29
  * already-ordered candidates without a heap sort. `test/postgres-explain
29
30
  * .test.ts` asserts an `Index` node (never `Seq Scan`) so the regression
30
31
  * cannot silently return.
@@ -45,7 +46,7 @@ import { serveNotReadyError } from './readiness';
45
46
  * would leave gaps on rollback, which the pull-window arithmetic in §4.5
46
47
  * does not tolerate). Cross-partition pushes never contend.
47
48
  */
48
- import type { PushOperationResult, ScopeMap } from '@syncular/core';
49
+ import type { PushOperationResult, UnitScopes } from '@syncular/core';
49
50
  import {
50
51
  bindAuthoritativePartition,
51
52
  type BoundAuthoritativeQuery,
@@ -63,8 +64,6 @@ import {
63
64
  import {
64
65
  assertPhysicalColumns,
65
66
  assertStoredLayouts,
66
- COMMIT_WINDOW_BATCH_SQL,
67
- LATEST_SCOPED_CHANGE_BATCH_SQL,
68
67
  deleteRowSql,
69
68
  dropTableDdl,
70
69
  indexRowPageStatement,
@@ -90,7 +89,7 @@ import {
90
89
  indexSignature,
91
90
  schemaDdl,
92
91
  serverIndexDdl,
93
- selectRowScopesSql,
92
+ rowsReferencingBlobSql,
94
93
  selectRowSql,
95
94
  selectRowsSql,
96
95
  prefetchRowsBatchSql,
@@ -108,20 +107,23 @@ import type {
108
107
  ClientPushResult,
109
108
  ClientRecord,
110
109
  ClientRecordWriteOptions,
111
- ClientSubscription,
112
110
  CommitChangeSummary,
113
111
  CommitDetail,
114
112
  CommitMetadata,
115
113
  CommitMetadataQuery,
116
- CommitWindowQuery,
117
114
  DurableJsonValue,
118
115
  IndexRowScanQuery,
116
+ LiveWindow,
117
+ LiveWindowQuery,
119
118
  NewChange,
120
119
  NewCommit,
121
120
  NewReaction,
121
+ OutboxSequence,
122
+ OutboxSettlement,
122
123
  PartitionRegistryEntry,
123
124
  PreparedPushApply,
124
125
  PrunedReactionCounts,
126
+ PushWatermark,
125
127
  ReactionClaimQuery,
126
128
  ReactionFailure,
127
129
  ReactionFailureUpdate,
@@ -140,28 +142,37 @@ import type {
140
142
  StorageTransaction,
141
143
  StoredChange,
142
144
  StoredCheckpoint,
143
- StoredCommit,
144
145
  StoredPushResult,
145
146
  StoredReaction,
146
147
  StoredRow,
148
+ Tombstone,
147
149
  } from './storage';
148
150
  import {
149
151
  isPostgresConstraintError,
150
152
  StorageConstraintError,
151
153
  } from './storage-errors';
152
- import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
154
+ import {
155
+ assertScopeIndexedScan,
156
+ readLiveWindowPages,
157
+ resolveIndexRowScan,
158
+ } from './storage-query';
153
159
 
154
160
  /**
155
161
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
156
162
  *
157
163
  * Covering index design (the reason this file exists):
158
- * - `sync_change_scopes_pk (partition, tbl, var, value, commit_seq)` — the
159
- * candidate scan for `readCommitWindow` ranges on the (partition, tbl,
160
- * var, value IN …) prefix and returns `commit_seq` already ascending;
161
- * - `sync_row_scopes_pk (partition, tbl, var, value, row_id)` — same shape
162
- * for `scanRows`, ordered by `row_id`.
163
- * Both are the PRIMARY KEY, so they are the clustering/covering index for
164
- * their table.
164
+ * - `sync_change_scopes_by_key (partition, var, value, commit_seq)`: the
165
+ * §4.5 live scan ranges once per unit key on the (partition, var, value)
166
+ * prefix across tables and returns `commit_seq` already ascending;
167
+ * - `sync_change_scopes_pk (partition, tbl, var, value, commit_seq)`:
168
+ * the §4.7 scope pin, erasure and pruning name the table;
169
+ * - `sync_row_scopes_pk (partition, tbl, var, value, row_id)`: the same
170
+ * shape for `scanRows`, ordered by `row_id`.
171
+ *
172
+ * The §6.3.2 watermark delete and the §9 settlement of results stored
173
+ * before wire version 4 (NULL `outbox_id`) range over the `(partition,
174
+ * client_id)` prefix of `sync_push_results`' PRIMARY KEY, which the
175
+ * watermark keeps to one request's results per outbox.
165
176
  *
166
177
  * `sync_row_scopes_by_row (partition, tbl, row_id)` is the one secondary
167
178
  * scope index: `writeRowsOn` and `deleteRow` replace a row's scope entries
@@ -184,7 +195,8 @@ export const POSTGRES_DDL = `
184
195
  CREATE TABLE IF NOT EXISTS sync_partitions(
185
196
  partition TEXT PRIMARY KEY,
186
197
  max_commit_seq BIGINT NOT NULL DEFAULT 0,
187
- horizon_seq BIGINT NOT NULL DEFAULT 0
198
+ horizon_seq BIGINT NOT NULL DEFAULT 0,
199
+ delete_floor BIGINT NOT NULL DEFAULT 0
188
200
  );
189
201
  CREATE TABLE IF NOT EXISTS sync_partition_registry(
190
202
  partition TEXT PRIMARY KEY,
@@ -221,11 +233,21 @@ CREATE TABLE IF NOT EXISTS sync_change_scopes(
221
233
  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,
222
234
  PRIMARY KEY(partition, tbl, var, value, commit_seq)
223
235
  );
236
+ CREATE INDEX IF NOT EXISTS sync_change_scopes_by_key
237
+ ON sync_change_scopes(partition, var, value, commit_seq);
224
238
  CREATE TABLE IF NOT EXISTS sync_push_results(
225
239
  partition TEXT NOT NULL, client_id TEXT NOT NULL,
226
240
  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,
241
+ outbox_id TEXT, client_seq BIGINT,
227
242
  PRIMARY KEY(partition, client_id, client_commit_id)
228
243
  );
244
+ ALTER TABLE sync_push_results ADD COLUMN IF NOT EXISTS outbox_id TEXT;
245
+ ALTER TABLE sync_push_results ADD COLUMN IF NOT EXISTS client_seq BIGINT;
246
+ CREATE TABLE IF NOT EXISTS sync_push_watermarks(
247
+ partition TEXT NOT NULL, client_id TEXT NOT NULL, outbox_id TEXT NOT NULL,
248
+ through_seq BIGINT NOT NULL,
249
+ PRIMARY KEY(partition, client_id, outbox_id)
250
+ );
229
251
  CREATE TABLE IF NOT EXISTS sync_reactions(
230
252
  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,
231
253
  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,
@@ -249,10 +271,12 @@ CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
249
271
  CREATE TABLE IF NOT EXISTS sync_clients(
250
272
  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
251
273
  wire_version INTEGER NOT NULL DEFAULT 1,
252
- cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,
274
+ cursor BIGINT NOT NULL,
253
275
  updated_at_ms BIGINT NOT NULL,
254
276
  last_round_at_ms BIGINT, last_error_code TEXT,
255
277
  consecutive_failures INTEGER NOT NULL DEFAULT 0,
278
+ schema_version INTEGER, units JSONB, registration_digest BYTEA,
279
+ catching_up JSONB NOT NULL DEFAULT '[]',
256
280
  PRIMARY KEY(partition, client_id)
257
281
  );
258
282
  ALTER TABLE sync_clients
@@ -261,6 +285,19 @@ ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS last_round_at_ms BIGINT;
261
285
  ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS last_error_code TEXT;
262
286
  ALTER TABLE sync_clients
263
287
  ADD COLUMN IF NOT EXISTS consecutive_failures INTEGER NOT NULL DEFAULT 0;
288
+ ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS schema_version INTEGER;
289
+ ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS units JSONB;
290
+ ALTER TABLE sync_clients ADD COLUMN IF NOT EXISTS registration_digest BYTEA;
291
+ ALTER TABLE sync_clients
292
+ ADD COLUMN IF NOT EXISTS catching_up JSONB NOT NULL DEFAULT '[]';
293
+ -- §9: a database from before wire version 4 (its client records still hold
294
+ -- subscriptions) starts the horizon at its last commit.
295
+ UPDATE sync_partitions SET horizon_seq = max_commit_seq
296
+ WHERE EXISTS (SELECT 1 FROM information_schema.columns
297
+ WHERE table_schema = current_schema()
298
+ AND table_name = 'sync_clients'
299
+ AND column_name = 'subscriptions');
300
+ ALTER TABLE sync_clients DROP COLUMN IF EXISTS subscriptions;
264
301
  CREATE TABLE IF NOT EXISTS sync_blob_refs(
265
302
  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
266
303
  blob_id TEXT NOT NULL,
@@ -270,9 +307,18 @@ CREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob
270
307
  ON sync_blob_refs(partition, blob_id);
271
308
  CREATE TABLE IF NOT EXISTS sync_tombstones(
272
309
  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,
273
- commit_seq BIGINT NOT NULL,
310
+ commit_seq BIGINT NOT NULL, server_version BIGINT, scopes JSONB,
274
311
  PRIMARY KEY(partition, tbl, row_id)
275
312
  );
313
+ ALTER TABLE sync_tombstones ADD COLUMN IF NOT EXISTS server_version BIGINT;
314
+ ALTER TABLE sync_tombstones ADD COLUMN IF NOT EXISTS scopes JSONB;
315
+ ALTER TABLE sync_partitions
316
+ ADD COLUMN IF NOT EXISTS delete_floor BIGINT NOT NULL DEFAULT 0;
317
+ UPDATE sync_partitions SET delete_floor = t.version
318
+ FROM (SELECT partition, max(server_version) AS version
319
+ FROM sync_tombstones GROUP BY partition) t
320
+ WHERE t.partition = sync_partitions.partition
321
+ AND t.version > sync_partitions.delete_floor;
276
322
  CREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(
277
323
  partition TEXT NOT NULL, name TEXT NOT NULL,
278
324
  schema_version INTEGER NOT NULL,
@@ -430,6 +476,7 @@ interface ServeGateRow {
430
476
  log_epoch: string | null;
431
477
  pending: unknown;
432
478
  result?: unknown;
479
+ delete_floor?: unknown;
433
480
  }
434
481
 
435
482
  /**
@@ -480,6 +527,8 @@ interface PrefetchRow {
480
527
  readonly payload: unknown;
481
528
  readonly column_versions: unknown;
482
529
  readonly tombstone_seq: unknown;
530
+ readonly tombstone_version: unknown;
531
+ readonly tombstone_scopes: unknown;
483
532
  }
484
533
 
485
534
  type AdmissionRow = ServeGateRow & Partial<PrefetchRow>;
@@ -510,6 +559,7 @@ async function readAdmissionOn(
510
559
  ): Promise<{
511
560
  gate: ServeGate;
512
561
  persisted: StoredPushResult | undefined;
562
+ deleteFloor: number;
513
563
  prefetched: readonly PrefetchRow[];
514
564
  }> {
515
565
  const params: unknown[] = [
@@ -520,7 +570,8 @@ async function readAdmissionOn(
520
570
  ];
521
571
  let statement = `SELECT ${SERVE_GATE_PROJECTION},
522
572
  (SELECT result FROM sync_push_results
523
- WHERE partition=$1 AND client_id=$3 AND client_commit_id=$4) AS result`;
573
+ WHERE partition=$1 AND client_id=$3 AND client_commit_id=$4) AS result,
574
+ (SELECT delete_floor FROM sync_partitions WHERE partition=$1) AS delete_floor`;
524
575
  if (prefetch !== undefined && prefetch.specs.length > 0) {
525
576
  params.push(JSON.stringify(prefetch.specs));
526
577
  // The gate row pads the read-ahead columns with typed NULLs so both
@@ -529,11 +580,13 @@ async function readAdmissionOn(
529
580
  NULL::text AS tbl, NULL::text AS lookup_id, NULL::text AS row_id,
530
581
  NULL::bigint AS server_version, NULL::jsonb AS scopes,
531
582
  NULL::bytea AS payload, NULL::bytea AS column_versions,
532
- NULL::bigint AS tombstone_seq
583
+ NULL::bigint AS tombstone_seq, NULL::bigint AS tombstone_version,
584
+ NULL::jsonb AS tombstone_scopes
533
585
  UNION ALL
534
- SELECT NULL::bigint, NULL::text, NULL::json, NULL::jsonb,
586
+ SELECT NULL::bigint, NULL::text, NULL::json, NULL::jsonb, NULL::bigint,
535
587
  p.tbl, p.lookup_id, p.row_id, p.server_version, p.scopes,
536
- p.payload, p.column_versions, p.tombstone_seq
588
+ p.payload, p.column_versions, p.tombstone_seq,
589
+ p.tombstone_version, p.tombstone_scopes
537
590
  FROM (${prefetchRowsBatchSql(prefetch.tables, {
538
591
  partition: '$1',
539
592
  specs: `$${params.length}`,
@@ -544,6 +597,8 @@ async function readAdmissionOn(
544
597
  return {
545
598
  gate: toServeGate(gateRow),
546
599
  persisted: toPersistedPushResult(gateRow?.result),
600
+ // asNumber maps the NULL of a partition without a commit to 0.
601
+ deleteFloor: asNumber(gateRow?.delete_floor),
547
602
  prefetched: rows.filter(
548
603
  (row): row is AdmissionRow & PrefetchRow =>
549
604
  row.tbl !== null && row.tbl !== undefined,
@@ -783,23 +838,6 @@ interface ChangeRecord {
783
838
  payload: unknown;
784
839
  }
785
840
 
786
- /**
787
- * One result row of `COMMIT_WINDOW_BATCH_SQL` (candidate LEFT JOIN commit meta
788
- * LEFT JOIN changes): meta/change columns are NULL when the joined row
789
- * vanished (LEFT JOIN contract).
790
- */
791
- interface CommitWindowRecord {
792
- commit_seq: unknown;
793
- actor_id: string | null;
794
- created_at_ms: unknown;
795
- tbl: string | null;
796
- row_id: string | null;
797
- op: unknown;
798
- row_version: unknown;
799
- scopes: unknown;
800
- payload: unknown;
801
- }
802
-
803
841
  function toStoredRow(record: RowRecord): StoredRow {
804
842
  return {
805
843
  rowId: record.row_id,
@@ -812,6 +850,68 @@ function toStoredRow(record: RowRecord): StoredRow {
812
850
  };
813
851
  }
814
852
 
853
+ function toTombstone(
854
+ seq: unknown,
855
+ version: unknown,
856
+ scopes: unknown,
857
+ ): Tombstone | null {
858
+ if (seq === null || seq === undefined) return null;
859
+ return {
860
+ commitSeq: asNumber(seq),
861
+ ...(version === null || version === undefined
862
+ ? {}
863
+ : { serverVersion: asNumber(version) }),
864
+ ...(scopes === null || scopes === undefined
865
+ ? {}
866
+ : { scopes: asJson<Record<string, string>>(scopes) }),
867
+ };
868
+ }
869
+
870
+ const CLIENT_RECORD_COLUMNS =
871
+ 'client_id, actor_id, wire_version, cursor, updated_at_ms, schema_version, units, registration_digest, catching_up, last_round_at_ms, last_error_code, consecutive_failures';
872
+
873
+ function toClientRecord(record: {
874
+ client_id: string;
875
+ actor_id: string;
876
+ wire_version: unknown;
877
+ cursor: unknown;
878
+ updated_at_ms: unknown;
879
+ schema_version: unknown;
880
+ units: unknown;
881
+ registration_digest: unknown;
882
+ catching_up: unknown;
883
+ last_round_at_ms: unknown;
884
+ last_error_code: string | null;
885
+ consecutive_failures: unknown;
886
+ }): ClientRecord {
887
+ return {
888
+ clientId: record.client_id,
889
+ actorId: record.actor_id,
890
+ wireVersion: asNumber(record.wire_version),
891
+ cursor: asNumber(record.cursor),
892
+ updatedAtMs: asNumber(record.updated_at_ms),
893
+ ...(record.schema_version === null
894
+ ? {}
895
+ : { schemaVersion: asNumber(record.schema_version) }),
896
+ ...(record.units === null || record.registration_digest === null
897
+ ? {}
898
+ : {
899
+ registration: {
900
+ units: asJson<UnitScopes[]>(record.units),
901
+ digest: asBytes(record.registration_digest),
902
+ },
903
+ }),
904
+ catchingUp: asJson<ClientRecord['catchingUp']>(record.catching_up),
905
+ ...clientRoundState(
906
+ record.last_round_at_ms === null
907
+ ? null
908
+ : asNumber(record.last_round_at_ms),
909
+ record.last_error_code,
910
+ asNumber(record.consecutive_failures),
911
+ ),
912
+ };
913
+ }
914
+
815
915
  function toStoredChange(record: ChangeRecord): StoredChange {
816
916
  return {
817
917
  table: record.tbl,
@@ -1144,7 +1244,7 @@ class PostgresTransaction implements StorageTransaction {
1144
1244
  * key, so the next read goes to the database again.
1145
1245
  */
1146
1246
  readonly #prefetchedRows = new Map<string, StoredRow | null>();
1147
- readonly #prefetchedTombstones = new Map<string, number | null>();
1247
+ readonly #prefetchedTombstones = new Map<string, Tombstone | null>();
1148
1248
  /**
1149
1249
  * Upserts staged per table (row id → row and its push operation index).
1150
1250
  * Every statement of this transaction writes them first (see the
@@ -1325,7 +1425,7 @@ class PostgresTransaction implements StorageTransaction {
1325
1425
  // `#client` flushes this transaction's staged upserts first, so the rows
1326
1426
  // are the final candidate state.
1327
1427
  const { rows: records } = await this.#client.query<RowRecord>(
1328
- selectRowsSql(this.#resolveTable(table)),
1428
+ selectRowsSql(this.#resolveTable(table), 'postgres'),
1329
1429
  [this.#partition, missing],
1330
1430
  );
1331
1431
  for (const record of records) rows.set(record.row_id, toStoredRow(record));
@@ -1357,7 +1457,7 @@ class PostgresTransaction implements StorageTransaction {
1357
1457
  this.#recordPrefetched(rows);
1358
1458
  }
1359
1459
 
1360
- /** Answer the following `getRow`/`getTombstoneSeq` calls from a read snapshot. */
1460
+ /** Answer the following `getRow`/`getTombstone` calls from a read snapshot. */
1361
1461
  #recordPrefetched(records: readonly PrefetchRow[]): void {
1362
1462
  for (const record of records) {
1363
1463
  const key = `${record.tbl}\u0000${record.lookup_id}`;
@@ -1369,26 +1469,35 @@ class PostgresTransaction implements StorageTransaction {
1369
1469
  );
1370
1470
  this.#prefetchedTombstones.set(
1371
1471
  key,
1372
- record.tombstone_seq === null || record.tombstone_seq === undefined
1373
- ? null
1374
- : asNumber(record.tombstone_seq),
1472
+ toTombstone(
1473
+ record.tombstone_seq,
1474
+ record.tombstone_version,
1475
+ record.tombstone_scopes,
1476
+ ),
1375
1477
  );
1376
1478
  }
1377
1479
  }
1378
1480
 
1379
- async getTombstoneSeq(
1481
+ async getTombstone(
1380
1482
  table: string,
1381
1483
  rowId: string,
1382
- ): Promise<number | undefined> {
1484
+ ): Promise<Tombstone | undefined> {
1383
1485
  this.#assertOpen();
1384
1486
  const prefetched = this.#prefetchedTombstones.get(`${table}\u0000${rowId}`);
1385
1487
  if (prefetched !== undefined) return prefetched ?? undefined;
1386
- const { rows } = await this.#client.query<{ commit_seq: unknown }>(
1387
- 'SELECT commit_seq FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
1488
+ const { rows } = await this.#client.query<{
1489
+ commit_seq: unknown;
1490
+ server_version: unknown;
1491
+ scopes: unknown;
1492
+ }>(
1493
+ 'SELECT commit_seq, server_version, scopes FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
1388
1494
  [this.#partition, table, rowId],
1389
1495
  );
1390
- const seq = rows[0]?.commit_seq;
1391
- return seq === null || seq === undefined ? undefined : asNumber(seq);
1496
+ const row = rows[0];
1497
+ return (
1498
+ toTombstone(row?.commit_seq, row?.server_version, row?.scopes) ??
1499
+ undefined
1500
+ );
1392
1501
  }
1393
1502
 
1394
1503
  async clearTombstone(table: string, rowId: string): Promise<void> {
@@ -1481,6 +1590,7 @@ class PostgresTransaction implements StorageTransaction {
1481
1590
  readonly table: string;
1482
1591
  readonly rowIds: readonly string[];
1483
1592
  }[] = [],
1593
+ outbox?: OutboxSettlement,
1484
1594
  ): Promise<PreparedPushApply> {
1485
1595
  this.#assertOpen();
1486
1596
  // The lock is its own statement: a READ COMMITTED statement's snapshot is
@@ -1489,6 +1599,10 @@ class PostgresTransaction implements StorageTransaction {
1489
1599
  // and the read into one statement would miss a duplicate that committed
1490
1600
  // while this transaction waited.
1491
1601
  await this.lockPartition();
1602
+ const watermark =
1603
+ outbox === undefined
1604
+ ? undefined
1605
+ : await this.#settleOutbox(clientId, clientCommitId, outbox);
1492
1606
  const tables: CompiledTable[] = [];
1493
1607
  const specs: { tbl: string; ids: string[] }[] = [];
1494
1608
  for (const target of targets) {
@@ -1510,7 +1624,77 @@ class PostgresTransaction implements StorageTransaction {
1510
1624
  specs.length === 0 ? undefined : { tables, specs },
1511
1625
  );
1512
1626
  this.#recordPrefetched(admission.prefetched);
1513
- return { gate: admission.gate, persisted: admission.persisted };
1627
+ return {
1628
+ gate: admission.gate,
1629
+ persisted: admission.persisted,
1630
+ deleteFloor: admission.deleteFloor,
1631
+ ...(watermark === undefined ? {} : { watermark }),
1632
+ };
1633
+ }
1634
+
1635
+ /**
1636
+ * The §9 settlement and §6.3.2 steps 1 and 2 under the partition lock,
1637
+ * before the candidate savepoint, so a rejection keeps them. Two
1638
+ * statements: the settlement touches disjoint rows (outside and inside the
1639
+ * request), and the watermark delete must see its sequences.
1640
+ */
1641
+ async #settleOutbox(
1642
+ clientId: string,
1643
+ clientCommitId: string,
1644
+ outbox: OutboxSettlement,
1645
+ ): Promise<number> {
1646
+ const first = outbox.commits[0];
1647
+ const last = outbox.commits.at(-1);
1648
+ if (
1649
+ first === undefined ||
1650
+ last === undefined ||
1651
+ first.clientCommitId !== clientCommitId
1652
+ ) {
1653
+ throw new Error("outbox settlement rides the request's first commit");
1654
+ }
1655
+ const commits = JSON.stringify(
1656
+ outbox.commits.map((commit) => ({
1657
+ id: commit.clientCommitId,
1658
+ seq: commit.clientSeq,
1659
+ })),
1660
+ );
1661
+ // §9 (b): with no pre-upgrade result on the request's last commit, every
1662
+ // remaining one outside the request left the outbox; (a) assigns the
1663
+ // request's sequences to its pre-upgrade results.
1664
+ await this.#client.query(
1665
+ `WITH c AS (SELECT * FROM jsonb_to_recordset($4::text::jsonb) AS c(id text, seq bigint)),
1666
+ b AS (DELETE FROM sync_push_results
1667
+ WHERE partition=$1 AND client_id=$2 AND outbox_id IS NULL
1668
+ AND client_commit_id NOT IN (SELECT id FROM c)
1669
+ AND NOT EXISTS (SELECT 1 FROM sync_push_results
1670
+ WHERE partition=$1 AND client_id=$2 AND client_commit_id=$5
1671
+ AND outbox_id IS NULL)),
1672
+ a AS (UPDATE sync_push_results r SET outbox_id=$3, client_seq=c.seq FROM c
1673
+ WHERE r.partition=$1 AND r.client_id=$2 AND r.outbox_id IS NULL
1674
+ AND r.client_commit_id=c.id)
1675
+ SELECT 1`,
1676
+ [
1677
+ this.#partition,
1678
+ clientId,
1679
+ outbox.outboxId,
1680
+ commits,
1681
+ last.clientCommitId,
1682
+ ],
1683
+ );
1684
+ const { rows } = await this.#client.query<{ through_seq: unknown }>(
1685
+ `WITH w AS (
1686
+ INSERT INTO sync_push_watermarks(partition, client_id, outbox_id, through_seq)
1687
+ VALUES ($1,$2,$3,$4)
1688
+ ON CONFLICT (partition, client_id, outbox_id) DO UPDATE
1689
+ SET through_seq=GREATEST(sync_push_watermarks.through_seq, EXCLUDED.through_seq)
1690
+ RETURNING through_seq),
1691
+ d AS (DELETE FROM sync_push_results
1692
+ WHERE partition=$1 AND client_id=$2 AND outbox_id=$3
1693
+ AND client_seq<(SELECT through_seq FROM w))
1694
+ SELECT through_seq FROM w`,
1695
+ [this.#partition, clientId, outbox.outboxId, first.clientSeq],
1696
+ );
1697
+ return asNumber(rows[0]?.through_seq);
1514
1698
  }
1515
1699
 
1516
1700
  async lockPartition(): Promise<void> {
@@ -1527,10 +1711,8 @@ class PostgresTransaction implements StorageTransaction {
1527
1711
  ): Promise<boolean> {
1528
1712
  this.#assertOpen();
1529
1713
  await this.#ensurePushSavepoint();
1530
- // `RETURNING`: the affected-row check must not depend on a driver's
1531
- // `rowCount` for a statement with no result rows. Bun.sql's canonical
1532
- // adapter derives `rowCount` from the returned rows, so a bare UPDATE
1533
- // reports 0 and the CAS would never advance on a real Bun.sql host.
1714
+ // `RETURNING`: `PgQueryable` reports returned rows only (no affected-row
1715
+ // count), so every affected-row check counts returned rows.
1534
1716
  const result = await this.#client.query<{ name: string }>(
1535
1717
  `UPDATE sync_backfill_checkpoints
1536
1718
  SET watermark=$1, observed_rows=$2, updated_at_ms=$3
@@ -1552,6 +1734,7 @@ class PostgresTransaction implements StorageTransaction {
1552
1734
  clientId: string,
1553
1735
  clientCommitId: string,
1554
1736
  result: StoredPushResult,
1737
+ sequence?: OutboxSequence,
1555
1738
  ): Promise<StoredPushResult> {
1556
1739
  this.#assertOpen();
1557
1740
  // Candidate rows that never reached the database are discarded with the
@@ -1567,6 +1750,7 @@ class PostgresTransaction implements StorageTransaction {
1567
1750
  clientId,
1568
1751
  clientCommitId,
1569
1752
  result,
1753
+ sequence,
1570
1754
  );
1571
1755
  await this.commit();
1572
1756
  return canonical;
@@ -1577,10 +1761,11 @@ class PostgresTransaction implements StorageTransaction {
1577
1761
  clientId: string,
1578
1762
  clientCommitId: string,
1579
1763
  result: StoredPushResult,
1764
+ sequence: OutboxSequence | undefined,
1580
1765
  ): Promise<StoredPushResult> {
1581
1766
  const { rows } = await this.#client.query<{ result: unknown }>(
1582
- `INSERT INTO sync_push_results(partition, client_id, client_commit_id, result)
1583
- VALUES ($1,$2,$3,$4)
1767
+ `INSERT INTO sync_push_results(partition, client_id, client_commit_id, result, outbox_id, client_seq)
1768
+ VALUES ($1,$2,$3,$4,$5,$6)
1584
1769
  ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING
1585
1770
  RETURNING result`,
1586
1771
  [
@@ -1588,6 +1773,8 @@ class PostgresTransaction implements StorageTransaction {
1588
1773
  clientId,
1589
1774
  clientCommitId,
1590
1775
  JSON.stringify(serializePushResult(result)),
1776
+ sequence?.outboxId ?? null,
1777
+ sequence?.clientSeq ?? null,
1591
1778
  ],
1592
1779
  );
1593
1780
  if (rows[0] !== undefined) {
@@ -1703,9 +1890,11 @@ class PostgresTransaction implements StorageTransaction {
1703
1890
  // Allocate the next dense commitSeq under a per-partition row lock: the
1704
1891
  // UPDATE … RETURNING serializes concurrent pushes to this partition and
1705
1892
  // never leaves a gap on rollback (see the file header).
1706
- const allocate = `INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 1)
1893
+ // §2.2: the allocation also raises the delete floor to the commit's.
1894
+ const allocate = `INSERT INTO sync_partitions(partition, max_commit_seq, delete_floor) VALUES ($1, 1, $7)
1707
1895
  ON CONFLICT (partition) DO UPDATE
1708
- SET max_commit_seq = sync_partitions.max_commit_seq + 1
1896
+ SET max_commit_seq = sync_partitions.max_commit_seq + 1,
1897
+ delete_floor = GREATEST(sync_partitions.delete_floor, EXCLUDED.delete_floor)
1709
1898
  RETURNING max_commit_seq`;
1710
1899
  const commitRow = `INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version)
1711
1900
  SELECT $1, allocated.max_commit_seq, $2, $3, $4, $5, $6 FROM allocated
@@ -1717,6 +1906,7 @@ class PostgresTransaction implements StorageTransaction {
1717
1906
  commit.actorId,
1718
1907
  commit.createdAtMs,
1719
1908
  this.#writerVersion,
1909
+ commitDeleteFloor(commit.changes),
1720
1910
  ];
1721
1911
  if (commit.changes.length === 0) {
1722
1912
  const { rows } = await q.query<{ commit_seq: unknown }>(
@@ -1741,8 +1931,9 @@ class PostgresTransaction implements StorageTransaction {
1741
1931
  // chunks run under the same commitSeq with their global idx. Serialized
1742
1932
  // scopes bind as text before parsing JSONB; drivers that encode JSONB
1743
1933
  // parameters would otherwise store the string as a scalar. A commit can
1744
- // delete one row twice, so a chunk's tombstone insert keeps one row per
1745
- // key and a later chunk updates it to the same commit_seq.
1934
+ // delete one row twice, so a chunk's tombstone insert keeps the latest
1935
+ // delete per key and a later chunk overwrites it with its own. `version`
1936
+ // is the change's row version (§2.2), which a delete's tombstone keeps.
1746
1937
  const valuesOf = (
1747
1938
  params: unknown[],
1748
1939
  slice: readonly NewChange[],
@@ -1755,7 +1946,7 @@ class PostgresTransaction implements StorageTransaction {
1755
1946
  change.table,
1756
1947
  change.rowId,
1757
1948
  change.op === 'upsert' ? 1 : 2,
1758
- change.rowVersion ?? null,
1949
+ change.rowVersion,
1759
1950
  JSON.stringify(change.scopes),
1760
1951
  change.payload ?? null,
1761
1952
  );
@@ -1769,16 +1960,21 @@ class PostgresTransaction implements StorageTransaction {
1769
1960
  )`;
1770
1961
  const tombstones = (
1771
1962
  movedParam: string,
1772
- ) => `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq)
1773
- SELECT DISTINCT ON (tbl, row_id) partition, tbl, row_id, commit_seq
1774
- FROM inserted
1775
- WHERE op = 2
1963
+ ) => `INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq, server_version, scopes)
1964
+ SELECT DISTINCT ON (inserted.tbl, inserted.row_id) inserted.partition,
1965
+ inserted.tbl, inserted.row_id, inserted.commit_seq,
1966
+ v.version, inserted.scopes
1967
+ FROM inserted JOIN v ON v.idx = inserted.idx
1968
+ WHERE inserted.op = 2
1776
1969
  AND NOT EXISTS (
1777
1970
  SELECT 1
1778
1971
  FROM jsonb_to_recordset(${movedParam}::text::jsonb) AS moved(tbl text, row_id text)
1779
1972
  WHERE moved.tbl = inserted.tbl AND moved.row_id = inserted.row_id)
1973
+ ORDER BY inserted.tbl, inserted.row_id, inserted.idx DESC
1780
1974
  ON CONFLICT (partition, tbl, row_id)
1781
- DO UPDATE SET commit_seq = excluded.commit_seq`;
1975
+ DO UPDATE SET commit_seq = excluded.commit_seq,
1976
+ server_version = excluded.server_version,
1977
+ scopes = excluded.scopes`;
1782
1978
  const firstSlice = commit.changes.slice(0, PG_CHANGES_PER_STATEMENT);
1783
1979
  const params = [...head];
1784
1980
  const values = valuesOf(params, firstSlice, 0);
@@ -1787,12 +1983,14 @@ class PostgresTransaction implements StorageTransaction {
1787
1983
  const { rows } = await q.query<{ max_commit_seq: unknown }>(
1788
1984
  `WITH allocated AS (${allocate}),
1789
1985
  allocated_commit AS (${commitRow}),
1986
+ v(idx, tbl, row_id, op, version, scopes, payload) AS (
1987
+ VALUES ${values.join(',')}
1988
+ ),
1790
1989
  inserted AS (
1791
1990
  INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
1792
- SELECT $1, allocated.max_commit_seq, v.idx, v.tbl, v.row_id, v.op, v.row_version, v.scopes, v.payload
1793
- FROM allocated
1794
- CROSS JOIN (VALUES ${values.join(',')}) AS v(idx, tbl, row_id, op, row_version, scopes, payload)
1795
- RETURNING partition, tbl, row_id, op, commit_seq, scopes
1991
+ SELECT $1, allocated.max_commit_seq, v.idx, v.tbl, v.row_id, v.op, v.version, v.scopes, v.payload
1992
+ FROM allocated CROSS JOIN v
1993
+ RETURNING partition, idx, tbl, row_id, op, commit_seq, scopes
1796
1994
  ),
1797
1995
  ${scopesCte},
1798
1996
  tombstoned AS (${tombstones(movedParam)})
@@ -1814,11 +2012,14 @@ class PostgresTransaction implements StorageTransaction {
1814
2012
  chunkParams.push(moved);
1815
2013
  const chunkMovedParam = `$${chunkParams.length}`;
1816
2014
  await q.query(
1817
- `WITH inserted AS (
2015
+ `WITH v(idx, tbl, row_id, op, version, scopes, payload) AS (
2016
+ VALUES ${chunkValues.join(',')}
2017
+ ),
2018
+ inserted AS (
1818
2019
  INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
1819
- SELECT $1, $2, v.idx, v.tbl, v.row_id, v.op, v.row_version, v.scopes, v.payload
1820
- FROM (VALUES ${chunkValues.join(',')}) AS v(idx, tbl, row_id, op, row_version, scopes, payload)
1821
- RETURNING partition, tbl, row_id, op, commit_seq, scopes
2020
+ SELECT $1, $2, v.idx, v.tbl, v.row_id, v.op, v.version, v.scopes, v.payload
2021
+ FROM v
2022
+ RETURNING partition, idx, tbl, row_id, op, commit_seq, scopes
1822
2023
  ),
1823
2024
  ${scopesCte},
1824
2025
  tombstoned AS (${tombstones(chunkMovedParam)})
@@ -1833,17 +2034,20 @@ class PostgresTransaction implements StorageTransaction {
1833
2034
  clientId: string,
1834
2035
  clientCommitId: string,
1835
2036
  result: StoredPushResult,
2037
+ sequence?: OutboxSequence,
1836
2038
  ): Promise<void> {
1837
2039
  this.#assertOpen();
1838
2040
  await this.#client.query(
1839
- `INSERT INTO sync_push_results(partition, client_id, client_commit_id, result)
1840
- VALUES ($1,$2,$3,$4)
2041
+ `INSERT INTO sync_push_results(partition, client_id, client_commit_id, result, outbox_id, client_seq)
2042
+ VALUES ($1,$2,$3,$4,$5,$6)
1841
2043
  ON CONFLICT (partition, client_id, client_commit_id) DO NOTHING`,
1842
2044
  [
1843
2045
  this.#partition,
1844
2046
  clientId,
1845
2047
  clientCommitId,
1846
2048
  JSON.stringify(serializePushResult(result)),
2049
+ sequence?.outboxId ?? null,
2050
+ sequence?.clientSeq ?? null,
1847
2051
  ],
1848
2052
  );
1849
2053
  }
@@ -2445,9 +2649,12 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2445
2649
  */
2446
2650
  async begin(partition: string): Promise<StorageTransaction> {
2447
2651
  let resolveReady!: (tx: PostgresTransaction) => void;
2448
- const ready = new Promise<PostgresTransaction>((r) => {
2449
- resolveReady = r;
2652
+ let rejectReady!: (error: unknown) => void;
2653
+ const ready = new Promise<PostgresTransaction>((res, rej) => {
2654
+ resolveReady = res;
2655
+ rejectReady = rej;
2450
2656
  });
2657
+ let opened = false;
2451
2658
  let resolveScope!: () => void;
2452
2659
  let rejectScope!: (error: unknown) => void;
2453
2660
  const scope = new Promise<void>((res, rej) => {
@@ -2465,12 +2672,20 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2465
2672
  resolveScope,
2466
2673
  rejectScope,
2467
2674
  );
2675
+ opened = true;
2468
2676
  resolveReady(tx);
2469
2677
  // Hold the transaction open until commit()/rollback() settles `scope`.
2470
2678
  await scope;
2471
2679
  })
2472
2680
  .catch((error: unknown) => {
2473
2681
  if (error instanceof RollbackSignal) return;
2682
+ // The executor failed before the callback ran (no connection, BEGIN
2683
+ // refused): `begin()` itself rejects, and no transaction exists to
2684
+ // observe `done`.
2685
+ if (!opened) {
2686
+ rejectReady(error);
2687
+ return;
2688
+ }
2474
2689
  throw error;
2475
2690
  });
2476
2691
  const tx = await ready;
@@ -2576,15 +2791,23 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2576
2791
  [partition, horizonSeq],
2577
2792
  );
2578
2793
  const removed = await client.query(
2579
- 'DELETE FROM sync_commits WHERE partition=$1 AND commit_seq<=$2',
2794
+ 'DELETE FROM sync_commits WHERE partition=$1 AND commit_seq<=$2 RETURNING commit_seq',
2580
2795
  [partition, horizonSeq],
2581
2796
  );
2797
+ // Scope entries go by the keys of the changes being pruned, before
2798
+ // those changes are deleted: a `commit_seq` predicate alone would scan
2799
+ // the partition's whole scope index (`commit_seq` is its last key column).
2582
2800
  await client.query(
2583
- 'DELETE FROM sync_changes WHERE partition=$1 AND commit_seq<=$2',
2801
+ `DELETE FROM sync_change_scopes s USING (
2802
+ SELECT DISTINCT c.tbl, e.key, e.value, c.commit_seq
2803
+ FROM sync_changes c CROSS JOIN LATERAL jsonb_each_text(c.scopes) e
2804
+ WHERE c.partition=$1 AND c.commit_seq<=$2) k
2805
+ WHERE s.partition=$1 AND s.tbl=k.tbl AND s.var=k.key
2806
+ AND s.value=k.value AND s.commit_seq=k.commit_seq`,
2584
2807
  [partition, horizonSeq],
2585
2808
  );
2586
2809
  await client.query(
2587
- 'DELETE FROM sync_change_scopes WHERE partition=$1 AND commit_seq<=$2',
2810
+ 'DELETE FROM sync_changes WHERE partition=$1 AND commit_seq<=$2',
2588
2811
  [partition, horizonSeq],
2589
2812
  );
2590
2813
  // §4.6: tombstones prune in the same pass as the commit log.
@@ -2595,7 +2818,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2595
2818
  return {
2596
2819
  previousHorizonSeq,
2597
2820
  horizonSeq,
2598
- removedCommits: removed.rowCount,
2821
+ removedCommits: removed.rows.length,
2599
2822
  };
2600
2823
  });
2601
2824
  }
@@ -2856,10 +3079,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2856
3079
  SET status='completed', completed_at_ms=$4,
2857
3080
  lease_owner=NULL, lease_expires_at_ms=NULL
2858
3081
  WHERE partition=$1 AND idempotency_key=$2
2859
- AND status='leased' AND lease_owner=$3`,
3082
+ AND status='leased' AND lease_owner=$3
3083
+ RETURNING idempotency_key`,
2860
3084
  [partition, idempotencyKey, leaseOwner, completedAtMs],
2861
3085
  );
2862
- return result.rowCount === 1;
3086
+ return result.rows.length === 1;
2863
3087
  }
2864
3088
 
2865
3089
  async extendReactionLease(
@@ -2871,10 +3095,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2871
3095
  const result = await this.#exec.query(
2872
3096
  `UPDATE sync_reactions SET lease_expires_at_ms=$4
2873
3097
  WHERE partition=$1 AND idempotency_key=$2
2874
- AND status='leased' AND lease_owner=$3`,
3098
+ AND status='leased' AND lease_owner=$3
3099
+ RETURNING idempotency_key`,
2875
3100
  [partition, idempotencyKey, leaseOwner, leaseExpiresAtMs],
2876
3101
  );
2877
- return result.rowCount === 1;
3102
+ return result.rows.length === 1;
2878
3103
  }
2879
3104
 
2880
3105
  async failReaction(
@@ -2887,7 +3112,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2887
3112
  SET status=$4, available_at_ms=$5, last_failure=$6,
2888
3113
  lease_owner=NULL, lease_expires_at_ms=NULL
2889
3114
  WHERE partition=$1 AND idempotency_key=$2
2890
- AND status='leased' AND lease_owner=$3`,
3115
+ AND status='leased' AND lease_owner=$3
3116
+ RETURNING idempotency_key`,
2891
3117
  [
2892
3118
  partition,
2893
3119
  idempotencyKey,
@@ -2897,7 +3123,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2897
3123
  JSON.stringify(update.failure),
2898
3124
  ],
2899
3125
  );
2900
- return result.rowCount === 1;
3126
+ return result.rows.length === 1;
2901
3127
  }
2902
3128
 
2903
3129
  async retryReaction(
@@ -2910,10 +3136,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
2910
3136
  SET status='pending', attempts=0, available_at_ms=$3,
2911
3137
  last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
2912
3138
  completed_at_ms=NULL
2913
- WHERE partition=$1 AND idempotency_key=$2 AND status='dead-letter'`,
3139
+ WHERE partition=$1 AND idempotency_key=$2 AND status='dead-letter'
3140
+ RETURNING idempotency_key`,
2914
3141
  [partition, idempotencyKey, nowMs],
2915
3142
  );
2916
- return result.rowCount === 1;
3143
+ return result.rows.length === 1;
2917
3144
  }
2918
3145
 
2919
3146
  async getReaction(
@@ -3002,107 +3229,76 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3002
3229
 
3003
3230
  async latestScopedChangeSeq(
3004
3231
  partition: string,
3005
- query: { readonly table: string; readonly scopeFilter: ScopeMap },
3232
+ query: { readonly table: string; readonly scopes: UnitScopes },
3006
3233
  ): Promise<number> {
3007
- const firstVariable = Object.keys(query.scopeFilter).sort()[0];
3008
- const values =
3009
- firstVariable === undefined
3010
- ? []
3011
- : (query.scopeFilter[firstVariable] ?? []);
3012
- if (firstVariable === undefined || values.length === 0) return 0;
3013
- // Concurrent reads of a pull share one statement across tables.
3234
+ const variable = Object.keys(query.scopes).sort()[0];
3235
+ const value = variable === undefined ? undefined : query.scopes[variable];
3236
+ if (variable === undefined || value === undefined) return 0;
3237
+ // Concurrent reads of a pull share one statement across tables: one
3238
+ // index-only max over the (partition, tbl, var, value) prefix per spec.
3014
3239
  const [row] = await this.#batchedPage<{ seq: unknown }>(
3015
3240
  'latestScopedChange',
3016
- LATEST_SCOPED_CHANGE_BATCH_SQL,
3241
+ `SELECT s.i AS sub,
3242
+ (SELECT max(commit_seq) FROM sync_change_scopes
3243
+ WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=s.value) AS seq
3244
+ FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, value text)
3245
+ ORDER BY s.i`,
3017
3246
  partition,
3018
- { tbl: query.table, var: firstVariable, vals: values },
3247
+ { tbl: query.table, var: variable, value },
3019
3248
  );
3020
- return row === undefined ? 0 : asNumber(row.seq);
3249
+ return row === undefined || row.seq === null ? 0 : asNumber(row.seq);
3021
3250
  }
3022
3251
 
3023
- async readCommitWindow(
3252
+ readLiveWindow(
3024
3253
  partition: string,
3025
- query: CommitWindowQuery,
3026
- ): Promise<StoredCommit[]> {
3027
- const variables = Object.keys(query.scopeFilter).sort();
3028
- const firstVariable = variables[0];
3029
- if (firstVariable === undefined) return [];
3030
- const firstValues = query.scopeFilter[firstVariable] ?? [];
3031
- if (firstValues.length === 0) return [];
3032
- // Candidates via the inverted index (one variable): the (partition, tbl,
3033
- // var, value, commit_seq) PK makes the candidate subquery an index range
3034
- // scan returning commit_seq already ascending (see postgres-explain
3035
- // .test.ts), LEFT JOINed to the commit meta + the table's changes. Pages
3036
- // of concurrent window reads share one statement across tables (see
3037
- // `COMMIT_WINDOW_BATCH_SQL`). Exact multi-variable verification against
3038
- // the stored scope map happens below.
3039
- const commits: StoredCommit[] = [];
3040
- let deliveredChanges = 0;
3041
- let afterSeq = query.afterSeq;
3042
- const batchSize = Math.max(64, query.limitChanges);
3043
- while (deliveredChanges < query.limitChanges) {
3044
- const records = await this.#batchedPage<CommitWindowRecord>(
3045
- 'commitWindow',
3046
- COMMIT_WINDOW_BATCH_SQL,
3047
- partition,
3048
- {
3049
- tbl: query.table,
3050
- var: firstVariable,
3051
- vals: firstValues,
3052
- after: afterSeq,
3053
- through: query.throughSeq,
3054
- lim: batchSize,
3055
- },
3254
+ query: LiveWindowQuery,
3255
+ ): Promise<LiveWindow> {
3256
+ // One statement per page: one LATERAL range of
3257
+ // `sync_change_scopes_by_key` per unit key, each DISTINCT and LIMITed at
3258
+ // the index, merged in commit order and LIMITed again, then LEFT JOINed
3259
+ // to the commit meta and every change of the commit. A candidate whose
3260
+ // commit vanished comes back with NULL meta and still advances the scan.
3261
+ return readLiveWindowPages(query, async (keys, limit) => {
3262
+ const { rows } = await this.#exec.query<{
3263
+ commit_seq: unknown;
3264
+ actor_id: string | null;
3265
+ created_at_ms: unknown;
3266
+ tbl: string | null;
3267
+ row_id: string;
3268
+ op: unknown;
3269
+ row_version: unknown;
3270
+ scopes: unknown;
3271
+ payload: unknown;
3272
+ }>(
3273
+ `SELECT c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,
3274
+ ch.tbl AS tbl, ch.row_id AS row_id, ch.op AS op, ch.row_version AS row_version, ch.scopes AS scopes, ch.payload AS payload
3275
+ FROM (SELECT DISTINCT s.commit_seq
3276
+ FROM jsonb_to_recordset($2::text::jsonb) AS k(var text, value text, after bigint)
3277
+ CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes
3278
+ WHERE partition=$1 AND var=k.var AND value=k.value
3279
+ AND commit_seq>k.after AND commit_seq<=$3
3280
+ ORDER BY commit_seq LIMIT $4) s
3281
+ ORDER BY s.commit_seq LIMIT $4) c
3282
+ LEFT JOIN sync_commits m ON m.partition=$1 AND m.commit_seq=c.commit_seq
3283
+ LEFT JOIN sync_changes ch ON ch.partition=$1 AND ch.commit_seq=c.commit_seq
3284
+ ORDER BY c.commit_seq, ch.idx`,
3285
+ [partition, JSON.stringify(keys), query.throughSeq, limit],
3056
3286
  );
3057
- if (records.length === 0) break;
3058
- // Fold the page: rows arrive ordered (commit_seq, idx); consecutive
3059
- // rows with the same commit_seq are one candidate. Every candidate
3060
- // advances the cursor — including vanished commits (NULL meta, LEFT
3061
- // JOIN contract) and commits whose changes all fail the exact
3062
- // multi-variable match.
3063
- let candidateCount = 0;
3064
- let i = 0;
3065
- while (i < records.length) {
3066
- const head = records[i];
3067
- if (head === undefined) break;
3068
- const commitSeq = asNumber(head.commit_seq);
3069
- candidateCount += 1;
3070
- afterSeq = commitSeq;
3071
- const changes: StoredChange[] = [];
3072
- for (; i < records.length; i++) {
3073
- const record = records[i];
3074
- if (record === undefined || asNumber(record.commit_seq) !== commitSeq)
3075
- break;
3076
- // NULL tbl: a candidate with no change rows for the table.
3077
- if (record.tbl === null || record.row_id === null) continue;
3078
- const change = toStoredChange({
3079
- tbl: record.tbl,
3080
- row_id: record.row_id,
3081
- op: record.op,
3082
- row_version: record.row_version,
3083
- scopes: record.scopes,
3084
- payload: record.payload,
3085
- });
3086
- if (matchesEffective(change.scopes, query.scopeFilter)) {
3087
- changes.push(change);
3088
- }
3089
- }
3090
- // NULL meta: the commit vanished — cursor advanced, nothing emitted.
3091
- if (head.actor_id === null) continue;
3092
- if (changes.length === 0) continue;
3093
- commits.push({
3094
- commitSeq,
3095
- createdAtMs: asNumber(head.created_at_ms),
3096
- actorId: head.actor_id,
3097
- changes,
3098
- });
3099
- deliveredChanges += changes.length;
3100
- if (deliveredChanges >= query.limitChanges) break;
3101
- }
3102
- if (deliveredChanges >= query.limitChanges) break;
3103
- if (candidateCount < batchSize) break;
3104
- }
3105
- return commits;
3287
+ return rows.map((record) => ({
3288
+ commitSeq: asNumber(record.commit_seq),
3289
+ ...(record.actor_id === null
3290
+ ? {}
3291
+ : {
3292
+ meta: {
3293
+ actorId: record.actor_id,
3294
+ createdAtMs: asNumber(record.created_at_ms),
3295
+ },
3296
+ }),
3297
+ ...(record.tbl === null
3298
+ ? {}
3299
+ : { change: toStoredChange({ ...record, tbl: record.tbl }) }),
3300
+ }));
3301
+ });
3106
3302
  }
3107
3303
 
3108
3304
  async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
@@ -3167,37 +3363,13 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3167
3363
  partition: string,
3168
3364
  clientId: string,
3169
3365
  ): Promise<ClientRecord | undefined> {
3170
- const { rows } = await this.#exec.query<{
3171
- client_id: string;
3172
- actor_id: string;
3173
- wire_version: unknown;
3174
- cursor: unknown;
3175
- subscriptions: unknown;
3176
- updated_at_ms: unknown;
3177
- last_round_at_ms: unknown;
3178
- last_error_code: string | null;
3179
- consecutive_failures: unknown;
3180
- }>(
3181
- '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=$1 AND client_id=$2',
3366
+ const { rows } = await this.#exec.query<
3367
+ Parameters<typeof toClientRecord>[0]
3368
+ >(
3369
+ `SELECT ${CLIENT_RECORD_COLUMNS} FROM sync_clients WHERE partition=$1 AND client_id=$2`,
3182
3370
  [partition, clientId],
3183
3371
  );
3184
- const record = rows[0];
3185
- if (record === undefined) return undefined;
3186
- return {
3187
- clientId: record.client_id,
3188
- actorId: record.actor_id,
3189
- wireVersion: asNumber(record.wire_version),
3190
- cursor: asNumber(record.cursor),
3191
- updatedAtMs: asNumber(record.updated_at_ms),
3192
- subscriptions: asJson<ClientSubscription[]>(record.subscriptions),
3193
- ...clientRoundState(
3194
- record.last_round_at_ms === null
3195
- ? null
3196
- : asNumber(record.last_round_at_ms),
3197
- record.last_error_code,
3198
- asNumber(record.consecutive_failures),
3199
- ),
3200
- };
3372
+ return rows[0] === undefined ? undefined : toClientRecord(rows[0]);
3201
3373
  }
3202
3374
 
3203
3375
  async putClientRecord(
@@ -3205,15 +3377,23 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3205
3377
  record: ClientRecord,
3206
3378
  options?: ClientRecordWriteOptions,
3207
3379
  ): Promise<void> {
3380
+ // Every non-key field comes from the new record, except the registration
3381
+ // list and digest, which only a traveling list replaces (§4.5).
3382
+ const registration = record.registration;
3208
3383
  await this.#exec.query(
3209
- `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms, last_round_at_ms)
3210
- VALUES ($1,$2,$3,$4,$5,$6,$7,$7)
3384
+ `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, updated_at_ms, last_round_at_ms, schema_version, units, registration_digest, catching_up)
3385
+ VALUES ($1,$2,$3,$4,$5,$6,$11,$7,$8::text::jsonb,$9,$10::text::jsonb)
3211
3386
  ON CONFLICT (partition, client_id) DO UPDATE
3212
3387
  SET actor_id=EXCLUDED.actor_id, wire_version=EXCLUDED.wire_version,
3213
3388
  cursor=EXCLUDED.cursor,
3214
- subscriptions=EXCLUDED.subscriptions,
3215
3389
  updated_at_ms=EXCLUDED.updated_at_ms,
3216
- last_round_at_ms=EXCLUDED.last_round_at_ms${
3390
+ last_round_at_ms=EXCLUDED.last_round_at_ms,
3391
+ schema_version=EXCLUDED.schema_version,${
3392
+ registration === undefined
3393
+ ? ''
3394
+ : '\n units=EXCLUDED.units, registration_digest=EXCLUDED.registration_digest,'
3395
+ }
3396
+ catching_up=EXCLUDED.catching_up${
3217
3397
  options?.keepRoundOutcome === true
3218
3398
  ? ''
3219
3399
  : ',\n last_error_code=NULL, consecutive_failures=0'
@@ -3224,8 +3404,12 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3224
3404
  record.actorId,
3225
3405
  record.wireVersion,
3226
3406
  record.cursor,
3227
- JSON.stringify(record.subscriptions),
3228
3407
  record.updatedAtMs,
3408
+ record.schemaVersion ?? null,
3409
+ registration === undefined ? null : JSON.stringify(registration.units),
3410
+ registration?.digest ?? null,
3411
+ JSON.stringify(record.catchingUp),
3412
+ record.lastRoundAtMs ?? record.updatedAtMs,
3229
3413
  ],
3230
3414
  );
3231
3415
  }
@@ -3254,9 +3438,15 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3254
3438
  cursor: number,
3255
3439
  updatedAtMs: number,
3256
3440
  ): Promise<void> {
3441
+ // §8.2: the ack never raises the record cursor above a catching-up
3442
+ // unit's cursor, so pruning keeps that unit's history (§4.6).
3257
3443
  await this.#exec.query(
3258
3444
  `UPDATE sync_clients
3259
- SET cursor=GREATEST(cursor, $1), updated_at_ms=GREATEST(updated_at_ms, $2)
3445
+ SET cursor=GREATEST(cursor, LEAST($1::bigint, COALESCE((
3446
+ SELECT min((u->>'cursor')::bigint)
3447
+ FROM jsonb_array_elements(sync_clients.catching_up) AS u
3448
+ WHERE (u->>'cursor')::bigint>=0), $1::bigint))),
3449
+ updated_at_ms=GREATEST(updated_at_ms, $2)
3260
3450
  WHERE partition=$3 AND client_id=$4 AND actor_id=$5
3261
3451
  AND EXISTS (SELECT 1 FROM sync_partition_registry
3262
3452
  WHERE partition=sync_clients.partition AND log_epoch=$6)`,
@@ -3264,26 +3454,12 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3264
3454
  );
3265
3455
  }
3266
3456
 
3267
- async updateClientCursor(
3268
- partition: string,
3269
- clientId: string,
3270
- cursor: number,
3271
- updatedAtMs: number,
3272
- ): Promise<void> {
3273
- await this.#exec.query(
3274
- `UPDATE sync_clients
3275
- SET cursor=GREATEST(cursor, $3), updated_at_ms=GREATEST(updated_at_ms, $4)
3276
- WHERE partition=$1 AND client_id=$2`,
3277
- [partition, clientId, cursor, updatedAtMs],
3278
- );
3279
- }
3280
-
3281
3457
  async getActiveClientCursorFloor(
3282
3458
  partition: string,
3283
3459
  cutoffMs: number,
3284
3460
  ): Promise<number | null> {
3285
3461
  const { rows } = await this.#exec.query<{ cursor: unknown }>(
3286
- 'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=$1 AND updated_at_ms>=$2',
3462
+ 'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=$1 AND updated_at_ms>=$2 AND cursor>=0',
3287
3463
  [partition, cutoffMs],
3288
3464
  );
3289
3465
  return rows[0]!.cursor === null ? null : asNumber(rows[0]!.cursor);
@@ -3315,36 +3491,29 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3315
3491
  readonly scopes: Record<string, string>;
3316
3492
  }[]
3317
3493
  > {
3318
- // Candidate rows via the by-blob index (§5.9.4/§5.9.5); each row's
3319
- // stored scopes come from sync_rows for the §3.4 authorization test.
3320
- const { rows: refs } = await this.#exec.query<{
3494
+ // One statement: the by-blob index (§5.9.4/§5.9.5) supplies the candidate
3495
+ // rows and each row's stored scopes come from its row table for the §3.4
3496
+ // authorization test (see `rowsReferencingBlobSql`).
3497
+ if (this.#tables === undefined || this.#tables.size === 0) return [];
3498
+ const { rows } = await this.#exec.query<{
3321
3499
  tbl: string;
3322
3500
  row_id: string;
3323
- }>(
3324
- 'SELECT tbl, row_id FROM sync_blob_refs WHERE partition=$1 AND blob_id=$2',
3325
- [partition, blobId],
3326
- );
3327
- const out: {
3328
- table: string;
3329
- rowId: string;
3330
- scopes: Record<string, string>;
3331
- }[] = [];
3332
- for (const ref of refs) {
3333
- const compiled = this.#tables?.get(ref.tbl);
3334
- if (compiled === undefined) continue; // table no longer in the schema
3335
- const { rows } = await this.#exec.query<{ scopes: unknown }>(
3336
- selectRowScopesSql(compiled, 'postgres'),
3337
- [partition, ref.row_id],
3338
- );
3339
- const row = rows[0];
3340
- if (row === undefined) continue;
3341
- out.push({
3342
- table: ref.tbl,
3343
- rowId: ref.row_id,
3344
- scopes: asJson<Record<string, string>>(row.scopes),
3345
- });
3346
- }
3347
- return out;
3501
+ scopes: unknown;
3502
+ }>(rowsReferencingBlobSql(this.#tables.values(), 'postgres'), [
3503
+ partition,
3504
+ blobId,
3505
+ ]);
3506
+ return rows.flatMap((row) =>
3507
+ row.scopes === null
3508
+ ? []
3509
+ : [
3510
+ {
3511
+ table: row.tbl,
3512
+ rowId: row.row_id,
3513
+ scopes: asJson<Record<string, string>>(row.scopes),
3514
+ },
3515
+ ],
3516
+ );
3348
3517
  }
3349
3518
 
3350
3519
  async listReferencedBlobIds(partition: string): Promise<string[]> {
@@ -3392,7 +3561,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3392
3561
  WHERE s.partition=$1 AND s.tbl=$2 AND s.var=$3 AND s.value=$4
3393
3562
  AND s.commit_seq<=$5 AND c2.op=1 AND c2.scopes->>$3=s.value
3394
3563
  LIMIT $6) d
3395
- WHERE c.partition=$1 AND c.commit_seq=d.commit_seq AND c.idx=d.idx`,
3564
+ WHERE c.partition=$1 AND c.commit_seq=d.commit_seq AND c.idx=d.idx
3565
+ RETURNING c.commit_seq`,
3396
3566
  params,
3397
3567
  );
3398
3568
  const scopes = await client.query(
@@ -3405,45 +3575,42 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3405
3575
  AND c.tbl=s.tbl AND c.scopes->>$3=s.value)
3406
3576
  LIMIT $6) d
3407
3577
  WHERE cs.partition=$1 AND cs.tbl=$2 AND cs.var=$3 AND cs.value=$4
3408
- AND cs.commit_seq=d.commit_seq`,
3578
+ AND cs.commit_seq=d.commit_seq
3579
+ RETURNING cs.commit_seq`,
3409
3580
  params,
3410
3581
  );
3411
- return changes.rowCount + scopes.rowCount;
3582
+ // §4.6.1: stored conflict results of the binding lose their row payload.
3583
+ const results = await client.query(
3584
+ `UPDATE sync_push_results p SET result=jsonb_set(p.result, '{results}', (
3585
+ SELECT jsonb_agg(e - 'serverRow' ORDER BY i)
3586
+ FROM jsonb_array_elements(p.result->'results')
3587
+ WITH ORDINALITY AS t(e, i)))
3588
+ FROM (
3589
+ SELECT client_id, client_commit_id FROM sync_push_results
3590
+ WHERE partition=$1
3591
+ AND result->'conflictAuthorization'->>'table'=$2
3592
+ AND result->'conflictAuthorization'->'scopes'->>$3=$4
3593
+ AND jsonb_path_exists(result, '$.results[*].serverRow')
3594
+ LIMIT $5) d
3595
+ WHERE p.partition=$1 AND p.client_id=d.client_id
3596
+ AND p.client_commit_id=d.client_commit_id
3597
+ RETURNING p.client_id`,
3598
+ [partition, query.table, query.variable, query.value, query.limit],
3599
+ );
3600
+ return changes.rows.length + scopes.rows.length + results.rows.length;
3412
3601
  });
3413
3602
  }
3414
3603
 
3415
3604
  // -- admin/console read surface --------------------------------------------
3416
3605
 
3417
3606
  async listClientRecords(partition: string): Promise<ClientRecord[]> {
3418
- const { rows } = await this.#exec.query<{
3419
- client_id: string;
3420
- actor_id: string;
3421
- wire_version: unknown;
3422
- cursor: unknown;
3423
- subscriptions: unknown;
3424
- updated_at_ms: unknown;
3425
- last_round_at_ms: unknown;
3426
- last_error_code: string | null;
3427
- consecutive_failures: unknown;
3428
- }>(
3429
- '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=$1 ORDER BY updated_at_ms DESC',
3607
+ const { rows } = await this.#exec.query<
3608
+ Parameters<typeof toClientRecord>[0]
3609
+ >(
3610
+ `SELECT ${CLIENT_RECORD_COLUMNS} FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC`,
3430
3611
  [partition],
3431
3612
  );
3432
- return rows.map((r) => ({
3433
- clientId: r.client_id,
3434
- actorId: r.actor_id,
3435
- wireVersion: asNumber(r.wire_version),
3436
- cursor: asNumber(r.cursor),
3437
- updatedAtMs: asNumber(r.updated_at_ms),
3438
- subscriptions: (typeof r.subscriptions === 'string'
3439
- ? JSON.parse(r.subscriptions)
3440
- : r.subscriptions) as ClientSubscription[],
3441
- ...clientRoundState(
3442
- r.last_round_at_ms === null ? null : asNumber(r.last_round_at_ms),
3443
- r.last_error_code,
3444
- asNumber(r.consecutive_failures),
3445
- ),
3446
- }));
3613
+ return rows.map(toClientRecord);
3447
3614
  }
3448
3615
 
3449
3616
  async listCommitMetadata(
@@ -3484,53 +3651,72 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3484
3651
  ORDER BY commit_seq DESC LIMIT $4`,
3485
3652
  [partition, query.afterSeq, beforeSeq, query.limit],
3486
3653
  );
3487
- // `changeSample`: one extra statement for the whole page — the first
3488
- // `sample` changes (change-index order) of every listed commit.
3654
+ // One grouped statement for the page's per-table change counts and, with
3655
+ // `changeSample`, one for the first `sample` changes (change-index order)
3656
+ // of every listed commit.
3489
3657
  const sampleCount =
3490
3658
  query.changeSample !== undefined &&
3491
3659
  Number.isInteger(query.changeSample) &&
3492
3660
  query.changeSample > 0
3493
3661
  ? query.changeSample
3494
3662
  : 0;
3663
+ const seqs = rows.map((row) => asNumber(row.commit_seq));
3664
+ const counts = new Map<number, { tbl: string; n: unknown }[]>();
3665
+ for (const count of seqs.length === 0
3666
+ ? []
3667
+ : (
3668
+ await this.#exec.query<{
3669
+ commit_seq: unknown;
3670
+ tbl: string;
3671
+ n: unknown;
3672
+ }>(
3673
+ `SELECT commit_seq, tbl, count(*) AS n FROM sync_changes
3674
+ WHERE partition=$1 AND commit_seq=ANY($2::bigint[])
3675
+ GROUP BY commit_seq, tbl ORDER BY commit_seq, tbl`,
3676
+ [partition, seqs],
3677
+ )
3678
+ ).rows) {
3679
+ const seq = asNumber(count.commit_seq);
3680
+ counts.set(seq, [...(counts.get(seq) ?? []), count]);
3681
+ }
3495
3682
  const samples = new Map<number, CommitChangeSummary[]>();
3496
- if (sampleCount > 0 && rows.length > 0) {
3497
- const seqs = rows.map((row) => asNumber(row.commit_seq));
3498
- const { rows: changeRows } = await this.#exec.query<{
3499
- commit_seq: unknown;
3500
- tbl: string;
3501
- row_id: string;
3502
- op: unknown;
3503
- }>(
3504
- `SELECT commit_seq, tbl, row_id, op FROM sync_changes
3505
- WHERE partition=$1 AND commit_seq IN (${seqs.map((_, index) => `$${index + 2}`).join(',')}) AND idx<$${seqs.length + 2}
3506
- ORDER BY commit_seq, idx`,
3507
- [partition, ...seqs, sampleCount],
3508
- );
3509
- for (const change of changeRows) {
3510
- const sample = samples.get(asNumber(change.commit_seq)) ?? [];
3511
- sample.push({
3683
+ for (const change of sampleCount === 0 || seqs.length === 0
3684
+ ? []
3685
+ : (
3686
+ await this.#exec.query<{
3687
+ commit_seq: unknown;
3688
+ tbl: string;
3689
+ row_id: string;
3690
+ op: unknown;
3691
+ }>(
3692
+ `SELECT commit_seq, tbl, row_id, op FROM sync_changes
3693
+ WHERE partition=$1 AND commit_seq=ANY($2::bigint[]) AND idx<$3
3694
+ ORDER BY commit_seq, idx`,
3695
+ [partition, seqs, sampleCount],
3696
+ )
3697
+ ).rows) {
3698
+ const seq = asNumber(change.commit_seq);
3699
+ samples.set(seq, [
3700
+ ...(samples.get(seq) ?? []),
3701
+ {
3512
3702
  table: change.tbl,
3513
3703
  rowId: change.row_id,
3514
3704
  op: asNumber(change.op) === 1 ? 'upsert' : 'delete',
3515
- });
3516
- samples.set(asNumber(change.commit_seq), sample);
3517
- }
3705
+ },
3706
+ ]);
3518
3707
  }
3519
3708
  const out: CommitMetadata[] = [];
3520
3709
  for (const row of rows) {
3521
3710
  const commitSeq = asNumber(row.commit_seq);
3522
- const changes = await this.#exec.query<{ tbl: string; n: unknown }>(
3523
- 'SELECT tbl, count(*) AS n FROM sync_changes WHERE partition=$1 AND commit_seq=$2 GROUP BY tbl',
3524
- [partition, commitSeq],
3525
- );
3711
+ const changes = counts.get(commitSeq) ?? [];
3526
3712
  out.push({
3527
3713
  commitSeq,
3528
3714
  clientId: row.client_id,
3529
3715
  clientCommitId: row.client_commit_id,
3530
3716
  actorId: row.actor_id,
3531
3717
  createdAtMs: asNumber(row.created_at_ms),
3532
- changeCount: changes.rows.reduce((sum, c) => sum + asNumber(c.n), 0),
3533
- tables: changes.rows.map((c) => c.tbl),
3718
+ changeCount: changes.reduce((sum, c) => sum + asNumber(c.n), 0),
3719
+ tables: changes.map((c) => c.tbl),
3534
3720
  ...(sampleCount > 0 ? { sample: samples.get(commitSeq) ?? [] } : {}),
3535
3721
  });
3536
3722
  }
@@ -3652,45 +3838,62 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
3652
3838
  });
3653
3839
  }
3654
3840
 
3841
+ async listPushWatermarks(
3842
+ partition: string,
3843
+ clientCommitId: string,
3844
+ ): Promise<PushWatermark[]> {
3845
+ // The clients come from the retained commit log, which has no index on
3846
+ // `client_commit_id`; the read is bounded by retention (§4.6).
3847
+ const { rows } = await this.#exec.query<{
3848
+ client_id: string;
3849
+ outbox_id: string;
3850
+ through_seq: unknown;
3851
+ }>(
3852
+ `SELECT client_id, outbox_id, through_seq FROM sync_push_watermarks
3853
+ WHERE partition=$1 AND client_id IN (
3854
+ SELECT client_id FROM sync_commits WHERE partition=$1 AND client_commit_id=$2)
3855
+ ORDER BY client_id, outbox_id`,
3856
+ [partition, clientCommitId],
3857
+ );
3858
+ return rows.map((row) => ({
3859
+ clientId: row.client_id,
3860
+ outboxId: row.outbox_id,
3861
+ throughSeq: asNumber(row.through_seq),
3862
+ }));
3863
+ }
3864
+
3655
3865
  async scopeActivity(
3656
3866
  partition: string,
3657
3867
  query: ScopeActivityQuery,
3658
3868
  ): Promise<ScopeCommitActivity[]> {
3869
+ // One statement for the page: candidate (commit, table) pairs from the
3870
+ // `sync_change_scopes_by_key` range of the key, newest first, joined to
3871
+ // the commit metadata with the table's change count. A candidate whose
3872
+ // commit was pruned has no metadata and is skipped.
3659
3873
  const { rows } = await this.#exec.query<{
3660
3874
  commit_seq: unknown;
3661
3875
  tbl: string;
3876
+ actor_id: string;
3877
+ created_at_ms: unknown;
3878
+ n: unknown;
3662
3879
  }>(
3663
- `SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
3664
- WHERE partition=$1 AND var=$2 AND value=$3
3665
- ORDER BY commit_seq DESC LIMIT $4`,
3880
+ `SELECT s.commit_seq, s.tbl, m.actor_id, m.created_at_ms,
3881
+ (SELECT count(*) FROM sync_changes ch
3882
+ WHERE ch.partition=$1 AND ch.commit_seq=s.commit_seq AND ch.tbl=s.tbl) AS n
3883
+ FROM (SELECT DISTINCT commit_seq, tbl FROM sync_change_scopes
3884
+ WHERE partition=$1 AND var=$2 AND value=$3
3885
+ ORDER BY commit_seq DESC LIMIT $4) s
3886
+ JOIN sync_commits m ON m.partition=$1 AND m.commit_seq=s.commit_seq
3887
+ ORDER BY s.commit_seq DESC`,
3666
3888
  [partition, query.variable, query.value, query.limit],
3667
3889
  );
3668
- const out: ScopeCommitActivity[] = [];
3669
- for (const row of rows) {
3670
- const commitSeq = asNumber(row.commit_seq);
3671
- const meta = await this.#exec.query<{
3672
- actor_id: string;
3673
- created_at_ms: unknown;
3674
- }>(
3675
- 'SELECT actor_id, created_at_ms FROM sync_commits WHERE partition=$1 AND commit_seq=$2',
3676
- [partition, commitSeq],
3677
- );
3678
- const metaRow = meta.rows[0];
3679
- if (metaRow === undefined) continue;
3680
- const count = await this.#exec.query<{ n: unknown }>(
3681
- 'SELECT count(*) AS n FROM sync_changes WHERE partition=$1 AND commit_seq=$2 AND tbl=$3',
3682
- [partition, commitSeq, row.tbl],
3683
- );
3684
- out.push({
3685
- commitSeq,
3686
- table: row.tbl,
3687
- createdAtMs: asNumber(metaRow.created_at_ms),
3688
- actorId: metaRow.actor_id,
3689
- changeCount:
3690
- count.rows[0] === undefined ? 0 : asNumber(count.rows[0].n),
3691
- });
3692
- }
3693
- return out;
3890
+ return rows.map((row) => ({
3891
+ commitSeq: asNumber(row.commit_seq),
3892
+ table: row.tbl,
3893
+ createdAtMs: asNumber(row.created_at_ms),
3894
+ actorId: row.actor_id,
3895
+ changeCount: asNumber(row.n),
3896
+ }));
3694
3897
  }
3695
3898
 
3696
3899
  async listPartitions(): Promise<string[]> {