@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,5 +1,5 @@
1
1
  import type { CompiledTable, IndexSchema } from './schema.js';
2
- import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, IndexRowScanQuery, RowScanQuery, StorageTransaction } from './storage.js';
2
+ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, RowScanQuery, StorageTransaction, StoredChange } from './storage.js';
3
3
  /**
4
4
  * Fail loudly instead of making an unsupported unscoped scan look empty.
5
5
  * Returns the first scope variable in sorted order — the one every adapter
@@ -15,3 +15,32 @@ export declare function resolveIndexRowScan(table: CompiledTable, query: IndexRo
15
15
  * which reads outside the transaction.
16
16
  */
17
17
  export declare function transactionQuery(tx: StorageTransaction, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
18
+ /** One index range of the live scan: a unit key and its exclusive lower bound. */
19
+ export interface LiveKey {
20
+ readonly var: string;
21
+ readonly value: string;
22
+ readonly after: number;
23
+ }
24
+ /**
25
+ * One row of a live-window page: a candidate commit joined to its metadata
26
+ * (absent when the commit vanished) and one of its changes (absent when it
27
+ * has none), in (commitSeq, change index) order.
28
+ */
29
+ export interface LiveWindowRow {
30
+ readonly commitSeq: number;
31
+ readonly meta?: {
32
+ readonly actorId: string;
33
+ readonly createdAtMs: number;
34
+ };
35
+ readonly change?: StoredChange;
36
+ }
37
+ /**
38
+ * The §4.5 live scan over a backend's page read. Each distinct unit key
39
+ * (the first variable, keys sorted) becomes one index range starting at the
40
+ * lowest bound of the units that share it; `readPage` returns up to `limit`
41
+ * candidate commits above every range's bound. A change is kept when a unit
42
+ * covers its table, the pair's effective scopes match it, and its commit
43
+ * lies above that unit's own bound. Every candidate advances the scan, so a
44
+ * page of non-matching candidates never repeats.
45
+ */
46
+ export declare function readLiveWindowPages(query: LiveWindowQuery, readPage: (keys: readonly LiveKey[], limit: number) => Promise<readonly LiveWindowRow[]>): Promise<LiveWindow>;
@@ -1,3 +1,4 @@
1
+ import { matchesEffective } from './scopes.js';
1
2
  import { StorageQueryError } from './storage-errors.js';
2
3
  /**
3
4
  * Fail loudly instead of making an unsupported unscoped scan look empty.
@@ -46,3 +47,70 @@ export async function transactionQuery(tx, query) {
46
47
  }
47
48
  return tx.queryAuthoritative(query);
48
49
  }
50
+ /**
51
+ * The §4.5 live scan over a backend's page read. Each distinct unit key
52
+ * (the first variable, keys sorted) becomes one index range starting at the
53
+ * lowest bound of the units that share it; `readPage` returns up to `limit`
54
+ * candidate commits above every range's bound. A change is kept when a unit
55
+ * covers its table, the pair's effective scopes match it, and its commit
56
+ * lies above that unit's own bound. Every candidate advances the scan, so a
57
+ * page of non-matching candidates never repeats.
58
+ */
59
+ export async function readLiveWindowPages(query, readPage) {
60
+ const bounds = new Map();
61
+ for (const unit of query.units) {
62
+ if (unit.tables.size === 0)
63
+ continue;
64
+ const variable = Object.keys(unit.scopes).sort()[0];
65
+ const value = variable === undefined ? undefined : unit.scopes[variable];
66
+ if (variable === undefined || value === undefined) {
67
+ throw new StorageQueryError('sync.storage.scan_requires_scope');
68
+ }
69
+ const id = JSON.stringify([variable, value]);
70
+ const prior = bounds.get(id);
71
+ if (prior === undefined || unit.afterSeq < prior.after) {
72
+ bounds.set(id, { var: variable, value, after: unit.afterSeq });
73
+ }
74
+ }
75
+ const commits = [];
76
+ const limit = Math.max(64, query.limitChanges);
77
+ let delivered = 0;
78
+ let scanned = -1;
79
+ while (bounds.size > 0) {
80
+ const rows = await readPage([...bounds.values()].map((key) => ({
81
+ ...key,
82
+ after: Math.max(key.after, scanned),
83
+ })), limit);
84
+ let candidates = 0;
85
+ for (let i = 0; i < rows.length;) {
86
+ const head = rows[i];
87
+ if (head === undefined)
88
+ break;
89
+ candidates += 1;
90
+ scanned = head.commitSeq;
91
+ const changes = [];
92
+ for (; rows[i]?.commitSeq === head.commitSeq; i++) {
93
+ const change = rows[i]?.change;
94
+ if (change !== undefined &&
95
+ query.units.some((unit) => {
96
+ const effective = unit.tables.get(change.table);
97
+ return (head.commitSeq > unit.afterSeq &&
98
+ effective !== undefined &&
99
+ matchesEffective(change.scopes, effective));
100
+ })) {
101
+ changes.push(change);
102
+ }
103
+ }
104
+ if (head.meta === undefined || changes.length === 0)
105
+ continue;
106
+ commits.push({ commitSeq: head.commitSeq, ...head.meta, changes });
107
+ delivered += changes.length;
108
+ if (delivered >= query.limitChanges) {
109
+ return { commits, throughSeq: head.commitSeq };
110
+ }
111
+ }
112
+ if (candidates < limit)
113
+ break;
114
+ }
115
+ return { commits, throughSeq: query.throughSeq };
116
+ }
package/dist/storage.d.ts CHANGED
@@ -11,13 +11,14 @@ import type { AuthoritativeRelationPlan } from './authoritative-query.js';
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 { PushOperationResult, RowValue, ScopeMap, UnitScopes } from '@syncular/core';
21
22
  import type { CompiledSchema } from './schema.js';
22
23
  export interface CommitPruneQuery {
23
24
  readonly logEpoch: string;
@@ -77,6 +78,35 @@ export interface PreparedPushApply {
77
78
  readonly gate: ServeGate;
78
79
  /** The already-persisted outcome for this key, or `undefined` on a miss. */
79
80
  readonly persisted: StoredPushResult | undefined;
81
+ /**
82
+ * The partition's delete floor (§2.2): the highest version any applied
83
+ * delete recorded, `0` before the first. An insert starts one above it.
84
+ */
85
+ readonly deleteFloor: number;
86
+ /**
87
+ * The outbox watermark `W` after §6.3.2 step 1; present iff the call
88
+ * carried an {@link OutboxSettlement}. A commit of the request whose
89
+ * `persisted` is `undefined` and whose `clientSeq` is below `W` is
90
+ * expired (`sync.commit_expired`); at or above `W` it was never seen.
91
+ */
92
+ readonly watermark?: number;
93
+ }
94
+ /** The outbox position of one pushed commit (§6.3.2). */
95
+ export interface OutboxSequence {
96
+ readonly outboxId: string;
97
+ readonly clientSeq: number;
98
+ }
99
+ /**
100
+ * One push request's outbox, for the §9 settlement of results stored before
101
+ * wire version 4 and §6.3.2 steps 1 and 2.
102
+ */
103
+ export interface OutboxSettlement {
104
+ readonly outboxId: string;
105
+ /** Every `PUSH_COMMIT` of the request in frame order. */
106
+ readonly commits: readonly {
107
+ readonly clientCommitId: string;
108
+ readonly clientSeq: number;
109
+ }[];
80
110
  }
81
111
  /** Why `serveGate` refuses, or `undefined` when this request may serve. */
82
112
  export type ServeGateRefusal = {
@@ -126,12 +156,26 @@ export interface NewChange {
126
156
  readonly table: string;
127
157
  readonly rowId: string;
128
158
  readonly op: 'upsert' | 'delete';
129
- /** Present for upsert (§2.2). */
130
- readonly rowVersion?: number;
159
+ /**
160
+ * The row's `server_version` after the write (§2.2): an upsert's written
161
+ * version, a delete's advanced version, which its tombstone records and
162
+ * the delete floor rises to.
163
+ */
164
+ readonly rowVersion: number;
131
165
  readonly scopes: Record<string, string>;
132
166
  /** Present for upsert. */
133
167
  readonly payload?: Uint8Array;
134
168
  }
169
+ /** §2.2 delete-precedence tombstone of a row deleted within the horizon. */
170
+ export interface Tombstone {
171
+ readonly commitSeq: number;
172
+ /**
173
+ * The deleted row's last `server_version` and stored scopes. Both are
174
+ * absent on a tombstone written before servers recorded them.
175
+ */
176
+ readonly serverVersion?: number;
177
+ readonly scopes?: Record<string, string>;
178
+ }
135
179
  export interface NewCommit {
136
180
  readonly clientId: string;
137
181
  readonly clientCommitId: string;
@@ -146,10 +190,16 @@ export interface NewCommit {
146
190
  * its tombstone.
147
191
  */
148
192
  export declare function rowsLiveAfterDelete(changes: readonly NewChange[]): Set<string>;
193
+ /**
194
+ * The delete floor a commit raises the partition's to (§2.2): the highest
195
+ * version of a delete that leaves a tombstone, `0` without one.
196
+ */
197
+ export declare function commitDeleteFloor(changes: readonly NewChange[]): number;
149
198
  export interface StoredChange {
150
199
  readonly table: string;
151
200
  readonly rowId: string;
152
201
  readonly op: 'upsert' | 'delete';
202
+ /** Absent only on a delete logged before wire version 4. */
153
203
  readonly rowVersion?: number;
154
204
  readonly scopes: Record<string, string>;
155
205
  readonly payload?: Uint8Array;
@@ -242,23 +292,43 @@ export interface StoredPushResult {
242
292
  };
243
293
  readonly results: readonly PushOperationResult[];
244
294
  }
245
- export interface ClientSubscription {
246
- /** Codec accepted by the last pull; absent on records written before schema windows. */
247
- readonly schemaVersion?: number;
295
+ /** The registration list a client last sent, with its digest (§4.1). */
296
+ export interface ClientRegistration {
297
+ /** Scope maps in registration order. */
298
+ readonly units: readonly UnitScopes[];
299
+ /** The 32-byte registration digest. */
300
+ readonly digest: Uint8Array;
301
+ }
302
+ /** A unit still catching up after the client's last completed round (§4.1). */
303
+ export interface CatchingUpUnit {
304
+ /** The unit id (§4.1). */
248
305
  readonly id: string;
249
- readonly table: string;
250
- /** Requested scopes of the client's most recent pull (§8.1). */
251
- readonly scopes: ScopeMap;
306
+ /** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
307
+ readonly cursor: number;
252
308
  }
309
+ /** The §4.5 client record. */
253
310
  export interface ClientRecord {
254
311
  readonly clientId: string;
255
312
  readonly actorId: string;
256
- /** SSP2 version last accepted from this client; selects realtime deltas. */
313
+ /** SSP2 version last accepted from this client. */
257
314
  readonly wireVersion: number;
258
- /** Minimum `nextCursor` across the last pull's active subscriptions. */
315
+ /** The record cursor (§4.5); feeds the §4.6 retention watermark. */
259
316
  readonly cursor: number;
260
317
  readonly updatedAtMs: number;
261
- readonly subscriptions: readonly ClientSubscription[];
318
+ /**
319
+ * Schema version of the latest completed round; realtime projects deltas
320
+ * through its codec. Absent on a record written before wire version 4.
321
+ */
322
+ readonly schemaVersion?: number;
323
+ /**
324
+ * The stored registration list; absent when none is stored (§9: a record
325
+ * written before wire version 4 holds none). On `putClientRecord`, absent
326
+ * keeps the stored list and digest: a round writes them only when its
327
+ * list traveled.
328
+ */
329
+ readonly registration?: ClientRegistration;
330
+ /** Catching-up units in registration order; the rest of the list is live. */
331
+ readonly catchingUp: readonly CatchingUpUnit[];
262
332
  /** When this client's last sync round finished, successfully or not. */
263
333
  readonly lastRoundAtMs?: number;
264
334
  /** Code of the last round when it failed; absent after a successful round. */
@@ -277,23 +347,42 @@ export interface ClientRecordWriteOptions {
277
347
  }
278
348
  /** The round-state fields of a stored `sync_clients` row. */
279
349
  export declare function clientRoundState(lastRoundAtMs: number | null, lastErrorCode: string | null, consecutiveFailures: number): Pick<ClientRecord, 'lastRoundAtMs' | 'lastErrorCode' | 'consecutiveFailures'>;
280
- export interface CommitWindowQuery {
281
- readonly table: string;
350
+ /** One unit of the §4.5 scan set. */
351
+ export interface LiveScanUnit {
352
+ /** The unit's scope map; its first variable (keys sorted) is its index key. */
353
+ readonly scopes: UnitScopes;
354
+ /** Exclusive lower bound: `R`, the unit's cursor `P`, or its pin. */
355
+ readonly afterSeq: number;
282
356
  /**
283
- * Effective scopes (§3.2): a change matches iff, for every key, its
284
- * stored value is in the list. Implementations MUST select candidates
285
- * via the inverted scope index, never by scanning the log.
357
+ * The unit's active (unit, table) pairs: covered table → effective scopes
358
+ * (§3.2). A change of table `t` matches iff its stored scopes satisfy the
359
+ * pair for `t` and its commit lies above `afterSeq`.
286
360
  */
287
- readonly scopeFilter: ScopeMap;
288
- /** Window `afterSeq < commitSeq <= throughSeq`, oldest first (§4.5). */
289
- readonly afterSeq: number;
361
+ readonly tables: ReadonlyMap<string, ScopeMap>;
362
+ }
363
+ export interface LiveWindowQuery {
364
+ readonly units: readonly LiveScanUnit[];
365
+ /** `maxCommitSeq` read at the start of the pull. */
290
366
  readonly throughSeq: number;
291
- /** Stop after accumulating at least this many matching changes. */
367
+ /** The `limitCommits` budget: stop after the commit that reaches it. */
292
368
  readonly limitChanges: number;
293
369
  }
370
+ /** The commits of one live section (§4.5). */
371
+ export interface LiveWindow {
372
+ /** Oldest first, each with its matching changes in change order. */
373
+ readonly commits: readonly StoredCommit[];
374
+ /**
375
+ * `T`: `query.throughSeq`, or the last delivered `commitSeq` when the
376
+ * budget cut the section.
377
+ */
378
+ readonly throughSeq: number;
379
+ }
294
380
  export interface RowScanQuery {
295
381
  readonly table: string;
296
- /** Same matching rule as `CommitWindowQuery.scopeFilter`, over rows. */
382
+ /**
383
+ * Effective scopes (§3.2): a row matches iff, for every key, its stored
384
+ * value is in the list. Candidates come from the inverted row-scope index.
385
+ */
297
386
  readonly scopeFilter: ScopeMap;
298
387
  /** Resume after this rowId (exclusive); `null` = start of table. */
299
388
  readonly afterRowId: string | null;
@@ -373,6 +462,13 @@ export interface RowListQuery {
373
462
  readonly afterRowId: string | null;
374
463
  readonly limit: number;
375
464
  }
465
+ /** One §6.3.2 watermark row. */
466
+ export interface PushWatermark {
467
+ readonly clientId: string;
468
+ readonly outboxId: string;
469
+ /** `W`: results of this outbox below it are deleted. */
470
+ readonly throughSeq: number;
471
+ }
376
472
  /** A stored push outcome with the client that sent it. */
377
473
  export interface ClientPushResult {
378
474
  readonly clientId: string;
@@ -453,17 +549,17 @@ export interface StorageTransaction {
453
549
  readonly rowIds: readonly string[];
454
550
  }[]): Promise<void>;
455
551
  /**
456
- * §5 delete-precedence tombstone read: the `commit_seq` of the newest
457
- * applied delete of this row still within the pruning horizon, or
458
- * `undefined` when no tombstone exists. Consulted only when an upsert's
459
- * stored row is absent. Required: in-tree adapters implement it on the
460
- * transaction's own connection with read-your-own-writes semantics.
552
+ * §5 delete-precedence tombstone read: the newest applied delete of this
553
+ * row still within the pruning horizon, or `undefined` when no tombstone
554
+ * exists. Consulted only when an upsert's stored row is absent. Required:
555
+ * in-tree adapters implement it on the transaction's own connection with
556
+ * read-your-own-writes semantics.
461
557
  */
462
- getTombstoneSeq(table: string, rowId: string): Promise<number | undefined>;
558
+ getTombstone(table: string, rowId: string): Promise<Tombstone | undefined>;
463
559
  /**
464
- * Remove the row's tombstone because the row was recreated in this
465
- * transaction (§5: an explicit insert recreates). Called on every insert
466
- * over an absent row; a no-op when no tombstone exists.
560
+ * Remove the row's tombstone because the row is live again in this
561
+ * transaction: an insert over its tombstone (§6.2) or a §2.2 scope move.
562
+ * A no-op when no tombstone exists.
467
563
  */
468
564
  clearTombstone(table: string, rowId: string): Promise<void>;
469
565
  /**
@@ -508,11 +604,18 @@ export interface StorageTransaction {
508
604
  * are built; a storage with per-statement network cost folds that read-ahead
509
605
  * into the admission read and answers the following `getRow` calls from it.
510
606
  * Missing support fails closed before an app-row mutation.
607
+ *
608
+ * `outbox`, passed with the first commit of a request that carries an
609
+ * `outboxId`, settles the client's results stored before wire version 4
610
+ * (§9) and runs §6.3.2 steps 1 and 2 under the same lock, before the read
611
+ * of `persisted`. Those writes survive `commitRejectedPushResult`; the
612
+ * caller commits this transaction whatever the commit's outcome, so the
613
+ * settlement runs exactly once per request.
511
614
  */
512
615
  preparePushApply(clientId: string, clientCommitId: string, runningSchemaVersion: number, targets?: readonly {
513
616
  readonly table: string;
514
617
  readonly rowIds: readonly string[];
515
- }[]): Promise<PreparedPushApply>;
618
+ }[], outbox?: OutboxSettlement): Promise<PreparedPushApply>;
516
619
  /**
517
620
  * Rejection finalization while the push-apply serialization lock is still
518
621
  * held: discard every candidate write, persist the rejected idempotency
@@ -521,7 +624,7 @@ export interface StorageTransaction {
521
624
  * push so a concurrent duplicate cannot rerun operations, validators, or
522
625
  * merges.
523
626
  */
524
- commitRejectedPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<StoredPushResult>;
627
+ commitRejectedPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<StoredPushResult>;
525
628
  upsertRow(table: string, row: StoredRow, context?: {
526
629
  readonly opIndex: number;
527
630
  }): Promise<void>;
@@ -536,9 +639,11 @@ export interface StorageTransaction {
536
639
  enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
537
640
  /**
538
641
  * Persist an idempotency outcome only when the key is still absent. The
539
- * first writer wins; callers read the canonical value after commit.
642
+ * first writer wins; callers read the canonical value after commit. A
643
+ * result without `sequence` (no `outboxId`, §6.10, §12.3) is never deleted
644
+ * by a watermark.
540
645
  */
541
- putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
646
+ putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<void>;
542
647
  /**
543
648
  * Advance this partition's checkpoint only while `owner_epoch` still
544
649
  * matches, so the owner-epoch CAS rides inside the caller's transaction.
@@ -595,7 +700,10 @@ export interface ServerStorage {
595
700
  * back without a write, so a request that only reads takes no write lock.
596
701
  */
597
702
  touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
598
- /** Rotate log continuity after restore and discard stale cursor records. */
703
+ /**
704
+ * Rotate log continuity after restore and delete the partition's client
705
+ * records. Watermark rows stay (§6.3.2).
706
+ */
599
707
  rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
600
708
  /** Registry entries ordered by partition for maintenance loops. */
601
709
  listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
@@ -695,22 +803,25 @@ export interface ServerStorage {
695
803
  /** Delete a bounded set of aged terminal rows. Never deletes active work. */
696
804
  pruneReactions?(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
697
805
  /**
698
- * Matching commits in the window, oldest first, each carrying only its
699
- * matching changes for `table`. Stops once accumulated matching changes
700
- * reach `limitChanges` or the window is exhausted.
806
+ * The §4.5 live section: every commit in `(min afterSeq, throughSeq]`
807
+ * carrying a change that matches a unit of the scan set, oldest first,
808
+ * each with its matching changes once, in change order, across tables.
809
+ * Stops after the commit whose matching changes reach `limitChanges`
810
+ * (never splitting a commit). Candidates come from the change-scope key
811
+ * index, one index range per distinct unit key, never from a log scan.
701
812
  */
702
- readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
813
+ readLiveWindow(partition: string, query: LiveWindowQuery): Promise<LiveWindow>;
703
814
  /**
704
- * Newest commitSeq whose change to `query.table` carries a value of the
705
- * filter's first variable (keys sorted) in the inverted change-scope index:
706
- * the `readCommitWindow` candidate rule, so no change a window read would
707
- * deliver for this filter sits above it. 0 when the index holds none (never
708
- * written, or pruned). The §4.7 sqlite-lane bootstrap pin reads it; it MUST
709
- * be an index lookup per value, independent of the table's history.
815
+ * Newest commitSeq whose change to `query.table` carries the unit's value
816
+ * of its first variable (keys sorted): the `readLiveWindow` candidate rule,
817
+ * so no change the unit would receive for the table sits above it. 0 when
818
+ * the index holds none (never written, or pruned). The §4.7 sqlite-lane
819
+ * scope pin reads it; it MUST be one index lookup, independent of the
820
+ * table's history.
710
821
  */
711
822
  latestScopedChangeSeq(partition: string, query: {
712
823
  readonly table: string;
713
- readonly scopeFilter: ScopeMap;
824
+ readonly scopes: UnitScopes;
714
825
  }): Promise<number>;
715
826
  /** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
716
827
  scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
@@ -741,10 +852,13 @@ export interface ServerStorage {
741
852
  scanRowsByIndex?(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
742
853
  getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
743
854
  /**
744
- * Write the record for a completed round. The round-state fields reset: the
745
- * stored last round is a success at `updatedAtMs` with no failures — unless
746
- * `keepRoundOutcome` is set, which leaves the reported code and streak in
747
- * place (the round carried a `ROUND_FAILURE` report, §1.5/§4.5).
855
+ * Write the record for a completed round (§4.5). A record without
856
+ * `registration` keeps the stored list and digest. The round-state fields
857
+ * reset: the stored last round is a success at `lastRoundAtMs` (default
858
+ * `updatedAtMs`) with no failures, unless `keepRoundOutcome` is set, which
859
+ * leaves the reported code and streak in place (the round carried a
860
+ * `ROUND_FAILURE` report, §1.5/§4.5). An `unregistered` answer rewrites the
861
+ * stored record with only `lastRoundAtMs` moved.
748
862
  */
749
863
  putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
750
864
  /**
@@ -755,15 +869,17 @@ export interface ServerStorage {
755
869
  */
756
870
  recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
757
871
  /**
758
- * Atomically advance an existing record's cursor and activity timestamp.
759
- * Preserve registration fields; require matching actor and current log epoch.
760
- * Missing records and mismatched identities are unchanged (§8.2).
872
+ * §8.2 ack: atomically raise an existing record's cursor to `cursor`,
873
+ * capped at the lowest non-negative cursor of its catching-up units, and
874
+ * its activity timestamp, both monotonically. Every other field stays;
875
+ * requires the matching actor and the current log epoch. A missing record
876
+ * or a mismatched identity is unchanged.
761
877
  */
762
878
  advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
763
- /** Advance an existing client's ACK cursor and timestamp atomically,
764
- * preserving actor, wire version, and subscriptions. Missing records stay absent. */
765
- updateClientCursor(partition: string, clientId: string, cursor: number, updatedAtMs: number): Promise<void>;
766
- /** Minimum cursor with updatedAtMs >= cutoff; null when none are active. */
879
+ /**
880
+ * Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
881
+ * none are active. A bootstrapping client (cursor < 0) holds no cursor.
882
+ */
767
883
  getActiveClientCursorFloor(partition: string, cutoffMs: number): Promise<number | null>;
768
884
  /** Cursor records for client listings and administrative counts. */
769
885
  listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
@@ -791,9 +907,11 @@ export interface ServerStorage {
791
907
  * `eraseScopeValueHistory`: under the partition write lock, removes up to
792
908
  * `limit` upsert change records of `table` at or below `throughSeq` whose
793
909
  * scopes bind `variable` to `value`, then up to `limit` change scope index
794
- * entries of that binding whose commit holds no such change any more.
910
+ * entries of that binding whose commit holds no such change any more,
911
+ * then strips `serverRow` from up to `limit` stored conflict results of
912
+ * `table` whose conflict authorization scopes bind `variable` to `value`.
795
913
  * Delete change records stay: clients behind the erasure still need them.
796
- * Returns the number of records removed.
914
+ * Returns the number of records removed or stripped.
797
915
  */
798
916
  listScopeValueRows?(partition: string, query: ScopeValueQuery): Promise<string[]>;
799
917
  eraseScopeValueHistory?(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
@@ -804,7 +922,7 @@ export interface ServerStorage {
804
922
  * calls them.
805
923
  *
806
924
  * `listClientRecords`: every stored client record for the partition
807
- * (cursor, last-seen, subscription list) — the "who's connected" view.
925
+ * (cursor, last-seen, registration list): the "who's connected" view.
808
926
  * `listCommitMetadata`: the commit log without payloads (metadata +
809
927
  * touched tables), the newest-oriented window an operator inspects.
810
928
  * `scopeActivity`: the recent commits touching one scope key, via the
@@ -819,6 +937,9 @@ export interface ServerStorage {
819
937
  * `listPushResults`: every stored idempotency outcome for one
820
938
  * clientCommitId across the partition's clients, scanning the retained
821
939
  * outcomes without a dedicated index.
940
+ * `listPushWatermarks`: the §6.3.2 watermark rows of every client whose
941
+ * retained commit log carries the clientCommitId; a commit whose result
942
+ * the watermark deleted reads as "expired below sequence `throughSeq`".
822
943
  * `listPartitions`: the partition-only compatibility view of
823
944
  * `listPartitionRegistry`, sorted.
824
945
  */
@@ -830,6 +951,7 @@ export interface ServerStorage {
830
951
  listRows?(partition: string, query: RowListQuery): Promise<StoredRow[]>;
831
952
  countRows?(partition: string, table: string): Promise<number>;
832
953
  listPushResults?(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
954
+ listPushWatermarks?(partition: string, clientCommitId: string): Promise<PushWatermark[]>;
833
955
  listPartitions(): Promise<string[]>;
834
956
  }
835
957
  /** One scope binding of one table, budgeted (§4.6.1). */
package/dist/storage.js CHANGED
@@ -64,6 +64,21 @@ export function rowsLiveAfterDelete(changes) {
64
64
  }
65
65
  return live;
66
66
  }
67
+ /**
68
+ * The delete floor a commit raises the partition's to (§2.2): the highest
69
+ * version of a delete that leaves a tombstone, `0` without one.
70
+ */
71
+ export function commitDeleteFloor(changes) {
72
+ const live = rowsLiveAfterDelete(changes);
73
+ let floor = 0;
74
+ for (const change of changes) {
75
+ if (change.op === 'delete' &&
76
+ !live.has(`${change.table}\u0000${change.rowId}`)) {
77
+ floor = Math.max(floor, change.rowVersion);
78
+ }
79
+ }
80
+ return floor;
81
+ }
67
82
  /** The round-state fields of a stored `sync_clients` row. */
68
83
  export function clientRoundState(lastRoundAtMs, lastErrorCode, consecutiveFailures) {
69
84
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.58.0",
3
+ "version": "0.60.0",
4
4
  "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
68
68
  "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
69
69
  },
70
70
  "dependencies": {
71
- "@syncular/core": "0.58.0"
71
+ "@syncular/core": "0.60.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"