@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
@@ -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,28 @@ 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;
219
+ /**
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.
223
+ */
224
+ readonly rowVersion: number;
184
225
  readonly scopes: Record<string, string>;
185
226
  /** Present for upsert. */
186
227
  readonly payload?: Uint8Array;
187
228
  }
188
229
 
230
+ /** §2.2 delete-precedence tombstone of a row deleted within the horizon. */
231
+ export interface Tombstone {
232
+ readonly commitSeq: number;
233
+ /**
234
+ * The deleted row's last `server_version` and stored scopes. Both are
235
+ * absent on a tombstone written before servers recorded them.
236
+ */
237
+ readonly serverVersion?: number;
238
+ readonly scopes?: Record<string, string>;
239
+ }
240
+
189
241
  export interface NewCommit {
190
242
  readonly clientId: string;
191
243
  readonly clientCommitId: string;
@@ -221,10 +273,29 @@ export function rowsLiveAfterDelete(
221
273
  return live;
222
274
  }
223
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
+
224
294
  export interface StoredChange {
225
295
  readonly table: string;
226
296
  readonly rowId: string;
227
297
  readonly op: 'upsert' | 'delete';
298
+ /** Absent only on a delete logged before wire version 4. */
228
299
  readonly rowVersion?: number;
229
300
  readonly scopes: Record<string, string>;
230
301
  readonly payload?: Uint8Array;
@@ -332,24 +403,45 @@ export interface StoredPushResult {
332
403
  readonly results: readonly PushOperationResult[];
333
404
  }
334
405
 
335
- export interface ClientSubscription {
336
- /** Codec accepted by the last pull; absent on records written before schema windows. */
337
- 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). */
338
417
  readonly id: string;
339
- readonly table: string;
340
- /** Requested scopes of the client's most recent pull (§8.1). */
341
- readonly scopes: ScopeMap;
418
+ /** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
419
+ readonly cursor: number;
342
420
  }
343
421
 
422
+ /** The §4.5 client record. */
344
423
  export interface ClientRecord {
345
424
  readonly clientId: string;
346
425
  readonly actorId: string;
347
- /** SSP2 version last accepted from this client; selects realtime deltas. */
426
+ /** SSP2 version last accepted from this client. */
348
427
  readonly wireVersion: number;
349
- /** Minimum `nextCursor` across the last pull's active subscriptions. */
428
+ /** The record cursor (§4.5); feeds the §4.6 retention watermark. */
350
429
  readonly cursor: number;
351
430
  readonly updatedAtMs: number;
352
- 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[];
353
445
  /** When this client's last sync round finished, successfully or not. */
354
446
  readonly lastRoundAtMs?: number;
355
447
  /** Code of the last round when it failed; absent after a successful round. */
@@ -384,24 +476,45 @@ export function clientRoundState(
384
476
  };
385
477
  }
386
478
 
387
- export interface CommitWindowQuery {
388
- 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;
389
485
  /**
390
- * Effective scopes (§3.2): a change matches iff, for every key, its
391
- * stored value is in the list. Implementations MUST select candidates
392
- * 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`.
393
489
  */
394
- readonly scopeFilter: ScopeMap;
395
- /** Window `afterSeq < commitSeq <= throughSeq`, oldest first (§4.5). */
396
- 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. */
397
496
  readonly throughSeq: number;
398
- /** Stop after accumulating at least this many matching changes. */
497
+ /** The `limitCommits` budget: stop after the commit that reaches it. */
399
498
  readonly limitChanges: number;
400
499
  }
401
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
+
402
512
  export interface RowScanQuery {
403
513
  readonly table: string;
404
- /** 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
+ */
405
518
  readonly scopeFilter: ScopeMap;
406
519
  /** Resume after this rowId (exclusive); `null` = start of table. */
407
520
  readonly afterRowId: string | null;
@@ -490,6 +603,14 @@ export interface RowListQuery {
490
603
  readonly limit: number;
491
604
  }
492
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
+
493
614
  /** A stored push outcome with the client that sent it. */
494
615
  export interface ClientPushResult {
495
616
  readonly clientId: string;
@@ -590,17 +711,17 @@ export interface StorageTransaction {
590
711
  }[],
591
712
  ): Promise<void>;
592
713
  /**
593
- * §5 delete-precedence tombstone read: the `commit_seq` of the newest
594
- * applied delete of this row still within the pruning horizon, or
595
- * `undefined` when no tombstone exists. Consulted only when an upsert's
596
- * stored row is absent. Required: in-tree adapters implement it on the
597
- * transaction's own connection with read-your-own-writes semantics.
714
+ * §5 delete-precedence tombstone read: the newest applied delete of this
715
+ * row still within the pruning horizon, or `undefined` when no tombstone
716
+ * exists. Consulted only when an upsert's stored row is absent. Required:
717
+ * in-tree adapters implement it on the transaction's own connection with
718
+ * read-your-own-writes semantics.
598
719
  */
599
- getTombstoneSeq(table: string, rowId: string): Promise<number | undefined>;
720
+ getTombstone(table: string, rowId: string): Promise<Tombstone | undefined>;
600
721
  /**
601
- * Remove the row's tombstone because the row was recreated in this
602
- * transaction (§5: an explicit insert recreates). Called on every insert
603
- * over an absent row; a no-op when no tombstone exists.
722
+ * Remove the row's tombstone because the row is live again in this
723
+ * transaction: an insert over its tombstone (§6.2) or a §2.2 scope move.
724
+ * A no-op when no tombstone exists.
604
725
  */
605
726
  clearTombstone(table: string, rowId: string): Promise<void>;
606
727
  /**
@@ -647,6 +768,13 @@ export interface StorageTransaction {
647
768
  * are built; a storage with per-statement network cost folds that read-ahead
648
769
  * into the admission read and answers the following `getRow` calls from it.
649
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.
650
778
  */
651
779
  preparePushApply(
652
780
  clientId: string,
@@ -656,6 +784,7 @@ export interface StorageTransaction {
656
784
  readonly table: string;
657
785
  readonly rowIds: readonly string[];
658
786
  }[],
787
+ outbox?: OutboxSettlement,
659
788
  ): Promise<PreparedPushApply>;
660
789
  /**
661
790
  * Rejection finalization while the push-apply serialization lock is still
@@ -669,6 +798,7 @@ export interface StorageTransaction {
669
798
  clientId: string,
670
799
  clientCommitId: string,
671
800
  result: StoredPushResult,
801
+ sequence?: OutboxSequence,
672
802
  ): Promise<StoredPushResult>;
673
803
  upsertRow(
674
804
  table: string,
@@ -686,12 +816,15 @@ export interface StorageTransaction {
686
816
  enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
687
817
  /**
688
818
  * Persist an idempotency outcome only when the key is still absent. The
689
- * 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.
690
822
  */
691
823
  putPushResult(
692
824
  clientId: string,
693
825
  clientCommitId: string,
694
826
  result: StoredPushResult,
827
+ sequence?: OutboxSequence,
695
828
  ): Promise<void>;
696
829
  /**
697
830
  * Advance this partition's checkpoint only while `owner_epoch` still
@@ -783,7 +916,10 @@ export interface ServerStorage {
783
916
  authenticatedAtMs: number,
784
917
  initialLogEpoch: string,
785
918
  ): Promise<PartitionRegistryEntry>;
786
- /** 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
+ */
787
923
  rotatePartitionLogEpoch(
788
924
  partition: string,
789
925
  logEpoch: string,
@@ -972,26 +1108,29 @@ export interface ServerStorage {
972
1108
  ): Promise<PrunedReactionCounts>;
973
1109
 
974
1110
  /**
975
- * Matching commits in the window, oldest first, each carrying only its
976
- * matching changes for `table`. Stops once accumulated matching changes
977
- * 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.
978
1117
  */
979
- readCommitWindow(
1118
+ readLiveWindow(
980
1119
  partition: string,
981
- query: CommitWindowQuery,
982
- ): Promise<StoredCommit[]>;
1120
+ query: LiveWindowQuery,
1121
+ ): Promise<LiveWindow>;
983
1122
 
984
1123
  /**
985
- * Newest commitSeq whose change to `query.table` carries a value of the
986
- * filter's first variable (keys sorted) in the inverted change-scope index:
987
- * the `readCommitWindow` candidate rule, so no change a window read would
988
- * deliver for this filter sits above it. 0 when the index holds none (never
989
- * written, or pruned). The §4.7 sqlite-lane bootstrap pin reads it; it MUST
990
- * 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.
991
1130
  */
992
1131
  latestScopedChangeSeq(
993
1132
  partition: string,
994
- query: { readonly table: string; readonly scopeFilter: ScopeMap },
1133
+ query: { readonly table: string; readonly scopes: UnitScopes },
995
1134
  ): Promise<number>;
996
1135
 
997
1136
  /** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
@@ -1036,10 +1175,13 @@ export interface ServerStorage {
1036
1175
  clientId: string,
1037
1176
  ): Promise<ClientRecord | undefined>;
1038
1177
  /**
1039
- * Write the record for a completed round. The round-state fields reset: the
1040
- * stored last round is a success at `updatedAtMs` with no failures — unless
1041
- * `keepRoundOutcome` is set, which leaves the reported code and streak in
1042
- * 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.
1043
1185
  */
1044
1186
  putClientRecord(
1045
1187
  partition: string,
@@ -1060,9 +1202,11 @@ export interface ServerStorage {
1060
1202
  atMs: number,
1061
1203
  ): Promise<void>;
1062
1204
  /**
1063
- * Atomically advance an existing record's cursor and activity timestamp.
1064
- * Preserve registration fields; require matching actor and current log epoch.
1065
- * 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.
1066
1210
  */
1067
1211
  advanceClientCursor(
1068
1212
  partition: string,
@@ -1072,15 +1216,10 @@ export interface ServerStorage {
1072
1216
  cursor: number,
1073
1217
  updatedAtMs: number,
1074
1218
  ): Promise<void>;
1075
- /** Advance an existing client's ACK cursor and timestamp atomically,
1076
- * preserving actor, wire version, and subscriptions. Missing records stay absent. */
1077
- updateClientCursor(
1078
- partition: string,
1079
- clientId: string,
1080
- cursor: number,
1081
- updatedAtMs: number,
1082
- ): Promise<void>;
1083
- /** Minimum cursor with updatedAtMs >= cutoff; null when none are active. */
1219
+ /**
1220
+ * Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
1221
+ * none are active. A bootstrapping client (cursor < 0) holds no cursor.
1222
+ */
1084
1223
  getActiveClientCursorFloor(
1085
1224
  partition: string,
1086
1225
  cutoffMs: number,
@@ -1116,9 +1255,11 @@ export interface ServerStorage {
1116
1255
  * `eraseScopeValueHistory`: under the partition write lock, removes up to
1117
1256
  * `limit` upsert change records of `table` at or below `throughSeq` whose
1118
1257
  * scopes bind `variable` to `value`, then up to `limit` change scope index
1119
- * entries of that binding whose commit holds no such change any more.
1258
+ * entries of that binding whose commit holds no such change any more,
1259
+ * then strips `serverRow` from up to `limit` stored conflict results of
1260
+ * `table` whose conflict authorization scopes bind `variable` to `value`.
1120
1261
  * Delete change records stay: clients behind the erasure still need them.
1121
- * Returns the number of records removed.
1262
+ * Returns the number of records removed or stripped.
1122
1263
  */
1123
1264
  listScopeValueRows?(
1124
1265
  partition: string,
@@ -1136,7 +1277,7 @@ export interface ServerStorage {
1136
1277
  * calls them.
1137
1278
  *
1138
1279
  * `listClientRecords`: every stored client record for the partition
1139
- * (cursor, last-seen, subscription list) — the "who's connected" view.
1280
+ * (cursor, last-seen, registration list): the "who's connected" view.
1140
1281
  * `listCommitMetadata`: the commit log without payloads (metadata +
1141
1282
  * touched tables), the newest-oriented window an operator inspects.
1142
1283
  * `scopeActivity`: the recent commits touching one scope key, via the
@@ -1151,6 +1292,9 @@ export interface ServerStorage {
1151
1292
  * `listPushResults`: every stored idempotency outcome for one
1152
1293
  * clientCommitId across the partition's clients, scanning the retained
1153
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`".
1154
1298
  * `listPartitions`: the partition-only compatibility view of
1155
1299
  * `listPartitionRegistry`, sorted.
1156
1300
  */
@@ -1177,6 +1321,10 @@ export interface ServerStorage {
1177
1321
  partition: string,
1178
1322
  clientCommitId: string,
1179
1323
  ): Promise<ClientPushResult[]>;
1324
+ listPushWatermarks?(
1325
+ partition: string,
1326
+ clientCommitId: string,
1327
+ ): Promise<PushWatermark[]>;
1180
1328
  listPartitions(): Promise<string[]>;
1181
1329
  }
1182
1330