@syncular/server 0.59.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 (54) hide show
  1. package/README.md +20 -16
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +42 -40
  4. package/dist/context.d.ts +6 -8
  5. package/dist/context.js +1 -3
  6. package/dist/d1-storage.js +42 -24
  7. package/dist/errors.js +8 -0
  8. package/dist/events.d.ts +35 -17
  9. package/dist/frame-bytes.js +24 -6
  10. package/dist/handler.js +486 -223
  11. package/dist/local-authority.js +7 -9
  12. package/dist/operations.d.ts +5 -2
  13. package/dist/operations.js +20 -29
  14. package/dist/postgres-storage.d.ts +24 -19
  15. package/dist/postgres-storage.js +249 -168
  16. package/dist/pull.d.ts +68 -53
  17. package/dist/pull.js +258 -287
  18. package/dist/push.d.ts +12 -3
  19. package/dist/push.js +95 -32
  20. package/dist/realtime.d.ts +17 -11
  21. package/dist/realtime.js +65 -90
  22. package/dist/relational-rows.d.ts +0 -57
  23. package/dist/relational-rows.js +0 -97
  24. package/dist/seed.js +10 -15
  25. package/dist/segment-download.d.ts +4 -1
  26. package/dist/segment-download.js +4 -2
  27. package/dist/sqlite-dialect.d.ts +36 -59
  28. package/dist/sqlite-dialect.js +255 -159
  29. package/dist/sqlite-storage.js +24 -20
  30. package/dist/storage-query.d.ts +30 -1
  31. package/dist/storage-query.js +68 -0
  32. package/dist/storage.d.ts +156 -54
  33. package/dist/storage.js +15 -0
  34. package/package.json +2 -2
  35. package/src/admin.ts +87 -59
  36. package/src/context.ts +7 -11
  37. package/src/d1-storage.ts +49 -33
  38. package/src/errors.ts +8 -0
  39. package/src/events.ts +36 -17
  40. package/src/frame-bytes.ts +26 -6
  41. package/src/handler.ts +628 -286
  42. package/src/local-authority.ts +10 -11
  43. package/src/operations.ts +44 -42
  44. package/src/postgres-storage.ts +336 -226
  45. package/src/pull.ts +394 -414
  46. package/src/push.ts +116 -21
  47. package/src/realtime.ts +85 -129
  48. package/src/relational-rows.ts +0 -105
  49. package/src/seed.ts +13 -19
  50. package/src/segment-download.ts +8 -3
  51. package/src/sqlite-dialect.ts +363 -204
  52. package/src/sqlite-storage.ts +45 -25
  53. package/src/storage-query.ts +102 -0
  54. package/src/storage.ts +185 -58
@@ -16,7 +16,7 @@ import {
16
16
  StorageConstraintError,
17
17
  StorageQueryError,
18
18
  } from './storage-errors';
19
- import { serveGateRefusal } from './storage';
19
+ import { commitDeleteFloor, serveGateRefusal } from './storage';
20
20
  import { serveNotReadyError } from './readiness';
