@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,233 +1,233 @@
1
- /**
2
- * Cohort-topic substrate — topic-traffic signal.
3
- *
4
- * Transcribed from `docs/cohort-topic.md` §Topic traffic signal. A cohort tracks per-topic flow
5
- * rates alongside the stock `directParticipants` count and returns them on registration replies so
6
- * applications can decide whether the current tier is dense enough to settle on.
7
- *
8
- * Shape (`TopicTrafficV1` from the wire ticket):
9
- * - `arrivalsPerMin` — **combines** fresh registrations and renewals into one scalar (the seeker
10
- * uses renewals as a proxy for active matchable supply); the caller invokes {@link recordArrival}
11
- * for both.
12
- * - `queriesPerMin` — application-level query rate.
13
- * - counts are **exact integers** over `windowSeconds` (default 60), *not* log-bucketed like the
14
- * load barometer — the consumer-side matchmaking formulas are numeric.
15
- *
16
- * Pipeline: each member counts arrivals/queries locally ({@link recordArrival} / {@link recordQuery})
17
- * over a sliding window; {@link TrafficCounters.publish} freezes the windowed counts into the
18
- * member's gossiped per-topic summary each gossip round; {@link TrafficCounters.snapshot} returns the
19
- * **gossip-derived** view (own last-published summary + siblings' last-gossiped summaries from the
20
- * {@link CohortView}), so the reply lags by at most one round and never recomputes from raw counters
21
- * at reply time.
22
- *
23
- * Resolved open question (GROUNDING): the signal is returned **only** on `accepted` and `promoted`
24
- * replies (see {@link attachTopicTraffic}); a participant getting `Promoted(d+1)` still receives the
25
- * outgoing cohort's traffic so it can estimate whether the redirect target is hot.
26
- *
27
- * Counters reset to zero on `cohortEpoch` change ({@link TrafficCounters.reset}); the first round
28
- * after a rotation may under-report, and consumers tolerate a single zero reading.
29
- */
30
-
31
- import { bytesKey } from "./registration/bytes.js";
32
- import type { CohortView } from "./gossip/view.js";
33
- import type { RegistrationStore } from "./registration/types.js";
34
- import { bytesToB64url } from "./wire/codec.js";
35
- import type { CohortTopicSummary, RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
36
-
37
- /** Default observation window for the rate fields (seconds). */
38
- export const DEFAULT_TRAFFIC_WINDOW_SECONDS = 60;
39
-
40
- /** Frozen per-topic counts the member last published to gossip. */
41
- interface PublishedTopic {
42
- readonly arrivals: number;
43
- readonly queries: number;
44
- }
45
-
46
- /** Local windowed event timestamps (unix ms) for one topic. */
47
- interface TopicWindow {
48
- arrivals: number[];
49
- queries: number[];
50
- }
51
-
52
- /** Per-topic traffic counters with a gossip-derived snapshot. */
53
- export interface TrafficCounters {
54
- /** Record a fresh registration **or** a renewal for `topicId` at `now` (combined arrivals). */
55
- recordArrival(topicId: Uint8Array, now: number): void;
56
- /** Record an application-level query against `topicId` at `now`. */
57
- recordQuery(topicId: Uint8Array, now: number): void;
58
- /**
59
- * Freeze the current windowed counts into the member's gossiped summary (call once per gossip
60
- * round, at `now`). The frozen values are what {@link snapshot} and the gossip frame read.
61
- */
62
- publish(topicId: Uint8Array, now: number): PublishedTopic;
63
- /** Own most-recent published `(arrivals, queries)` for `topicId`, or zeros if never published. */
64
- published(topicId: Uint8Array): PublishedTopic;
65
- /**
66
- * Gossip-derived traffic for `topicId`: own last-published counts plus siblings' last-gossiped
67
- * summaries (exact-integer sums), with `directParticipants` from the replicated store. Lags ≤ one
68
- * round; never recomputes from raw counters.
69
- */
70
- snapshot(topicId: Uint8Array): TopicTrafficV1;
71
- /** Reset all counters to zero (call on `cohortEpoch` change). */
72
- reset(): void;
73
- /**
74
- * Drop all local windowed counts and the last-published summary for `topicId` (the cohort no longer
75
- * serves it — budget eviction / teardown). Idempotent; a no-op if never observed. Siblings' gossiped
76
- * contributions age out of {@link snapshot} on their own as their summaries stop naming the topic.
77
- */
78
- forget(topicId: Uint8Array): void;
79
- }
80
-
81
- export interface TrafficCountersDeps {
82
- /** Merged per-member gossip view — siblings' last-gossiped per-topic summaries. */
83
- view: CohortView;
84
- /** Replicated registration store — supplies the cohort-wide `directParticipants` stock count. */
85
- store: Pick<RegistrationStore, "directParticipants">;
86
- /** This member's own id, base64url — excluded from the sibling summary scan (counted via own published). */
87
- selfMember: string;
88
- /** Observation window (seconds). Default {@link DEFAULT_TRAFFIC_WINDOW_SECONDS}. */
89
- windowSeconds?: number;
90
- /** Tier-(d+1) cohort count for a topic (0 if not promoted); the promotion ticket owns this. */
91
- childCohortCount?: (topicId: Uint8Array) => number;
92
- }
93
-
94
- class WindowedTrafficCounters implements TrafficCounters {
95
- private readonly windows = new Map<string, TopicWindow>();
96
- private readonly lastPublished = new Map<string, PublishedTopic>();
97
- private readonly windowMs: number;
98
-
99
- constructor(private readonly deps: TrafficCountersDeps) {
100
- const ws = deps.windowSeconds ?? DEFAULT_TRAFFIC_WINDOW_SECONDS;
101
- if (!(ws > 0)) {
102
- throw new RangeError(`windowSeconds must be > 0, got ${ws}`);
103
- }
104
- this.windowMs = ws * 1000;
105
- }
106
-
107
- recordArrival(topicId: Uint8Array, now: number): void {
108
- this.windowFor(topicId).arrivals.push(now);
109
- }
110
-
111
- recordQuery(topicId: Uint8Array, now: number): void {
112
- this.windowFor(topicId).queries.push(now);
113
- }
114
-
115
- publish(topicId: Uint8Array, now: number): PublishedTopic {
116
- const w = this.windows.get(bytesKey(topicId));
117
- const frozen: PublishedTopic = {
118
- arrivals: w === undefined ? 0 : countWithin(w.arrivals, now, this.windowMs),
119
- queries: w === undefined ? 0 : countWithin(w.queries, now, this.windowMs),
120
- };
121
- this.lastPublished.set(bytesKey(topicId), frozen);
122
- return frozen;
123
- }
124
-
125
- published(topicId: Uint8Array): PublishedTopic {
126
- return this.lastPublished.get(bytesKey(topicId)) ?? { arrivals: 0, queries: 0 };
127
- }
128
-
129
- snapshot(topicId: Uint8Array): TopicTrafficV1 {
130
- const topicB64 = bytesToB64url(topicId);
131
- const own = this.published(topicId);
132
- let arrivals = own.arrivals;
133
- let queries = own.queries;
134
- let childCohortCount = 0;
135
- for (const [member, contribution] of this.deps.view.all()) {
136
- if (member === this.deps.selfMember) continue; // own contribution comes from lastPublished
137
- // O(1) per-topic lookup via the merge-time index; fall back to a scan only for a contribution
138
- // not built through `merge` (which populates `topicIndex`). Net: snapshot is O(members + summaries).
139
- const summary = contribution.topicIndex !== undefined
140
- ? contribution.topicIndex.get(topicB64)
141
- : contribution.topicSummaries.find((s) => s.topicId === topicB64);
142
- if (summary === undefined) continue;
143
- arrivals += summary.arrivalsPerMin;
144
- queries += summary.queriesPerMin;
145
- if (summary.childCohortCount > childCohortCount) {
146
- childCohortCount = summary.childCohortCount;
147
- }
148
- }
149
- // NOTE: `childCohortCount` (the max of siblings' gossiped counts above) is dormant whenever the
150
- // registry override is wired — the override returns a number (0 included), so `?? childCohortCount`
151
- // never falls through. It becomes the effective value only if the override is unwired; the child-set
152
- // replication follow-on converges siblings by populating each engine's registry, not via this max.
153
- const childOverride = this.deps.childCohortCount?.(topicId);
154
- return {
155
- windowSeconds: this.windowMs / 1000,
156
- arrivalsPerMin: arrivals,
157
- queriesPerMin: queries,
158
- directParticipants: this.deps.store.directParticipants(topicId),
159
- childCohortCount: childOverride ?? childCohortCount,
160
- };
161
- }
162
-
163
- reset(): void {
164
- this.windows.clear();
165
- this.lastPublished.clear();
166
- }
167
-
168
- forget(topicId: Uint8Array): void {
169
- // Idempotent: `Map.delete` on an absent key is a safe no-op. Clears both the raw windowed events
170
- // and the frozen last-published summary so a re-instantiated topic starts from zero.
171
- const key = bytesKey(topicId);
172
- this.windows.delete(key);
173
- this.lastPublished.delete(key);
174
- }
175
-
176
- private windowFor(topicId: Uint8Array): TopicWindow {
177
- const key = bytesKey(topicId);
178
- let w = this.windows.get(key);
179
- if (w === undefined) {
180
- w = { arrivals: [], queries: [] };
181
- this.windows.set(key, w);
182
- }
183
- return w;
184
- }
185
- }
186
-
187
- /** Count timestamps within `[now - windowMs, now]`, pruning anything older from `events` in place. */
188
- function countWithin(events: number[], now: number, windowMs: number): number {
189
- const cutoff = now - windowMs;
190
- // Events accumulate in arrival order; drop the stale prefix so the array stays bounded.
191
- let drop = 0;
192
- while (drop < events.length && events[drop]! < cutoff) {
193
- drop++;
194
- }
195
- if (drop > 0) {
196
- events.splice(0, drop);
197
- }
198
- return events.length;
199
- }
200
-
201
- /** Construct empty {@link TrafficCounters}. */
202
- export function createTrafficCounters(deps: TrafficCountersDeps): TrafficCounters {
203
- return new WindowedTrafficCounters(deps);
204
- }
205
-
206
- /**
207
- * Attach the topic-traffic signal to a reply **only** when the result is `accepted` or `promoted`
208
- * (GROUNDING-resolved: absent on `no_state`, `unwilling_member`, `unwilling_cohort`). Mutates and
209
- * returns `reply`. A no-op for non-traffic-bearing results, so callers can pipe every reply through.
210
- */
211
- export function attachTopicTraffic(reply: RegisterReplyV1, traffic: TopicTrafficV1): RegisterReplyV1 {
212
- if (reply.result === "accepted" || reply.result === "promoted") {
213
- reply.topicTraffic = traffic;
214
- }
215
- return reply;
216
- }
217
-
218
- /** The own published counts as a `CohortTopicSummary` for the gossip frame. Callers supply tier/promotion fields. */
219
- export function toCohortTopicSummary(
220
- topicId: Uint8Array,
221
- published: PublishedTopic,
222
- fields: { tier: number; directParticipants: number; promoted: boolean; childCohortCount: number },
223
- ): CohortTopicSummary {
224
- return {
225
- topicId: bytesToB64url(topicId),
226
- tier: fields.tier,
227
- directParticipants: fields.directParticipants,
228
- arrivalsPerMin: published.arrivals,
229
- queriesPerMin: published.queries,
230
- promoted: fields.promoted,
231
- childCohortCount: fields.childCohortCount,
232
- };
233
- }
1
+ /**
2
+ * Cohort-topic substrate — topic-traffic signal.
3
+ *
4
+ * Transcribed from `docs/cohort-topic.md` §Topic traffic signal. A cohort tracks per-topic flow
5
+ * rates alongside the stock `directParticipants` count and returns them on registration replies so
6
+ * applications can decide whether the current tier is dense enough to settle on.
7
+ *
8
+ * Shape (`TopicTrafficV1` from the wire ticket):
9
+ * - `arrivalsPerMin` — **combines** fresh registrations and renewals into one scalar (the seeker
10
+ * uses renewals as a proxy for active matchable supply); the caller invokes {@link recordArrival}
11
+ * for both.
12
+ * - `queriesPerMin` — application-level query rate.
13
+ * - counts are **exact integers** over `windowSeconds` (default 60), *not* log-bucketed like the
14
+ * load barometer — the consumer-side matchmaking formulas are numeric.
15
+ *
16
+ * Pipeline: each member counts arrivals/queries locally ({@link recordArrival} / {@link recordQuery})
17
+ * over a sliding window; {@link TrafficCounters.publish} freezes the windowed counts into the
18
+ * member's gossiped per-topic summary each gossip round; {@link TrafficCounters.snapshot} returns the
19
+ * **gossip-derived** view (own last-published summary + siblings' last-gossiped summaries from the
20
+ * {@link CohortView}), so the reply lags by at most one round and never recomputes from raw counters
21
+ * at reply time.
22
+ *
23
+ * Resolved open question (GROUNDING): the signal is returned **only** on `accepted` and `promoted`
24
+ * replies (see {@link attachTopicTraffic}); a participant getting `Promoted(d+1)` still receives the
25
+ * outgoing cohort's traffic so it can estimate whether the redirect target is hot.
26
+ *
27
+ * Counters reset to zero on `cohortEpoch` change ({@link TrafficCounters.reset}); the first round
28
+ * after a rotation may under-report, and consumers tolerate a single zero reading.
29
+ */
30
+
31
+ import { bytesKey } from "./registration/bytes.js";
32
+ import type { CohortView } from "./gossip/view.js";
33
+ import type { RegistrationStore } from "./registration/types.js";
34
+ import { bytesToB64url } from "./wire/codec.js";
35
+ import type { CohortTopicSummary, RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
36
+
37
+ /** Default observation window for the rate fields (seconds). */
38
+ export const DEFAULT_TRAFFIC_WINDOW_SECONDS = 60;
39
+
40
+ /** Frozen per-topic counts the member last published to gossip. */
41
+ interface PublishedTopic {
42
+ readonly arrivals: number;
43
+ readonly queries: number;
44
+ }
45
+
46
+ /** Local windowed event timestamps (unix ms) for one topic. */
47
+ interface TopicWindow {
48
+ arrivals: number[];
49
+ queries: number[];
50
+ }
51
+
52
+ /** Per-topic traffic counters with a gossip-derived snapshot. */
53
+ export interface TrafficCounters {
54
+ /** Record a fresh registration **or** a renewal for `topicId` at `now` (combined arrivals). */
55
+ recordArrival(topicId: Uint8Array, now: number): void;
56
+ /** Record an application-level query against `topicId` at `now`. */
57
+ recordQuery(topicId: Uint8Array, now: number): void;
58
+ /**
59
+ * Freeze the current windowed counts into the member's gossiped summary (call once per gossip
60
+ * round, at `now`). The frozen values are what {@link snapshot} and the gossip frame read.
61
+ */
62
+ publish(topicId: Uint8Array, now: number): PublishedTopic;
63
+ /** Own most-recent published `(arrivals, queries)` for `topicId`, or zeros if never published. */
64
+ published(topicId: Uint8Array): PublishedTopic;
65
+ /**
66
+ * Gossip-derived traffic for `topicId`: own last-published counts plus siblings' last-gossiped
67
+ * summaries (exact-integer sums), with `directParticipants` from the replicated store. Lags ≤ one
68
+ * round; never recomputes from raw counters.
69
+ */
70
+ snapshot(topicId: Uint8Array): TopicTrafficV1;
71
+ /** Reset all counters to zero (call on `cohortEpoch` change). */
72
+ reset(): void;
73
+ /**
74
+ * Drop all local windowed counts and the last-published summary for `topicId` (the cohort no longer
75
+ * serves it — budget eviction / teardown). Idempotent; a no-op if never observed. Siblings' gossiped
76
+ * contributions age out of {@link snapshot} on their own as their summaries stop naming the topic.
77
+ */
78
+ forget(topicId: Uint8Array): void;
79
+ }
80
+
81
+ export interface TrafficCountersDeps {
82
+ /** Merged per-member gossip view — siblings' last-gossiped per-topic summaries. */
83
+ view: CohortView;
84
+ /** Replicated registration store — supplies the cohort-wide `directParticipants` stock count. */
85
+ store: Pick<RegistrationStore, "directParticipants">;
86
+ /** This member's own id, base64url — excluded from the sibling summary scan (counted via own published). */
87
+ selfMember: string;
88
+ /** Observation window (seconds). Default {@link DEFAULT_TRAFFIC_WINDOW_SECONDS}. */
89
+ windowSeconds?: number;
90
+ /** Tier-(d+1) cohort count for a topic (0 if not promoted); the promotion ticket owns this. */
91
+ childCohortCount?: (topicId: Uint8Array) => number;
92
+ }
93
+
94
+ class WindowedTrafficCounters implements TrafficCounters {
95
+ private readonly windows = new Map<string, TopicWindow>();
96
+ private readonly lastPublished = new Map<string, PublishedTopic>();
97
+ private readonly windowMs: number;
98
+
99
+ constructor(private readonly deps: TrafficCountersDeps) {
100
+ const ws = deps.windowSeconds ?? DEFAULT_TRAFFIC_WINDOW_SECONDS;
101
+ if (!(ws > 0)) {
102
+ throw new RangeError(`windowSeconds must be > 0, got ${ws}`);
103
+ }
104
+ this.windowMs = ws * 1000;
105
+ }
106
+
107
+ recordArrival(topicId: Uint8Array, now: number): void {
108
+ this.windowFor(topicId).arrivals.push(now);
109
+ }
110
+
111
+ recordQuery(topicId: Uint8Array, now: number): void {
112
+ this.windowFor(topicId).queries.push(now);
113
+ }
114
+
115
+ publish(topicId: Uint8Array, now: number): PublishedTopic {
116
+ const w = this.windows.get(bytesKey(topicId));
117
+ const frozen: PublishedTopic = {
118
+ arrivals: w === undefined ? 0 : countWithin(w.arrivals, now, this.windowMs),
119
+ queries: w === undefined ? 0 : countWithin(w.queries, now, this.windowMs),
120
+ };
121
+ this.lastPublished.set(bytesKey(topicId), frozen);
122
+ return frozen;
123
+ }
124
+
125
+ published(topicId: Uint8Array): PublishedTopic {
126
+ return this.lastPublished.get(bytesKey(topicId)) ?? { arrivals: 0, queries: 0 };
127
+ }
128
+
129
+ snapshot(topicId: Uint8Array): TopicTrafficV1 {
130
+ const topicB64 = bytesToB64url(topicId);
131
+ const own = this.published(topicId);
132
+ let arrivals = own.arrivals;
133
+ let queries = own.queries;
134
+ let childCohortCount = 0;
135
+ for (const [member, contribution] of this.deps.view.all()) {
136
+ if (member === this.deps.selfMember) continue; // own contribution comes from lastPublished
137
+ // O(1) per-topic lookup via the merge-time index; fall back to a scan only for a contribution
138
+ // not built through `merge` (which populates `topicIndex`). Net: snapshot is O(members + summaries).
139
+ const summary = contribution.topicIndex !== undefined
140
+ ? contribution.topicIndex.get(topicB64)
141
+ : contribution.topicSummaries.find((s) => s.topicId === topicB64);
142
+ if (summary === undefined) continue;
143
+ arrivals += summary.arrivalsPerMin;
144
+ queries += summary.queriesPerMin;
145
+ if (summary.childCohortCount > childCohortCount) {
146
+ childCohortCount = summary.childCohortCount;
147
+ }
148
+ }
149
+ // NOTE: `childCohortCount` (the max of siblings' gossiped counts above) is dormant whenever the
150
+ // registry override is wired — the override returns a number (0 included), so `?? childCohortCount`
151
+ // never falls through. It becomes the effective value only if the override is unwired; the child-set
152
+ // replication follow-on converges siblings by populating each engine's registry, not via this max.
153
+ const childOverride = this.deps.childCohortCount?.(topicId);
154
+ return {
155
+ windowSeconds: this.windowMs / 1000,
156
+ arrivalsPerMin: arrivals,
157
+ queriesPerMin: queries,
158
+ directParticipants: this.deps.store.directParticipants(topicId),
159
+ childCohortCount: childOverride ?? childCohortCount,
160
+ };
161
+ }
162
+
163
+ reset(): void {
164
+ this.windows.clear();
165
+ this.lastPublished.clear();
166
+ }
167
+
168
+ forget(topicId: Uint8Array): void {
169
+ // Idempotent: `Map.delete` on an absent key is a safe no-op. Clears both the raw windowed events
170
+ // and the frozen last-published summary so a re-instantiated topic starts from zero.
171
+ const key = bytesKey(topicId);
172
+ this.windows.delete(key);
173
+ this.lastPublished.delete(key);
174
+ }
175
+
176
+ private windowFor(topicId: Uint8Array): TopicWindow {
177
+ const key = bytesKey(topicId);
178
+ let w = this.windows.get(key);
179
+ if (w === undefined) {
180
+ w = { arrivals: [], queries: [] };
181
+ this.windows.set(key, w);
182
+ }
183
+ return w;
184
+ }
185
+ }
186
+
187
+ /** Count timestamps within `[now - windowMs, now]`, pruning anything older from `events` in place. */
188
+ function countWithin(events: number[], now: number, windowMs: number): number {
189
+ const cutoff = now - windowMs;
190
+ // Events accumulate in arrival order; drop the stale prefix so the array stays bounded.
191
+ let drop = 0;
192
+ while (drop < events.length && events[drop]! < cutoff) {
193
+ drop++;
194
+ }
195
+ if (drop > 0) {
196
+ events.splice(0, drop);
197
+ }
198
+ return events.length;
199
+ }
200
+
201
+ /** Construct empty {@link TrafficCounters}. */
202
+ export function createTrafficCounters(deps: TrafficCountersDeps): TrafficCounters {
203
+ return new WindowedTrafficCounters(deps);
204
+ }
205
+
206
+ /**
207
+ * Attach the topic-traffic signal to a reply **only** when the result is `accepted` or `promoted`
208
+ * (GROUNDING-resolved: absent on `no_state`, `unwilling_member`, `unwilling_cohort`). Mutates and
209
+ * returns `reply`. A no-op for non-traffic-bearing results, so callers can pipe every reply through.
210
+ */
211
+ export function attachTopicTraffic(reply: RegisterReplyV1, traffic: TopicTrafficV1): RegisterReplyV1 {
212
+ if (reply.result === "accepted" || reply.result === "promoted") {
213
+ reply.topicTraffic = traffic;
214
+ }
215
+ return reply;
216
+ }
217
+
218
+ /** The own published counts as a `CohortTopicSummary` for the gossip frame. Callers supply tier/promotion fields. */
219
+ export function toCohortTopicSummary(
220
+ topicId: Uint8Array,
221
+ published: PublishedTopic,
222
+ fields: { tier: number; directParticipants: number; promoted: boolean; childCohortCount: number },
223
+ ): CohortTopicSummary {
224
+ return {
225
+ topicId: bytesToB64url(topicId),
226
+ tier: fields.tier,
227
+ directParticipants: fields.directParticipants,
228
+ arrivalsPerMin: published.arrivals,
229
+ queriesPerMin: published.queries,
230
+ promoted: fields.promoted,
231
+ childCohortCount: fields.childCohortCount,
232
+ };
233
+ }