@optimystic/db-core 1.5.0 → 1.6.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 (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,308 +1,308 @@
1
- /**
2
- * Reactivity — parent checkpoint summaries (`docs/reactivity.md` §Parent checkpoint summaries).
3
- *
4
- * A `W`-revision replay buffer is too shallow for a phone asleep overnight. To extend recoverable range
5
- * without ballooning replay memory, every parent forwarder cohort (and the tail cohort) maintains a
6
- * rolling {@link CheckpointSummary} over the `W_checkpoint` revisions sitting **immediately below** the
7
- * replay ring's low edge — the two windows *stack*, so a single round trip recovers `W + W_checkpoint`
8
- * revisions (the authoritative stacked semantics, `docs/reactivity.md` §Replay window). As revisions
9
- * retire from the ring, the forwarder feeds them to {@link RollingCheckpoint.retire}; the checkpoint
10
- * rolls its `toRevision` forward and trims its low edge to span `W_checkpoint`.
11
- *
12
- * The checkpoint is a **hint summary, not a chain replacement**. Two design questions the ticket asks to
13
- * resolve, decided here:
14
- *
15
- * - **`mergedDigest` semantics (resolved → system-level deterministic fold, per-collection override).**
16
- * `NotificationV1.digest` carries the commit-vote signed payload `utf8(commitHash + ":approve")` —
17
- * the exact bytes the commit threshold signature was computed over (see
18
- * `packages/db-core/src/reactivity/notification.ts`). It is per-revision deterministic and identical
19
- * across cohort members, so the default `mergedDigest` — a deterministic running fold over the
20
- * per-revision digests in revision order ({@link defaultDigestFold}) — converges under gossip and the
21
- * application can compare it against its own expectation. A collection MAY override the fold
22
- * ({@link RollingCheckpointInit.fold}, e.g. a KV collection folding changed-key sets). The merged
23
- * digest is **not** cryptographically verified — it is a hint; the cryptographic anchor is the
24
- * bracketing endpoints (below).
25
- *
26
- * - **`mergedDelta` vs `delta_max` (resolved → omit when oversize, never split).** The per-revision
27
- * deltas are coalesced ({@link RollingCheckpointInit.coalesceDeltas}, default concatenation) only when
28
- * the coalesced result fits within `delta_max`; otherwise `mergedDelta` is omitted entirely and the
29
- * subscriber relies on `mergedDigest` + the resume's `recentEntries`, or falls back to a chain read. No
30
- * multi-frame splitting — a checkpoint is a bounded hint.
31
- *
32
- * The **bracketing endpoints** are carried as the two full endpoint {@link NotificationV1}s
33
- * ({@link CheckpointSummary.bracketingEntries}). A bare signature is not independently verifiable — to
34
- * verify an endpoint is a real committed revision a subscriber needs the signed payload (the commit
35
- * digest) and the signers, which the full notification carries. {@link verifyCheckpointEndpoints} runs
36
- * the standard {@link NotificationVerifier} over both endpoints (proving they are real committed
37
- * revisions) and checks their revisions equal `fromRevision`/`toRevision`; a forged endpoint is rejected.
38
- */
39
-
40
- import { createRingHash } from "../cohort-topic/ring-hash.js";
41
- import { bytesToB64url, b64urlToBytes } from "../cohort-topic/wire/codec.js";
42
- import type { IRingHash } from "../cohort-topic/ports.js";
43
- import type { VerifyResult } from "../cohort-topic/membership/verifier.js";
44
- import { W_CHECKPOINT_DEFAULT } from "./config.js";
45
- import type { RevisionEntry } from "./replay-buffer.js";
46
- import type { NotificationVerifier } from "./verify.js";
47
- import { asObject, b64urlField, failWire, reqIntInRange, reqString } from "./wire-validate.js";
48
- import { validateNotificationV1, type NotificationV1 } from "./wire.js";
49
-
50
- /**
51
- * A parent checkpoint summary over `[fromRevision, toRevision]` (`docs/reactivity.md`
52
- * §Parent checkpoint summaries). All byte fields base64url; `bracketingEntries` is exactly the two
53
- * endpoint notifications, the verifiable anchor.
54
- */
55
- export interface CheckpointSummary {
56
- /** Collection id, base64url. */
57
- readonly collectionId: string;
58
- /** Inclusive low edge of the summarized range. */
59
- readonly fromRevision: number;
60
- /** Inclusive high edge of the summarized range (`toRevision - fromRevision + 1 ≈ W_checkpoint`). */
61
- readonly toRevision: number;
62
- /** Deterministic fold of the per-revision commit digests across the range, base64url (a hint). */
63
- readonly mergedDigest: string;
64
- /** Optional coalesced delta, base64url; omitted when the coalesced size exceeds `delta_max`. */
65
- readonly mergedDelta?: string;
66
- /** The two endpoint notifications (at `fromRevision` and `toRevision`) — the verifiable proof. */
67
- readonly bracketingEntries: readonly [NotificationV1, NotificationV1];
68
- }
69
-
70
- /** A fold of per-revision commit digests into one summary digest (`docs/reactivity.md` `mergedDigest`). */
71
- export type DigestFold = (perRevisionDigests: readonly Uint8Array[]) => Uint8Array;
72
-
73
- /** Coalesce per-revision deltas into one bounded delta (`docs/reactivity.md` `mergedDelta`). */
74
- export type DeltaCoalesce = (perRevisionDeltas: readonly Uint8Array[]) => Uint8Array;
75
-
76
- /**
77
- * The default system-level `mergedDigest` fold: a deterministic running hash
78
- * `acc₀ = H(∅); accᵢ = H(accᵢ₋₁ ‖ digestᵢ)` over the per-revision commit digests in revision order.
79
- * Order-dependent and reproducible, so every cohort member folds to identical bytes (gossip converges).
80
- */
81
- export function defaultDigestFold(hash: IRingHash = createRingHash()): DigestFold {
82
- return (digests: readonly Uint8Array[]): Uint8Array => {
83
- let acc = hash.H(new Uint8Array(0));
84
- for (const digest of digests) {
85
- const input = new Uint8Array(acc.length + digest.length);
86
- input.set(acc, 0);
87
- input.set(digest, acc.length);
88
- acc = hash.H(input);
89
- }
90
- return acc;
91
- };
92
- }
93
-
94
- /** The default delta coalescer: ordered concatenation of the per-revision delta bytes. */
95
- export function defaultDeltaCoalesce(deltas: readonly Uint8Array[]): Uint8Array {
96
- const total = deltas.reduce((n, d) => n + d.length, 0);
97
- const out = new Uint8Array(total);
98
- let offset = 0;
99
- for (const d of deltas) {
100
- out.set(d, offset);
101
- offset += d.length;
102
- }
103
- return out;
104
- }
105
-
106
- /** The fold/coalesce knobs shared by the rolling checkpoint and the rotation handoff. */
107
- export interface CheckpointFoldOptions {
108
- /** Collection id the summarized entries belong to, base64url. */
109
- readonly collectionId: string;
110
- /** `mergedDigest` fold over the per-revision commit digests. */
111
- readonly fold: DigestFold;
112
- /** `mergedDelta` coalescer over the per-revision deltas. */
113
- readonly coalesceDeltas: DeltaCoalesce;
114
- /** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
115
- readonly deltaMaxBytes: number;
116
- }
117
-
118
- /**
119
- * Coalesce the per-revision deltas of `ordered`, returning the base64url result only when it fits within
120
- * `deltaMaxBytes`. Omitted (`undefined`) when no entry carries a delta, when `deltaMaxBytes <= 0`, or when
121
- * the coalesced size would exceed `deltaMaxBytes` (the resolved omit-when-oversize policy — never split).
122
- */
123
- export function coalesceMergedDelta(ordered: readonly RevisionEntry[], coalesceDeltas: DeltaCoalesce, deltaMaxBytes: number): string | undefined {
124
- if (deltaMaxBytes <= 0) {
125
- return undefined;
126
- }
127
- const deltas: Uint8Array[] = [];
128
- for (const e of ordered) {
129
- if (e.payload.delta !== undefined) {
130
- deltas.push(b64urlToBytes(e.payload.delta));
131
- }
132
- }
133
- if (deltas.length === 0) {
134
- return undefined;
135
- }
136
- const coalesced = coalesceDeltas(deltas);
137
- return coalesced.length > deltaMaxBytes ? undefined : bytesToB64url(coalesced);
138
- }
139
-
140
- /**
141
- * Build a {@link CheckpointSummary} over `orderedEntries` (ascending by revision) — the shared fold the
142
- * rolling checkpoint and the rotation buffer-to-checkpoint handoff both use. Returns `undefined` for an
143
- * empty range. The two endpoints are carried as the full notifications (the verifiable anchor); the merged
144
- * digest is the deterministic fold over the per-revision commit digests; the coalesced delta is included
145
- * only when it fits within `deltaMaxBytes`.
146
- */
147
- export function buildCheckpointSummary(orderedEntries: readonly RevisionEntry[], opts: CheckpointFoldOptions): CheckpointSummary | undefined {
148
- if (orderedEntries.length === 0) {
149
- return undefined;
150
- }
151
- const digests = orderedEntries.map((e) => b64urlToBytes(e.payload.digest));
152
- const mergedDigest = bytesToB64url(opts.fold(digests));
153
- const first = orderedEntries[0]!.payload;
154
- const last = orderedEntries[orderedEntries.length - 1]!.payload;
155
- const summary: CheckpointSummary = {
156
- collectionId: opts.collectionId,
157
- fromRevision: first.revision,
158
- toRevision: last.revision,
159
- mergedDigest,
160
- bracketingEntries: [first, last],
161
- };
162
- const mergedDelta = coalesceMergedDelta(orderedEntries, opts.coalesceDeltas, opts.deltaMaxBytes);
163
- return mergedDelta !== undefined ? { ...summary, mergedDelta } : summary;
164
- }
165
-
166
- /** Construction inputs for a {@link RollingCheckpoint}. */
167
- export interface RollingCheckpointInit {
168
- /** Collection id, base64url (must match the entries retired into it). */
169
- readonly collectionId: string;
170
- /** Checkpoint span `W_checkpoint` (default {@link W_CHECKPOINT_DEFAULT}). */
171
- readonly span?: number;
172
- /** Ring hash for the default digest fold. Default db-core SHA-256. */
173
- readonly hash?: IRingHash;
174
- /** `mergedDigest` fold (default {@link defaultDigestFold} over the injected hash). */
175
- readonly fold?: DigestFold;
176
- /** `mergedDelta` coalescer (default {@link defaultDeltaCoalesce}). */
177
- readonly coalesceDeltas?: DeltaCoalesce;
178
- /** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
179
- readonly deltaMaxBytes?: number;
180
- }
181
-
182
- /**
183
- * The rolling `W_checkpoint`-span parent checkpoint. Retains up to `span` retired {@link RevisionEntry}s
184
- * (the documented per-cohort checkpoint memory cost) so it can fold a real `mergedDigest`, coalesce a
185
- * `mergedDelta`, and carry the two endpoint notifications. It always covers the `span` revisions just
186
- * below the replay ring's low edge.
187
- */
188
- export class RollingCheckpoint {
189
- readonly collectionId: string;
190
- readonly span: number;
191
- private readonly hash: IRingHash;
192
- private readonly fold: DigestFold;
193
- private readonly coalesceDeltas: DeltaCoalesce;
194
- private readonly deltaMaxBytes: number;
195
- /** revision → retired entry; trimmed to the highest `span` revisions. */
196
- private readonly byRevision = new Map<number, RevisionEntry>();
197
-
198
- constructor(init: RollingCheckpointInit) {
199
- const span = init.span ?? W_CHECKPOINT_DEFAULT;
200
- if (!Number.isInteger(span) || span < 1) {
201
- throw new RangeError(`reactivity checkpoint: span must be an integer >= 1, got ${span}`);
202
- }
203
- this.collectionId = init.collectionId;
204
- this.span = span;
205
- this.hash = init.hash ?? createRingHash();
206
- this.fold = init.fold ?? defaultDigestFold(this.hash);
207
- this.coalesceDeltas = init.coalesceDeltas ?? defaultDeltaCoalesce;
208
- this.deltaMaxBytes = init.deltaMaxBytes ?? 0;
209
- }
210
-
211
- /** Number of retired revisions currently summarized. */
212
- get size(): number {
213
- return this.byRevision.size;
214
- }
215
-
216
- /** Lowest summarized revision, or `undefined` when empty. */
217
- get fromRevision(): number | undefined {
218
- return this.size === 0 ? undefined : Math.min(...this.byRevision.keys());
219
- }
220
-
221
- /** Highest summarized revision, or `undefined` when empty. */
222
- get toRevision(): number | undefined {
223
- return this.size === 0 ? undefined : Math.max(...this.byRevision.keys());
224
- }
225
-
226
- /** True iff `revision` is within the checkpoint's covered range. */
227
- covers(revision: number): boolean {
228
- const from = this.fromRevision;
229
- const to = this.toRevision;
230
- return from !== undefined && to !== undefined && revision >= from && revision <= to;
231
- }
232
-
233
- /**
234
- * Fold one revision retired from the replay ring into the checkpoint. Entries arrive as the ring
235
- * evicts its low edge; the checkpoint trims to its highest `span` revisions so it tracks the window
236
- * immediately below the ring. A retransmit at an already-summarized revision replaces in place.
237
- */
238
- retire(entry: RevisionEntry): void {
239
- if (entry.payload.collectionId !== this.collectionId) {
240
- return; // an entry for a different collection is not ours to summarize
241
- }
242
- this.byRevision.set(entry.revision, entry);
243
- while (this.byRevision.size > this.span) {
244
- this.byRevision.delete(Math.min(...this.byRevision.keys()));
245
- }
246
- }
247
-
248
- /** The retired entries, ascending by revision. */
249
- private orderedEntries(): RevisionEntry[] {
250
- return [...this.byRevision.values()].sort((a, b) => a.revision - b.revision);
251
- }
252
-
253
- /** The fold/coalesce knobs this checkpoint applies — reused by the rotation handoff for an identical fold. */
254
- get foldOptions(): CheckpointFoldOptions {
255
- return { collectionId: this.collectionId, fold: this.fold, coalesceDeltas: this.coalesceDeltas, deltaMaxBytes: this.deltaMaxBytes };
256
- }
257
-
258
- /** Build the {@link CheckpointSummary} over the currently-summarized range, or `undefined` if empty. */
259
- summary(): CheckpointSummary | undefined {
260
- return buildCheckpointSummary(this.orderedEntries(), this.foldOptions);
261
- }
262
- }
263
-
264
- /**
265
- * Verify a checkpoint's bracketing endpoints are real committed revisions: run the standard
266
- * {@link NotificationVerifier} over both endpoint notifications and confirm their revisions equal
267
- * `fromRevision`/`toRevision` and their collection matches. Returns `"verified"` only if **both**
268
- * endpoints verify and align; a forged or tampered endpoint yields `"untrusted"`.
269
- */
270
- export async function verifyCheckpointEndpoints(summary: CheckpointSummary, verifier: NotificationVerifier): Promise<VerifyResult> {
271
- const [from, to] = summary.bracketingEntries;
272
- if (
273
- from.collectionId !== summary.collectionId ||
274
- to.collectionId !== summary.collectionId ||
275
- from.revision !== summary.fromRevision ||
276
- to.revision !== summary.toRevision
277
- ) {
278
- return "untrusted";
279
- }
280
- const [fromVerdict, toVerdict] = await Promise.all([verifier.verify(from), verifier.verify(to)]);
281
- return fromVerdict === "verified" && toVerdict === "verified" ? "verified" : "untrusted";
282
- }
283
-
284
- /**
285
- * Narrow an already-parsed value to {@link CheckpointSummary}, throwing on any defect. Used by the resume
286
- * codec to validate a checkpoint embedded in a `checkpoint_window` reply. The two `bracketingEntries` are
287
- * validated as full {@link NotificationV1}s (the verifiable anchor); `mergedDelta` is optional.
288
- */
289
- export function validateCheckpointSummary(value: unknown, what = "CheckpointSummary"): CheckpointSummary {
290
- const obj = asObject(value, what);
291
- const fromRevision = reqIntInRange(obj, "fromRevision", what, 0);
292
- const toRevision = reqIntInRange(obj, "toRevision", what, fromRevision);
293
- const bracketing = obj["bracketingEntries"];
294
- if (!Array.isArray(bracketing) || bracketing.length !== 2) {
295
- failWire(`${what}: field "bracketingEntries" must be a length-2 array`);
296
- }
297
- const summary: CheckpointSummary = {
298
- collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
299
- fromRevision,
300
- toRevision,
301
- mergedDigest: b64urlField(reqString(obj, "mergedDigest", what), "mergedDigest", what),
302
- bracketingEntries: [validateNotificationV1(bracketing[0]), validateNotificationV1(bracketing[1])],
303
- };
304
- if (obj["mergedDelta"] !== undefined) {
305
- return { ...summary, mergedDelta: b64urlField(reqString(obj, "mergedDelta", what), "mergedDelta", what) };
306
- }
307
- return summary;
308
- }
1
+ /**
2
+ * Reactivity — parent checkpoint summaries (`docs/reactivity.md` §Parent checkpoint summaries).
3
+ *
4
+ * A `W`-revision replay buffer is too shallow for a phone asleep overnight. To extend recoverable range
5
+ * without ballooning replay memory, every parent forwarder cohort (and the tail cohort) maintains a
6
+ * rolling {@link CheckpointSummary} over the `W_checkpoint` revisions sitting **immediately below** the
7
+ * replay ring's low edge — the two windows *stack*, so a single round trip recovers `W + W_checkpoint`
8
+ * revisions (the authoritative stacked semantics, `docs/reactivity.md` §Replay window). As revisions
9
+ * retire from the ring, the forwarder feeds them to {@link RollingCheckpoint.retire}; the checkpoint
10
+ * rolls its `toRevision` forward and trims its low edge to span `W_checkpoint`.
11
+ *
12
+ * The checkpoint is a **hint summary, not a chain replacement**. Two design questions the ticket asks to
13
+ * resolve, decided here:
14
+ *
15
+ * - **`mergedDigest` semantics (resolved → system-level deterministic fold, per-collection override).**
16
+ * `NotificationV1.digest` carries the commit-vote signed payload `utf8(commitHash + ":approve")` —
17
+ * the exact bytes the commit threshold signature was computed over (see
18
+ * `packages/db-core/src/reactivity/notification.ts`). It is per-revision deterministic and identical
19
+ * across cohort members, so the default `mergedDigest` — a deterministic running fold over the
20
+ * per-revision digests in revision order ({@link defaultDigestFold}) — converges under gossip and the
21
+ * application can compare it against its own expectation. A collection MAY override the fold
22
+ * ({@link RollingCheckpointInit.fold}, e.g. a KV collection folding changed-key sets). The merged
23
+ * digest is **not** cryptographically verified — it is a hint; the cryptographic anchor is the
24
+ * bracketing endpoints (below).
25
+ *
26
+ * - **`mergedDelta` vs `delta_max` (resolved → omit when oversize, never split).** The per-revision
27
+ * deltas are coalesced ({@link RollingCheckpointInit.coalesceDeltas}, default concatenation) only when
28
+ * the coalesced result fits within `delta_max`; otherwise `mergedDelta` is omitted entirely and the
29
+ * subscriber relies on `mergedDigest` + the resume's `recentEntries`, or falls back to a chain read. No
30
+ * multi-frame splitting — a checkpoint is a bounded hint.
31
+ *
32
+ * The **bracketing endpoints** are carried as the two full endpoint {@link NotificationV1}s
33
+ * ({@link CheckpointSummary.bracketingEntries}). A bare signature is not independently verifiable — to
34
+ * verify an endpoint is a real committed revision a subscriber needs the signed payload (the commit
35
+ * digest) and the signers, which the full notification carries. {@link verifyCheckpointEndpoints} runs
36
+ * the standard {@link NotificationVerifier} over both endpoints (proving they are real committed
37
+ * revisions) and checks their revisions equal `fromRevision`/`toRevision`; a forged endpoint is rejected.
38
+ */
39
+
40
+ import { createRingHash } from "../cohort-topic/ring-hash.js";
41
+ import { bytesToB64url, b64urlToBytes } from "../cohort-topic/wire/codec.js";
42
+ import type { IRingHash } from "../cohort-topic/ports.js";
43
+ import type { VerifyResult } from "../cohort-topic/membership/verifier.js";
44
+ import { W_CHECKPOINT_DEFAULT } from "./config.js";
45
+ import type { RevisionEntry } from "./replay-buffer.js";
46
+ import type { NotificationVerifier } from "./verify.js";
47
+ import { asObject, b64urlField, failWire, reqIntInRange, reqString } from "./wire-validate.js";
48
+ import { validateNotificationV1, type NotificationV1 } from "./wire.js";
49
+
50
+ /**
51
+ * A parent checkpoint summary over `[fromRevision, toRevision]` (`docs/reactivity.md`
52
+ * §Parent checkpoint summaries). All byte fields base64url; `bracketingEntries` is exactly the two
53
+ * endpoint notifications, the verifiable anchor.
54
+ */
55
+ export interface CheckpointSummary {
56
+ /** Collection id, base64url. */
57
+ readonly collectionId: string;
58
+ /** Inclusive low edge of the summarized range. */
59
+ readonly fromRevision: number;
60
+ /** Inclusive high edge of the summarized range (`toRevision - fromRevision + 1 ≈ W_checkpoint`). */
61
+ readonly toRevision: number;
62
+ /** Deterministic fold of the per-revision commit digests across the range, base64url (a hint). */
63
+ readonly mergedDigest: string;
64
+ /** Optional coalesced delta, base64url; omitted when the coalesced size exceeds `delta_max`. */
65
+ readonly mergedDelta?: string;
66
+ /** The two endpoint notifications (at `fromRevision` and `toRevision`) — the verifiable proof. */
67
+ readonly bracketingEntries: readonly [NotificationV1, NotificationV1];
68
+ }
69
+
70
+ /** A fold of per-revision commit digests into one summary digest (`docs/reactivity.md` `mergedDigest`). */
71
+ export type DigestFold = (perRevisionDigests: readonly Uint8Array[]) => Uint8Array;
72
+
73
+ /** Coalesce per-revision deltas into one bounded delta (`docs/reactivity.md` `mergedDelta`). */
74
+ export type DeltaCoalesce = (perRevisionDeltas: readonly Uint8Array[]) => Uint8Array;
75
+
76
+ /**
77
+ * The default system-level `mergedDigest` fold: a deterministic running hash
78
+ * `acc₀ = H(∅); accᵢ = H(accᵢ₋₁ ‖ digestᵢ)` over the per-revision commit digests in revision order.
79
+ * Order-dependent and reproducible, so every cohort member folds to identical bytes (gossip converges).
80
+ */
81
+ export function defaultDigestFold(hash: IRingHash = createRingHash()): DigestFold {
82
+ return (digests: readonly Uint8Array[]): Uint8Array => {
83
+ let acc = hash.H(new Uint8Array(0));
84
+ for (const digest of digests) {
85
+ const input = new Uint8Array(acc.length + digest.length);
86
+ input.set(acc, 0);
87
+ input.set(digest, acc.length);
88
+ acc = hash.H(input);
89
+ }
90
+ return acc;
91
+ };
92
+ }
93
+
94
+ /** The default delta coalescer: ordered concatenation of the per-revision delta bytes. */
95
+ export function defaultDeltaCoalesce(deltas: readonly Uint8Array[]): Uint8Array {
96
+ const total = deltas.reduce((n, d) => n + d.length, 0);
97
+ const out = new Uint8Array(total);
98
+ let offset = 0;
99
+ for (const d of deltas) {
100
+ out.set(d, offset);
101
+ offset += d.length;
102
+ }
103
+ return out;
104
+ }
105
+
106
+ /** The fold/coalesce knobs shared by the rolling checkpoint and the rotation handoff. */
107
+ export interface CheckpointFoldOptions {
108
+ /** Collection id the summarized entries belong to, base64url. */
109
+ readonly collectionId: string;
110
+ /** `mergedDigest` fold over the per-revision commit digests. */
111
+ readonly fold: DigestFold;
112
+ /** `mergedDelta` coalescer over the per-revision deltas. */
113
+ readonly coalesceDeltas: DeltaCoalesce;
114
+ /** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
115
+ readonly deltaMaxBytes: number;
116
+ }
117
+
118
+ /**
119
+ * Coalesce the per-revision deltas of `ordered`, returning the base64url result only when it fits within
120
+ * `deltaMaxBytes`. Omitted (`undefined`) when no entry carries a delta, when `deltaMaxBytes <= 0`, or when
121
+ * the coalesced size would exceed `deltaMaxBytes` (the resolved omit-when-oversize policy — never split).
122
+ */
123
+ export function coalesceMergedDelta(ordered: readonly RevisionEntry[], coalesceDeltas: DeltaCoalesce, deltaMaxBytes: number): string | undefined {
124
+ if (deltaMaxBytes <= 0) {
125
+ return undefined;
126
+ }
127
+ const deltas: Uint8Array[] = [];
128
+ for (const e of ordered) {
129
+ if (e.payload.delta !== undefined) {
130
+ deltas.push(b64urlToBytes(e.payload.delta));
131
+ }
132
+ }
133
+ if (deltas.length === 0) {
134
+ return undefined;
135
+ }
136
+ const coalesced = coalesceDeltas(deltas);
137
+ return coalesced.length > deltaMaxBytes ? undefined : bytesToB64url(coalesced);
138
+ }
139
+
140
+ /**
141
+ * Build a {@link CheckpointSummary} over `orderedEntries` (ascending by revision) — the shared fold the
142
+ * rolling checkpoint and the rotation buffer-to-checkpoint handoff both use. Returns `undefined` for an
143
+ * empty range. The two endpoints are carried as the full notifications (the verifiable anchor); the merged
144
+ * digest is the deterministic fold over the per-revision commit digests; the coalesced delta is included
145
+ * only when it fits within `deltaMaxBytes`.
146
+ */
147
+ export function buildCheckpointSummary(orderedEntries: readonly RevisionEntry[], opts: CheckpointFoldOptions): CheckpointSummary | undefined {
148
+ if (orderedEntries.length === 0) {
149
+ return undefined;
150
+ }
151
+ const digests = orderedEntries.map((e) => b64urlToBytes(e.payload.digest));
152
+ const mergedDigest = bytesToB64url(opts.fold(digests));
153
+ const first = orderedEntries[0]!.payload;
154
+ const last = orderedEntries[orderedEntries.length - 1]!.payload;
155
+ const summary: CheckpointSummary = {
156
+ collectionId: opts.collectionId,
157
+ fromRevision: first.revision,
158
+ toRevision: last.revision,
159
+ mergedDigest,
160
+ bracketingEntries: [first, last],
161
+ };
162
+ const mergedDelta = coalesceMergedDelta(orderedEntries, opts.coalesceDeltas, opts.deltaMaxBytes);
163
+ return mergedDelta !== undefined ? { ...summary, mergedDelta } : summary;
164
+ }
165
+
166
+ /** Construction inputs for a {@link RollingCheckpoint}. */
167
+ export interface RollingCheckpointInit {
168
+ /** Collection id, base64url (must match the entries retired into it). */
169
+ readonly collectionId: string;
170
+ /** Checkpoint span `W_checkpoint` (default {@link W_CHECKPOINT_DEFAULT}). */
171
+ readonly span?: number;
172
+ /** Ring hash for the default digest fold. Default db-core SHA-256. */
173
+ readonly hash?: IRingHash;
174
+ /** `mergedDigest` fold (default {@link defaultDigestFold} over the injected hash). */
175
+ readonly fold?: DigestFold;
176
+ /** `mergedDelta` coalescer (default {@link defaultDeltaCoalesce}). */
177
+ readonly coalesceDeltas?: DeltaCoalesce;
178
+ /** `delta_max`: omit `mergedDelta` when the coalesced size exceeds this. `0` ⇒ never emit a delta. */
179
+ readonly deltaMaxBytes?: number;
180
+ }
181
+
182
+ /**
183
+ * The rolling `W_checkpoint`-span parent checkpoint. Retains up to `span` retired {@link RevisionEntry}s
184
+ * (the documented per-cohort checkpoint memory cost) so it can fold a real `mergedDigest`, coalesce a
185
+ * `mergedDelta`, and carry the two endpoint notifications. It always covers the `span` revisions just
186
+ * below the replay ring's low edge.
187
+ */
188
+ export class RollingCheckpoint {
189
+ readonly collectionId: string;
190
+ readonly span: number;
191
+ private readonly hash: IRingHash;
192
+ private readonly fold: DigestFold;
193
+ private readonly coalesceDeltas: DeltaCoalesce;
194
+ private readonly deltaMaxBytes: number;
195
+ /** revision → retired entry; trimmed to the highest `span` revisions. */
196
+ private readonly byRevision = new Map<number, RevisionEntry>();
197
+
198
+ constructor(init: RollingCheckpointInit) {
199
+ const span = init.span ?? W_CHECKPOINT_DEFAULT;
200
+ if (!Number.isInteger(span) || span < 1) {
201
+ throw new RangeError(`reactivity checkpoint: span must be an integer >= 1, got ${span}`);
202
+ }
203
+ this.collectionId = init.collectionId;
204
+ this.span = span;
205
+ this.hash = init.hash ?? createRingHash();
206
+ this.fold = init.fold ?? defaultDigestFold(this.hash);
207
+ this.coalesceDeltas = init.coalesceDeltas ?? defaultDeltaCoalesce;
208
+ this.deltaMaxBytes = init.deltaMaxBytes ?? 0;
209
+ }
210
+
211
+ /** Number of retired revisions currently summarized. */
212
+ get size(): number {
213
+ return this.byRevision.size;
214
+ }
215
+
216
+ /** Lowest summarized revision, or `undefined` when empty. */
217
+ get fromRevision(): number | undefined {
218
+ return this.size === 0 ? undefined : Math.min(...this.byRevision.keys());
219
+ }
220
+
221
+ /** Highest summarized revision, or `undefined` when empty. */
222
+ get toRevision(): number | undefined {
223
+ return this.size === 0 ? undefined : Math.max(...this.byRevision.keys());
224
+ }
225
+
226
+ /** True iff `revision` is within the checkpoint's covered range. */
227
+ covers(revision: number): boolean {
228
+ const from = this.fromRevision;
229
+ const to = this.toRevision;
230
+ return from !== undefined && to !== undefined && revision >= from && revision <= to;
231
+ }
232
+
233
+ /**
234
+ * Fold one revision retired from the replay ring into the checkpoint. Entries arrive as the ring
235
+ * evicts its low edge; the checkpoint trims to its highest `span` revisions so it tracks the window
236
+ * immediately below the ring. A retransmit at an already-summarized revision replaces in place.
237
+ */
238
+ retire(entry: RevisionEntry): void {
239
+ if (entry.payload.collectionId !== this.collectionId) {
240
+ return; // an entry for a different collection is not ours to summarize
241
+ }
242
+ this.byRevision.set(entry.revision, entry);
243
+ while (this.byRevision.size > this.span) {
244
+ this.byRevision.delete(Math.min(...this.byRevision.keys()));
245
+ }
246
+ }
247
+
248
+ /** The retired entries, ascending by revision. */
249
+ private orderedEntries(): RevisionEntry[] {
250
+ return [...this.byRevision.values()].sort((a, b) => a.revision - b.revision);
251
+ }
252
+
253
+ /** The fold/coalesce knobs this checkpoint applies — reused by the rotation handoff for an identical fold. */
254
+ get foldOptions(): CheckpointFoldOptions {
255
+ return { collectionId: this.collectionId, fold: this.fold, coalesceDeltas: this.coalesceDeltas, deltaMaxBytes: this.deltaMaxBytes };
256
+ }
257
+
258
+ /** Build the {@link CheckpointSummary} over the currently-summarized range, or `undefined` if empty. */
259
+ summary(): CheckpointSummary | undefined {
260
+ return buildCheckpointSummary(this.orderedEntries(), this.foldOptions);
261
+ }
262
+ }
263
+
264
+ /**
265
+ * Verify a checkpoint's bracketing endpoints are real committed revisions: run the standard
266
+ * {@link NotificationVerifier} over both endpoint notifications and confirm their revisions equal
267
+ * `fromRevision`/`toRevision` and their collection matches. Returns `"verified"` only if **both**
268
+ * endpoints verify and align; a forged or tampered endpoint yields `"untrusted"`.
269
+ */
270
+ export async function verifyCheckpointEndpoints(summary: CheckpointSummary, verifier: NotificationVerifier): Promise<VerifyResult> {
271
+ const [from, to] = summary.bracketingEntries;
272
+ if (
273
+ from.collectionId !== summary.collectionId ||
274
+ to.collectionId !== summary.collectionId ||
275
+ from.revision !== summary.fromRevision ||
276
+ to.revision !== summary.toRevision
277
+ ) {
278
+ return "untrusted";
279
+ }
280
+ const [fromVerdict, toVerdict] = await Promise.all([verifier.verify(from), verifier.verify(to)]);
281
+ return fromVerdict === "verified" && toVerdict === "verified" ? "verified" : "untrusted";
282
+ }
283
+
284
+ /**
285
+ * Narrow an already-parsed value to {@link CheckpointSummary}, throwing on any defect. Used by the resume
286
+ * codec to validate a checkpoint embedded in a `checkpoint_window` reply. The two `bracketingEntries` are
287
+ * validated as full {@link NotificationV1}s (the verifiable anchor); `mergedDelta` is optional.
288
+ */
289
+ export function validateCheckpointSummary(value: unknown, what = "CheckpointSummary"): CheckpointSummary {
290
+ const obj = asObject(value, what);
291
+ const fromRevision = reqIntInRange(obj, "fromRevision", what, 0);
292
+ const toRevision = reqIntInRange(obj, "toRevision", what, fromRevision);
293
+ const bracketing = obj["bracketingEntries"];
294
+ if (!Array.isArray(bracketing) || bracketing.length !== 2) {
295
+ failWire(`${what}: field "bracketingEntries" must be a length-2 array`);
296
+ }
297
+ const summary: CheckpointSummary = {
298
+ collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
299
+ fromRevision,
300
+ toRevision,
301
+ mergedDigest: b64urlField(reqString(obj, "mergedDigest", what), "mergedDigest", what),
302
+ bracketingEntries: [validateNotificationV1(bracketing[0]), validateNotificationV1(bracketing[1])],
303
+ };
304
+ if (obj["mergedDelta"] !== undefined) {
305
+ return { ...summary, mergedDelta: b64urlField(reqString(obj, "mergedDelta", what), "mergedDelta", what) };
306
+ }
307
+ return summary;
308
+ }