21
21
  import {
22
22
  assertPhysicalColumns,
@@ -40,11 +40,12 @@ import {
40
40
  } from './relational-rows';
41
41
  import type { CompiledSchema, CompiledTable } from './schema';
42
42
  import {
43
- SQLITE_ADDED_COLUMNS,
44
43
  SQLITE_DDL,
44
+ SQLITE_UPGRADE_PROBE,
45
45
  SqliteFamilyStorage,
46
46
  SqliteFamilyTransaction,
47
47
  type SqliteStatementSpec,
48
+ sqliteUpgradeDdl,
48
49
  } from './sqlite-dialect';
49
50
  import {
50
51
  SqliteAdapterRequiredError,
@@ -58,6 +59,8 @@ import type {
58
59
  CheckpointDeclaration,
59
60
  IndexRowScanQuery,
60
61
  NewCommit,
62
+ OutboxSequence,
63
+ OutboxSettlement,
61
64
  PreparedPushApply,
62
65
  RowScanQuery,
63
66
  ServerStorage,
@@ -162,22 +165,37 @@ class SqliteTransaction
162
165
  readonly table: string;
163
166
  readonly rowIds: readonly string[];
164
167
  }[] = [],
168
+ outbox?: OutboxSettlement,
165
169
  ): Promise<PreparedPushApply> {
166
170
  this.assertOpen();
167
171
  // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
172
+ // The settlement precedes the savepoint, so a rejection keeps it.
173
+ const settled =
174
+ outbox === undefined
175
+ ? undefined
176
+ : await this.settleOutbox(clientId, clientCommitId, outbox);
168
177
  this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
169
178
  this.#pushApplySavepoint = true;
170
- return {
171
- gate: await this.#storage.readServeGate(
172
- this.partition,
173
- runningSchemaVersion,
174
- ),
175
- persisted: await this.#storage.getPushResult(
176
- this.partition,
177
- clientId,
178
- clientCommitId,
179
- ),
180
- };
179
+ const gate = await this.#storage.readServeGate(
180
+ this.partition,
181
+ runningSchemaVersion,
182
+ );
183
+ const [floor] = await this.all<{ delete_floor: number }>(
184
+ 'SELECT delete_floor FROM sync_partitions WHERE partition=?',
185
+ [this.partition],
186
+ );
187
+ const deleteFloor = floor?.delete_floor ?? 0;
188
+ return settled === undefined
189
+ ? {
190
+ gate,
191
+ deleteFloor,
192
+ persisted: await this.#storage.getPushResult(
193
+ this.partition,
194
+ clientId,
195
+ clientCommitId,
196
+ ),
197
+ }
198
+ : { gate, deleteFloor, ...settled };
181
199
  }
182
200
 
183
201
  async lockPartition(): Promise<void> {
@@ -214,6 +232,7 @@ class SqliteTransaction
214
232
  clientId: string,
215
233
  clientCommitId: string,
216
234
  result: StoredPushResult,
235
+ sequence?: OutboxSequence,
217
236
  ): Promise<StoredPushResult> {
218
237
  this.assertOpen();
219
238
  if (!this.#pushApplySavepoint) {
@@ -222,7 +241,7 @@ class SqliteTransaction
222
241
  this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_push_candidate');
223
242
  this.#storage.db.exec('RELEASE SAVEPOINT syncular_push_candidate');
224
243
  this.#pushApplySavepoint = false;
225
- await this.putPushResult(clientId, clientCommitId, result);
244
+ await this.putPushResult(clientId, clientCommitId, result, sequence);
226
245
  await this.commit();
227
246
  // The idempotency re-check found no record under the writer lock, so the
228
247
  // insert above is the canonical outcome.
@@ -255,10 +274,10 @@ class SqliteTransaction
255
274
  [p],
256
275
  );
257
276
  const commitSeq = (row?.max_commit_seq ?? 0) + 1;
258
- this.run('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?', [
259
- commitSeq,
260
- p,
261
- ]);
277
+ this.run(
278
+ 'UPDATE sync_partitions SET max_commit_seq=?, delete_floor=max(delete_floor, ?) WHERE partition=?',
279
+ [commitSeq, commitDeleteFloor(commit.changes), p],
280
+ );
262
281
  this.run(
263
282
  'INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)',
264
283
  [
@@ -347,13 +366,14 @@ export class SqliteServerStorage
347
366
  super();
348
367
  this.db = db;
349
368
  this.db.exec(SQLITE_DDL);
350
- for (const [table, name, definition] of SQLITE_ADDED_COLUMNS) {
351
- const columns = this.db
352
- .query<{ name: string }, []>(`PRAGMA table_info("${table}")`)
353
- .all();
354
- if (!columns.some((column) => column.name === name)) {
355
- this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
356
- }
369
+ for (const statement of sqliteUpgradeDdl(
370
+ this.db
371
+ .query<{ tbl: string; name: string }, SqliteValue[]>(
372
+ SQLITE_UPGRADE_PROBE.sql,
373
+ )
374
+ .all(...SQLITE_UPGRADE_PROBE.params),
375
+ )) {
376
+ this.db.exec(statement);
357
377
  }
358
378
  const commitColumns = this.db
359
379
  .query<{ name: string }, []>('PRAGMA table_info("sync_commits")')
@@ -1,11 +1,16 @@
1
1
  import type { ScopeMap } from '@syncular/core';
2
2
  import type { CompiledTable, IndexSchema } from './schema';
3
+ import { matchesEffective } from './scopes';
3
4
  import type {
4
5
  AuthoritativeQueryRequest,
5
6
  AuthoritativeQueryResult,
6
7
  IndexRowScanQuery,
8
+ LiveWindow,
9
+ LiveWindowQuery,
7
10
  RowScanQuery,
8
11
  StorageTransaction,
12
+ StoredChange,
13
+ StoredCommit,
9
14
  } from './storage';
10
15
  import { StorageQueryError } from './storage-errors';
11
16
 
@@ -73,3 +78,100 @@ export async function transactionQuery(
73
78
  }
74
79
  return tx.queryAuthoritative(query);
75
80
  }
81
+
82
+ /** One index range of the live scan: a unit key and its exclusive lower bound. */
83
+ export interface LiveKey {
84
+ readonly var: string;
85
+ readonly value: string;
86
+ readonly after: number;
87
+ }
88
+
89
+ /**
90
+ * One row of a live-window page: a candidate commit joined to its metadata
91
+ * (absent when the commit vanished) and one of its changes (absent when it
92
+ * has none), in (commitSeq, change index) order.
93
+ */
94
+ export interface LiveWindowRow {
95
+ readonly commitSeq: number;
96
+ readonly meta?: { readonly actorId: string; readonly createdAtMs: number };
97
+ readonly change?: StoredChange;
98
+ }
99
+
100
+ /**
101
+ * The §4.5 live scan over a backend's page read. Each distinct unit key
102
+ * (the first variable, keys sorted) becomes one index range starting at the
103
+ * lowest bound of the units that share it; `readPage` returns up to `limit`
104
+ * candidate commits above every range's bound. A change is kept when a unit
105
+ * covers its table, the pair's effective scopes match it, and its commit
106
+ * lies above that unit's own bound. Every candidate advances the scan, so a
107
+ * page of non-matching candidates never repeats.
108
+ */
109
+ export async function readLiveWindowPages(
110
+ query: LiveWindowQuery,
111
+ readPage: (
112
+ keys: readonly LiveKey[],
113
+ limit: number,
114
+ ) => Promise<readonly LiveWindowRow[]>,
115
+ ): Promise<LiveWindow> {
116
+ const bounds = new Map<string, LiveKey>();
117
+ for (const unit of query.units) {
118
+ if (unit.tables.size === 0) continue;
119
+ const variable = Object.keys(unit.scopes).sort()[0];
120
+ const value = variable === undefined ? undefined : unit.scopes[variable];
121
+ if (variable === undefined || value === undefined) {
122
+ throw new StorageQueryError('sync.storage.scan_requires_scope');
123
+ }
124
+ const id = JSON.stringify([variable, value]);
125
+ const prior = bounds.get(id);
126
+ if (prior === undefined || unit.afterSeq < prior.after) {
127
+ bounds.set(id, { var: variable, value, after: unit.afterSeq });
128
+ }
129
+ }
130
+ const commits: StoredCommit[] = [];
131
+ const limit = Math.max(64, query.limitChanges);
132
+ let delivered = 0;
133
+ let scanned = -1;
134
+ while (bounds.size > 0) {
135
+ const rows = await readPage(
136
+ [...bounds.values()].map((key) => ({
137
+ ...key,
138
+ after: Math.max(key.after, scanned),
139
+ })),
140
+ limit,
141
+ );
142
+ let candidates = 0;
143
+ for (let i = 0; i < rows.length;) {
144
+ const head = rows[i];
145
+ if (head === undefined) break;
146
+ candidates += 1;
147
+ scanned = head.commitSeq;
148
+ const changes: StoredChange[] = [];
149
+ for (; rows[i]?.commitSeq === head.commitSeq; i++) {
150
+ const change = rows[i]?.change;
151
+ if (
152
+ change !== undefined &&
153
+ query.units.some((unit) => {
154
+ const effective: ScopeMap | undefined = unit.tables.get(
155
+ change.table,
156
+ );
157
+ return (
158
+ head.commitSeq > unit.afterSeq &&
159
+ effective !== undefined &&
160
+ matchesEffective(change.scopes, effective)
161
+ );
162
+ })
163
+ ) {
164
+ changes.push(change);
165
+ }
166
+ }
167
+ if (head.meta === undefined || changes.length === 0) continue;
168
+ commits.push({ commitSeq: head.commitSeq, ...head.meta, changes });
169
+ delivered += changes.length;
170
+ if (delivered >= query.limitChanges) {
171
+ return { commits, throughSeq: head.commitSeq };
172
+ }
173
+ }
174
+ if (candidates < limit) break;
175
+ }
176
+ return { commits, throughSeq: query.throughSeq };
177
+ }
package/src/storage.ts CHANGED
@@ -11,13 +11,19 @@ import type { AuthoritativeRelationPlan } from './authoritative-query';
11
11
  * - the pruning horizon per §4.6;
12
12
  * - current-row reads for write authorization (§3.4) and conflict handling
13
13
  * (§6.2);
14
- * - per-(partition, clientId) cursor records + last subscription list
15
- * (§4.5, §8.1).
14
+ * - the per-(partition, clientId) client record: registration list,
15
+ * catching-up units and record cursor (§4.5, §8.1);
16
+ * - the per-outbox acknowledged watermark (§6.3.2).
16
17
  *
17
18
  * The interface is async throughout so a Postgres implementation slots in
18
19
  * without touching the core. All methods are partition-local (§2.1).
19
20
  */
20
- import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
21
+ import type {
22
+ PushOperationResult,
23
+ RowValue,
24
+ ScopeMap,
25
+ UnitScopes,
26
+ } from '@syncular/core';
21
27
  import type { CompiledSchema } from './schema';
22
28
 
23
29
  export interface CommitPruneQuery {
@@ -84,6 +90,37 @@ export interface PreparedPushApply {
84
90
  readonly gate: ServeGate;
85
91
  /** The already-persisted outcome for this key, or `undefined` on a miss. */
86
92
  readonly persisted: StoredPushResult | undefined;
93
+ /**
94
+ * The partition's delete floor (§2.2): the highest version any applied
95
+ * delete recorded, `0` before the first. An insert starts one above it.
96
+ */
97
+ readonly deleteFloor: number;
98
+ /**
99
+ * The outbox watermark `W` after §6.3.2 step 1; present iff the call
100
+ * carried an {@link OutboxSettlement}. A commit of the request whose
101
+ * `persisted` is `undefined` and whose `clientSeq` is below `W` is
102
+ * expired (`sync.commit_expired`); at or above `W` it was never seen.
103
+ */
104
+ readonly watermark?: number;
105
+ }
106
+
107
+ /** The outbox position of one pushed commit (§6.3.2). */
108
+ export interface OutboxSequence {
109
+ readonly outboxId: string;
110
+ readonly clientSeq: number;
111
+ }
112
+
113
+ /**
114
+ * One push request's outbox, for the §9 settlement of results stored before
115
+ * wire version 4 and §6.3.2 steps 1 and 2.
116
+ */
117
+ export interface OutboxSettlement {
118
+ readonly outboxId: string;
119
+ /** Every `PUSH_COMMIT` of the request in frame order. */
120
+ readonly commits: readonly {
121
+ readonly clientCommitId: string;
122
+ readonly clientSeq: number;
123
+ }[];
87
124
  }
88
125
 
89
126
  /** Why `serveGate` refuses, or `undefined` when this request may serve. */
@@ -179,13 +216,12 @@ export interface NewChange {
179
216
  readonly table: string;
180
217
  readonly rowId: string;
181
218
  readonly op: 'upsert' | 'delete';
182
- /** Present for upsert (§2.2). */
183
- readonly rowVersion?: number;
184
219
  /**
185
- * Present for delete: the deleted row's last `server_version`, recorded on
186
- * its tombstone (§2.2). Never reaches the wire.
220
+ * The row's `server_version` after the write (§2.2): an upsert's written
221
+ * version, a delete's advanced version, which its tombstone records and
222
+ * the delete floor rises to.
187
223
  */
188
- readonly deletedVersion?: number;
224
+ readonly rowVersion: number;
189
225
  readonly scopes: Record<string, string>;
190
226
  /** Present for upsert. */
191
227
  readonly payload?: Uint8Array;
@@ -237,10 +273,29 @@ export function rowsLiveAfterDelete(
237
273
  return live;
238
274
  }
239
275
 
276
+ /**
277
+ * The delete floor a commit raises the partition's to (§2.2): the highest
278
+ * version of a delete that leaves a tombstone, `0` without one.
279
+ */
280
+ export function commitDeleteFloor(changes: readonly NewChange[]): number {
281
+ const live = rowsLiveAfterDelete(changes);
282
+ let floor = 0;
283
+ for (const change of changes) {
284
+ if (
285
+ change.op === 'delete' &&
286
+ !live.has(`${change.table}\u0000${change.rowId}`)
287
+ ) {
288
+ floor = Math.max(floor, change.rowVersion);
289
+ }
290
+ }
291
+ return floor;
292
+ }
293
+
240
294
  export interface StoredChange {
241
295
  readonly table: string;
242
296
  readonly rowId: string;
243
297
  readonly op: 'upsert' | 'delete';
298
+ /** Absent only on a delete logged before wire version 4. */
244
299
  readonly rowVersion?: number;
245
300
  readonly scopes: Record<string, string>;
246
301
  readonly payload?: Uint8Array;
@@ -348,24 +403,45 @@ export interface StoredPushResult {
348
403
  readonly results: readonly PushOperationResult[];
349
404
  }
350
405
 
351
- export interface ClientSubscription {
352
- /** Codec accepted by the last pull; absent on records written before schema windows. */
353
- readonly schemaVersion?: number;
406
+ /** The registration list a client last sent, with its digest (§4.1). */
407
+ export interface ClientRegistration {
408
+ /** Scope maps in registration order. */
409
+ readonly units: readonly UnitScopes[];
410
+ /** The 32-byte registration digest. */
411
+ readonly digest: Uint8Array;
412
+ }
413
+
414
+ /** A unit still catching up after the client's last completed round (§4.1). */
415
+ export interface CatchingUpUnit {
416
+ /** The unit id (§4.1). */
354
417
  readonly id: string;
355
- readonly table: string;
356
- /** Requested scopes of the client's most recent pull (§8.1). */
357
- readonly scopes: ScopeMap;
418
+ /** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
419
+ readonly cursor: number;
358
420
  }
359
421
 
422
+ /** The §4.5 client record. */
360
423
  export interface ClientRecord {
361
424
  readonly clientId: string;
362
425
  readonly actorId: string;
363
- /** SSP2 version last accepted from this client; selects realtime deltas. */
426
+ /** SSP2 version last accepted from this client. */
364
427
  readonly wireVersion: number;
365
- /** Minimum `nextCursor` across the last pull's active subscriptions. */
428
+ /** The record cursor (§4.5); feeds the §4.6 retention watermark. */
366
429
  readonly cursor: number;
367
430
  readonly updatedAtMs: number;
368
- readonly subscriptions: readonly ClientSubscription[];
431
+ /**
432
+ * Schema version of the latest completed round; realtime projects deltas
433
+ * through its codec. Absent on a record written before wire version 4.
434
+ */
435
+ readonly schemaVersion?: number;
436
+ /**
437
+ * The stored registration list; absent when none is stored (§9: a record
438
+ * written before wire version 4 holds none). On `putClientRecord`, absent
439
+ * keeps the stored list and digest: a round writes them only when its
440
+ * list traveled.
441
+ */
442
+ readonly registration?: ClientRegistration;
443
+ /** Catching-up units in registration order; the rest of the list is live. */
444
+ readonly catchingUp: readonly CatchingUpUnit[];
369
445
  /** When this client's last sync round finished, successfully or not. */
370
446
  readonly lastRoundAtMs?: number;
371
447
  /** Code of the last round when it failed; absent after a successful round. */
@@ -400,24 +476,45 @@ export function clientRoundState(
400
476
  };
401
477
  }
402
478
 
403
- export interface CommitWindowQuery {
404
- readonly table: string;
479
+ /** One unit of the §4.5 scan set. */
480
+ export interface LiveScanUnit {
481
+ /** The unit's scope map; its first variable (keys sorted) is its index key. */
482
+ readonly scopes: UnitScopes;
483
+ /** Exclusive lower bound: `R`, the unit's cursor `P`, or its pin. */
484
+ readonly afterSeq: number;
405
485
  /**
406
- * Effective scopes (§3.2): a change matches iff, for every key, its
407
- * stored value is in the list. Implementations MUST select candidates
408
- * via the inverted scope index, never by scanning the log.
486
+ * The unit's active (unit, table) pairs: covered table → effective scopes
487
+ * (§3.2). A change of table `t` matches iff its stored scopes satisfy the
488
+ * pair for `t` and its commit lies above `afterSeq`.
409
489
  */
410
- readonly scopeFilter: ScopeMap;
411
- /** Window `afterSeq < commitSeq <= throughSeq`, oldest first (§4.5). */
412
- readonly afterSeq: number;
490
+ readonly tables: ReadonlyMap<string, ScopeMap>;
491
+ }
492
+
493
+ export interface LiveWindowQuery {
494
+ readonly units: readonly LiveScanUnit[];
495
+ /** `maxCommitSeq` read at the start of the pull. */
413
496
  readonly throughSeq: number;
414
- /** Stop after accumulating at least this many matching changes. */
497
+ /** The `limitCommits` budget: stop after the commit that reaches it. */
415
498
  readonly limitChanges: number;
416
499
  }
417
500
 
501
+ /** The commits of one live section (§4.5). */
502
+ export interface LiveWindow {
503
+ /** Oldest first, each with its matching changes in change order. */
504
+ readonly commits: readonly StoredCommit[];
505
+ /**
506
+ * `T`: `query.throughSeq`, or the last delivered `commitSeq` when the
507
+ * budget cut the section.
508
+ */
509
+ readonly throughSeq: number;
510
+ }
511
+
418
512
  export interface RowScanQuery {
419
513
  readonly table: string;
420
- /** Same matching rule as `CommitWindowQuery.scopeFilter`, over rows. */
514
+ /**
515
+ * Effective scopes (§3.2): a row matches iff, for every key, its stored
516
+ * value is in the list. Candidates come from the inverted row-scope index.
517
+ */
421
518
  readonly scopeFilter: ScopeMap;
422
519
  /** Resume after this rowId (exclusive); `null` = start of table. */
423
520
  readonly afterRowId: string | null;
@@ -506,6 +603,14 @@ export interface RowListQuery {
506
603
  readonly limit: number;
507
604
  }
508
605
 
606
+ /** One §6.3.2 watermark row. */
607
+ export interface PushWatermark {
608
+ readonly clientId: string;
609
+ readonly outboxId: string;
610
+ /** `W`: results of this outbox below it are deleted. */
611
+ readonly throughSeq: number;
612
+ }
613
+
509
614
  /** A stored push outcome with the client that sent it. */
510
615
  export interface ClientPushResult {
511
616
  readonly clientId: string;
@@ -663,6 +768,13 @@ export interface StorageTransaction {
663
768
  * are built; a storage with per-statement network cost folds that read-ahead
664
769
  * into the admission read and answers the following `getRow` calls from it.
665
770
  * Missing support fails closed before an app-row mutation.
771
+ *
772
+ * `outbox`, passed with the first commit of a request that carries an
773
+ * `outboxId`, settles the client's results stored before wire version 4
774
+ * (§9) and runs §6.3.2 steps 1 and 2 under the same lock, before the read
775
+ * of `persisted`. Those writes survive `commitRejectedPushResult`; the
776
+ * caller commits this transaction whatever the commit's outcome, so the
777
+ * settlement runs exactly once per request.
666
778
  */
667
779
  preparePushApply(
668
780
  clientId: string,
@@ -672,6 +784,7 @@ export interface StorageTransaction {
672
784
  readonly table: string;
673
785
  readonly rowIds: readonly string[];
674
786
  }[],
787
+ outbox?: OutboxSettlement,
675
788
  ): Promise<PreparedPushApply>;
676
789
  /**
677
790
  * Rejection finalization while the push-apply serialization lock is still
@@ -685,6 +798,7 @@ export interface StorageTransaction {
685
798
  clientId: string,
686
799
  clientCommitId: string,
687
800
  result: StoredPushResult,
801
+ sequence?: OutboxSequence,
688
802
  ): Promise<StoredPushResult>;
689
803
  upsertRow(
690
804
  table: string,
@@ -702,12 +816,15 @@ export interface StorageTransaction {
702
816
  enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
703
817
  /**
704
818
  * Persist an idempotency outcome only when the key is still absent. The
705
- * first writer wins; callers read the canonical value after commit.
819
+ * first writer wins; callers read the canonical value after commit. A
820
+ * result without `sequence` (no `outboxId`, §6.10, §12.3) is never deleted
821
+ * by a watermark.
706
822
  */
707
823
  putPushResult(
708
824
  clientId: string,
709
825
  clientCommitId: string,
710
826
  result: StoredPushResult,
827
+ sequence?: OutboxSequence,
711
828
  ): Promise<void>;
712
829
  /**
713
830
  * Advance this partition's checkpoint only while `owner_epoch` still
@@ -799,7 +916,10 @@ export interface ServerStorage {
799
916
  authenticatedAtMs: number,
800
917
  initialLogEpoch: string,
801
918
  ): Promise<PartitionRegistryEntry>;
802
- /** Rotate log continuity after restore and discard stale cursor records. */
919
+ /**
920
+ * Rotate log continuity after restore and delete the partition's client
921
+ * records. Watermark rows stay (§6.3.2).
922
+ */
803
923
  rotatePartitionLogEpoch(
804
924
  partition: string,
805
925
  logEpoch: string,
@@ -988,26 +1108,29 @@ export interface ServerStorage {
988
1108
  ): Promise<PrunedReactionCounts>;
989
1109
 
990
1110
  /**
991
- * Matching commits in the window, oldest first, each carrying only its
992
- * matching changes for `table`. Stops once accumulated matching changes
993
- * reach `limitChanges` or the window is exhausted.
1111
+ * The §4.5 live section: every commit in `(min afterSeq, throughSeq]`
1112
+ * carrying a change that matches a unit of the scan set, oldest first,
1113
+ * each with its matching changes once, in change order, across tables.
1114
+ * Stops after the commit whose matching changes reach `limitChanges`
1115
+ * (never splitting a commit). Candidates come from the change-scope key
1116
+ * index, one index range per distinct unit key, never from a log scan.
994
1117
  */
995
- readCommitWindow(
1118
+ readLiveWindow(
996
1119
  partition: string,
997
- query: CommitWindowQuery,
998
- ): Promise<StoredCommit[]>;
1120
+ query: LiveWindowQuery,
1121
+ ): Promise<LiveWindow>;
999
1122
 
1000
1123
  /**
1001
- * Newest commitSeq whose change to `query.table` carries a value of the
1002
- * filter's first variable (keys sorted) in the inverted change-scope index:
1003
- * the `readCommitWindow` candidate rule, so no change a window read would
1004
- * deliver for this filter sits above it. 0 when the index holds none (never
1005
- * written, or pruned). The §4.7 sqlite-lane bootstrap pin reads it; it MUST
1006
- * be an index lookup per value, independent of the table's history.
1124
+ * Newest commitSeq whose change to `query.table` carries the unit's value
1125
+ * of its first variable (keys sorted): the `readLiveWindow` candidate rule,
1126
+ * so no change the unit would receive for the table sits above it. 0 when
1127
+ * the index holds none (never written, or pruned). The §4.7 sqlite-lane
1128
+ * scope pin reads it; it MUST be one index lookup, independent of the
1129
+ * table's history.
1007
1130
  */
1008
1131
  latestScopedChangeSeq(
1009
1132
  partition: string,
1010
- query: { readonly table: string; readonly scopeFilter: ScopeMap },
1133
+ query: { readonly table: string; readonly scopes: UnitScopes },
1011
1134
  ): Promise<number>;
1012
1135
 
1013
1136
  /** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
@@ -1052,10 +1175,13 @@ export interface ServerStorage {
1052
1175
  clientId: string,
1053
1176
  ): Promise<ClientRecord | undefined>;
1054
1177
  /**
1055
- * Write the record for a completed round. The round-state fields reset: the
1056
- * stored last round is a success at `updatedAtMs` with no failures — unless
1057
- * `keepRoundOutcome` is set, which leaves the reported code and streak in
1058
- * place (the round carried a `ROUND_FAILURE` report, §1.5/§4.5).
1178
+ * Write the record for a completed round (§4.5). A record without
1179
+ * `registration` keeps the stored list and digest. The round-state fields
1180
+ * reset: the stored last round is a success at `lastRoundAtMs` (default
1181
+ * `updatedAtMs`) with no failures, unless `keepRoundOutcome` is set, which
1182
+ * leaves the reported code and streak in place (the round carried a
1183
+ * `ROUND_FAILURE` report, §1.5/§4.5). An `unregistered` answer rewrites the
1184
+ * stored record with only `lastRoundAtMs` moved.
1059
1185
  */
1060
1186
  putClientRecord(
1061
1187
  partition: string,
@@ -1076,9 +1202,11 @@ export interface ServerStorage {
1076
1202
  atMs: number,
1077
1203
  ): Promise<void>;
1078
1204
  /**
1079
- * Atomically advance an existing record's cursor and activity timestamp.
1080
- * Preserve registration fields; require matching actor and current log epoch.
1081
- * Missing records and mismatched identities are unchanged (§8.2).
1205
+ * §8.2 ack: atomically raise an existing record's cursor to `cursor`,
1206
+ * capped at the lowest non-negative cursor of its catching-up units, and
1207
+ * its activity timestamp, both monotonically. Every other field stays;
1208
+ * requires the matching actor and the current log epoch. A missing record
1209
+ * or a mismatched identity is unchanged.
1082
1210
  */
1083
1211
  advanceClientCursor(
1084
1212
  partition: string,
@@ -1088,14 +1216,6 @@ export interface ServerStorage {
1088
1216
  cursor: number,
1089
1217
  updatedAtMs: number,
1090
1218
  ): Promise<void>;
1091
- /** Advance an existing client's ACK cursor and timestamp atomically,
1092
- * preserving actor, wire version, and subscriptions. Missing records stay absent. */
1093
- updateClientCursor(
1094
- partition: string,
1095
- clientId: string,
1096
- cursor: number,
1097
- updatedAtMs: number,
1098
- ): Promise<void>;
1099
1219
  /**
1100
1220
  * Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
1101
1221
  * none are active. A bootstrapping client (cursor < 0) holds no cursor.
@@ -1157,7 +1277,7 @@ export interface ServerStorage {
1157
1277
  * calls them.
1158
1278
  *
1159
1279
  * `listClientRecords`: every stored client record for the partition
1160
- * (cursor, last-seen, subscription list) — the "who's connected" view.
1280
+ * (cursor, last-seen, registration list): the "who's connected" view.
1161
1281
  * `listCommitMetadata`: the commit log without payloads (metadata +
1162
1282
  * touched tables), the newest-oriented window an operator inspects.
1163
1283
  * `scopeActivity`: the recent commits touching one scope key, via the
@@ -1172,6 +1292,9 @@ export interface ServerStorage {
1172
1292
  * `listPushResults`: every stored idempotency outcome for one
1173
1293
  * clientCommitId across the partition's clients, scanning the retained
1174
1294
  * outcomes without a dedicated index.
1295
+ * `listPushWatermarks`: the §6.3.2 watermark rows of every client whose
1296
+ * retained commit log carries the clientCommitId; a commit whose result
1297
+ * the watermark deleted reads as "expired below sequence `throughSeq`".
1175
1298
  * `listPartitions`: the partition-only compatibility view of
1176
1299
  * `listPartitionRegistry`, sorted.
1177
1300
  */
@@ -1198,6 +1321,10 @@ export interface ServerStorage {
1198
1321
  partition: string,
1199
1322
  clientCommitId: string,
1200
1323
  ): Promise<ClientPushResult[]>;
1324
+ listPushWatermarks?(
1325
+ partition: string,
1326
+ clientCommitId: string,
1327
+ ): Promise<PushWatermark[]>;
1201
1328
  listPartitions(): Promise<string[]>;
1202
1329
  }
1203
1330