@optimystic/db-core 1.5.0 → 1.5.1

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 (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. package/src/utility/pending.ts +43 -43
@@ -1,172 +1,172 @@
1
- /**
2
- * Reactivity — configuration defaults (single source for the hot path).
3
- *
4
- * Transcribed from `docs/reactivity.md` §Configuration. Every tunable the reactivity hot path reads
5
- * is sourced from {@link DEFAULT_REACTIVITY_CONFIG} — never hard-coded at a call site — so the
6
- * simulator fold-back ([fold-simulator-findings-into-design-docs]) can retune `W` / `dedupe_window`
7
- * without touching origination, forwarding, the replay buffer, or delivery.
8
- *
9
- * **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain`, `queue_max`,
10
- * and `block_fill_size` are *provisional* pending the design simulator ([simulator-reactivity-replay],
11
- * folded back by [fold-simulator-findings-into-design-docs]). The simulator's REVISED guidance is that `W`
12
- * SHOULD become adaptive per measured commit-rate on hot collections (`W ≈ ⌈min_coverage × cps⌉`); the
13
- * static `W = 256` is kept as the Edge/low-rate default. {@link resolveW} exposes that hook; the
14
- * simulator's tail-rotation scenario also confirms the re-registration burst stays inside
15
- * `cap_promote_fast` within `T_drain`, and flags whether `queue_max` should scale with cohort size/tier
16
- * ({@link resolveQueueMax} is the parallel hook for that fold-back). Sourcing every tunable from this
17
- * single table is what lets the fold-back revise the values without touching the protocol code.
18
- *
19
- * Ownership: `W` / `dedupe_window` ← [reactivity-origination-replay-delivery]; `W_checkpoint` ←
20
- * [reactivity-backfill-resume-checkpoints]; `queue_max` / `delta_max` / `T_drain` / `warm_threshold` /
21
- * `block_fill_size` ← [reactivity-rotation-backpressure-policy] (this ticket). `T_rejoin_jitter`, TTL, and
22
- * ping are inherited from the cohort-topic defaults.
23
- */
24
-
25
- import type { NodeProfile } from "../cohort-topic/tiers.js";
26
- import { DEFAULT_T_REJOIN_JITTER_MS } from "../cohort-topic/antiflood/jitter.js";
27
-
28
- /** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
29
- export const W_DEFAULT = 256;
30
- /** Sliding dedupe-window size (revisions). Simulator-validated-pending. */
31
- export const DEDUPE_WINDOW_DEFAULT = 64;
32
- /** Parent-checkpoint span (revisions). Owned by the backfill/resume ticket; default carried here. */
33
- export const W_CHECKPOINT_DEFAULT = 4096;
34
- /** Per-subscriber bounded queue depth at a forwarder. Simulator-validated-pending (may scale with cohort/tier). */
35
- export const QUEUE_MAX_DEFAULT = 32;
36
- /** Max delta payload size on a Core node (bytes). */
37
- export const DELTA_MAX_CORE_BYTES = 4096;
38
- /** Max delta payload size on an Edge node (bytes) — Edge declines deltas (`0` ⇒ omit `delta`). */
39
- export const DELTA_MAX_EDGE_BYTES = 0;
40
- /** Subscriber registration TTL on a Core node (ms), inherited from cohort-topic. */
41
- export const SUBSCRIBER_TTL_CORE_MS = 90_000;
42
- /** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
43
- export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
44
- /** Transactions per block — drives tail rotation. Simulator-validated-pending. */
45
- export const BLOCK_FILL_SIZE_DEFAULT = 64;
46
- /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
47
- export const T_DRAIN_MS = 60_000;
48
- /** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
49
- export const WARM_THRESHOLD_DEFAULT = 8;
50
- /** Subscriber re-registration jitter span after a rotation hint (ms). Inherited from cohort-topic `T_rejoin_jitter`. */
51
- export const T_REJOIN_JITTER_MS = DEFAULT_T_REJOIN_JITTER_MS;
52
-
53
- /** The full reactivity config, with the documented defaults. */
54
- export interface ReactivityConfig {
55
- /** Replay buffer depth `W`. Simulator-validated-pending. */
56
- readonly w: number;
57
- /** Sliding dedupe-window size. Simulator-validated-pending. */
58
- readonly dedupeWindow: number;
59
- /** Parent-checkpoint span (reserved; backfill/resume ticket). */
60
- readonly wCheckpoint: number;
61
- /** Per-subscriber bounded queue depth (reserved; backpressure ticket). */
62
- readonly queueMax: number;
63
- /** Max delta payload size on a Core node (bytes). */
64
- readonly deltaMaxCoreBytes: number;
65
- /** Max delta payload size on an Edge node (bytes). */
66
- readonly deltaMaxEdgeBytes: number;
67
- /** Subscriber TTL on a Core node (ms). */
68
- readonly subscriberTtlCoreMs: number;
69
- /** Subscriber TTL on an Edge node (ms). */
70
- readonly subscriberTtlEdgeMs: number;
71
- /** Transactions per block — drives tail rotation. Simulator-validated-pending. */
72
- readonly blockFillSize: number;
73
- /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
74
- readonly tDrainMs: number;
75
- /** Transactions remaining before anticipatory warm-up. */
76
- readonly warmThreshold: number;
77
- /** Subscriber re-registration jitter span after a rotation (ms); inherited from cohort-topic. */
78
- readonly tRejoinJitterMs: number;
79
- }
80
-
81
- /** The default reactivity config (`docs/reactivity.md` §Configuration). */
82
- export const DEFAULT_REACTIVITY_CONFIG: ReactivityConfig = {
83
- w: W_DEFAULT,
84
- dedupeWindow: DEDUPE_WINDOW_DEFAULT,
85
- wCheckpoint: W_CHECKPOINT_DEFAULT,
86
- queueMax: QUEUE_MAX_DEFAULT,
87
- deltaMaxCoreBytes: DELTA_MAX_CORE_BYTES,
88
- deltaMaxEdgeBytes: DELTA_MAX_EDGE_BYTES,
89
- subscriberTtlCoreMs: SUBSCRIBER_TTL_CORE_MS,
90
- subscriberTtlEdgeMs: SUBSCRIBER_TTL_EDGE_MS,
91
- blockFillSize: BLOCK_FILL_SIZE_DEFAULT,
92
- tDrainMs: T_DRAIN_MS,
93
- warmThreshold: WARM_THRESHOLD_DEFAULT,
94
- tRejoinJitterMs: T_REJOIN_JITTER_MS,
95
- };
96
-
97
- /** `delta_max` for a node profile: Core admits deltas up to `delta_max`, Edge declines them (`0`). */
98
- export function deltaMaxForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
99
- return profile.kind === "edge" ? config.deltaMaxEdgeBytes : config.deltaMaxCoreBytes;
100
- }
101
-
102
- /** Subscriber TTL for a node profile (`docs/reactivity.md` §Subscription): Core 90 s / Edge 60 s. */
103
- export function subscriberTtlForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
104
- return profile.kind === "edge" ? config.subscriberTtlEdgeMs : config.subscriberTtlCoreMs;
105
- }
106
-
107
- /**
108
- * Resolve the replay-buffer depth `W` for a collection.
109
- *
110
- * Static default (no `cps`): returns the configured `config.w` unchanged — the simulator-confirmed
111
- * Edge/low-rate default. Adaptive (a measured `cps` and `minCoverageSeconds`): returns
112
- * `⌈minCoverageSeconds × cps⌉` clamped to `[config.w, maxW]`, the simulator's REVISED guidance for hot
113
- * collections. This is the single hook the backfill/resume ticket extends; the hot path here only ever
114
- * calls the static form, so behavior is unchanged until a `cps` is wired through.
115
- */
116
- export function resolveW(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; config?: ReactivityConfig } = {}): number {
117
- const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
118
- if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
119
- return config.w;
120
- }
121
- if (!Number.isFinite(opts.cps) || opts.cps <= 0 || !Number.isFinite(opts.minCoverageSeconds) || opts.minCoverageSeconds <= 0) {
122
- return config.w;
123
- }
124
- const adaptive = Math.ceil(opts.minCoverageSeconds * opts.cps);
125
- const maxW = opts.maxW ?? Number.POSITIVE_INFINITY;
126
- return Math.min(Math.max(config.w, adaptive), maxW);
127
- }
128
-
129
- /** Default `W_checkpoint`-to-`W` ratio (`docs/reactivity.md` §Parent checkpoint summaries: 16×). */
130
- export const W_CHECKPOINT_RATIO = 16;
131
-
132
- /**
133
- * Resolve the parent-checkpoint span `W_checkpoint` for a collection.
134
- *
135
- * Static default (no `cps`): the configured `config.wCheckpoint` (4096). Adaptive: `W_checkpoint`
136
- * "scales the same way and may stay a fixed 16× multiple of the resolved `W`" (`docs/reactivity.md`
137
- * §Configuration), so when a `cps` is supplied it tracks `W_CHECKPOINT_RATIO × resolveW(opts)`. This is
138
- * the single hook the simulator fold-back ([fold-simulator-findings-into-design-docs]) retunes; the
139
- * resume classifier reads it so a hot collection's stacked recovery range scales with the replay depth.
140
- */
141
- export function resolveWCheckpoint(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; ratio?: number; config?: ReactivityConfig } = {}): number {
142
- const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
143
- if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
144
- return config.wCheckpoint;
145
- }
146
- const ratio = opts.ratio ?? W_CHECKPOINT_RATIO;
147
- return resolveW(opts) * ratio;
148
- }
149
-
150
- /**
151
- * Resolve the per-subscriber bounded-queue depth `queue_max` for a cohort.
152
- *
153
- * Static default (no scaling input): the configured `config.queueMax` (32). The simulator flags whether
154
- * `queue_max` should scale with cohort size / tier on hot collections; this is the single hook the
155
- * fold-back ([fold-simulator-findings-into-design-docs]) retunes. When a `cohortSubscribers` count is
156
- * supplied, the depth scales as `⌈queue_max × subscribers / scaleBaseline⌉` clamped to `[queueMax, maxQueue]`
157
- * — never below the static default, optionally capped at a per-cohort memory budget. With no scaling input
158
- * the hot path is unchanged (constant `queue_max`).
159
- */
160
- export function resolveQueueMax(opts: { cohortSubscribers?: number; scaleBaseline?: number; maxQueue?: number; config?: ReactivityConfig } = {}): number {
161
- const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
162
- if (opts.cohortSubscribers === undefined) {
163
- return config.queueMax;
164
- }
165
- const baseline = opts.scaleBaseline ?? 1;
166
- if (!Number.isFinite(opts.cohortSubscribers) || opts.cohortSubscribers <= 0 || !(baseline > 0)) {
167
- return config.queueMax;
168
- }
169
- const scaled = Math.ceil((config.queueMax * opts.cohortSubscribers) / baseline);
170
- const maxQueue = opts.maxQueue ?? Number.POSITIVE_INFINITY;
171
- return Math.min(Math.max(config.queueMax, scaled), maxQueue);
172
- }
1
+ /**
2
+ * Reactivity — configuration defaults (single source for the hot path).
3
+ *
4
+ * Transcribed from `docs/reactivity.md` §Configuration. Every tunable the reactivity hot path reads
5
+ * is sourced from {@link DEFAULT_REACTIVITY_CONFIG} — never hard-coded at a call site — so the
6
+ * simulator fold-back ([fold-simulator-findings-into-design-docs]) can retune `W` / `dedupe_window`
7
+ * without touching origination, forwarding, the replay buffer, or delivery.
8
+ *
9
+ * **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain`, `queue_max`,
10
+ * and `block_fill_size` are *provisional* pending the design simulator ([simulator-reactivity-replay],
11
+ * folded back by [fold-simulator-findings-into-design-docs]). The simulator's REVISED guidance is that `W`
12
+ * SHOULD become adaptive per measured commit-rate on hot collections (`W ≈ ⌈min_coverage × cps⌉`); the
13
+ * static `W = 256` is kept as the Edge/low-rate default. {@link resolveW} exposes that hook; the
14
+ * simulator's tail-rotation scenario also confirms the re-registration burst stays inside
15
+ * `cap_promote_fast` within `T_drain`, and flags whether `queue_max` should scale with cohort size/tier
16
+ * ({@link resolveQueueMax} is the parallel hook for that fold-back). Sourcing every tunable from this
17
+ * single table is what lets the fold-back revise the values without touching the protocol code.
18
+ *
19
+ * Ownership: `W` / `dedupe_window` ← [reactivity-origination-replay-delivery]; `W_checkpoint` ←
20
+ * [reactivity-backfill-resume-checkpoints]; `queue_max` / `delta_max` / `T_drain` / `warm_threshold` /
21
+ * `block_fill_size` ← [reactivity-rotation-backpressure-policy] (this ticket). `T_rejoin_jitter`, TTL, and
22
+ * ping are inherited from the cohort-topic defaults.
23
+ */
24
+
25
+ import type { NodeProfile } from "../cohort-topic/tiers.js";
26
+ import { DEFAULT_T_REJOIN_JITTER_MS } from "../cohort-topic/antiflood/jitter.js";
27
+
28
+ /** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
29
+ export const W_DEFAULT = 256;
30
+ /** Sliding dedupe-window size (revisions). Simulator-validated-pending. */
31
+ export const DEDUPE_WINDOW_DEFAULT = 64;
32
+ /** Parent-checkpoint span (revisions). Owned by the backfill/resume ticket; default carried here. */
33
+ export const W_CHECKPOINT_DEFAULT = 4096;
34
+ /** Per-subscriber bounded queue depth at a forwarder. Simulator-validated-pending (may scale with cohort/tier). */
35
+ export const QUEUE_MAX_DEFAULT = 32;
36
+ /** Max delta payload size on a Core node (bytes). */
37
+ export const DELTA_MAX_CORE_BYTES = 4096;
38
+ /** Max delta payload size on an Edge node (bytes) — Edge declines deltas (`0` ⇒ omit `delta`). */
39
+ export const DELTA_MAX_EDGE_BYTES = 0;
40
+ /** Subscriber registration TTL on a Core node (ms), inherited from cohort-topic. */
41
+ export const SUBSCRIBER_TTL_CORE_MS = 90_000;
42
+ /** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
43
+ export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
44
+ /** Transactions per block — drives tail rotation. Simulator-validated-pending. */
45
+ export const BLOCK_FILL_SIZE_DEFAULT = 64;
46
+ /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
47
+ export const T_DRAIN_MS = 60_000;
48
+ /** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
49
+ export const WARM_THRESHOLD_DEFAULT = 8;
50
+ /** Subscriber re-registration jitter span after a rotation hint (ms). Inherited from cohort-topic `T_rejoin_jitter`. */
51
+ export const T_REJOIN_JITTER_MS = DEFAULT_T_REJOIN_JITTER_MS;
52
+
53
+ /** The full reactivity config, with the documented defaults. */
54
+ export interface ReactivityConfig {
55
+ /** Replay buffer depth `W`. Simulator-validated-pending. */
56
+ readonly w: number;
57
+ /** Sliding dedupe-window size. Simulator-validated-pending. */
58
+ readonly dedupeWindow: number;
59
+ /** Parent-checkpoint span (reserved; backfill/resume ticket). */
60
+ readonly wCheckpoint: number;
61
+ /** Per-subscriber bounded queue depth (reserved; backpressure ticket). */
62
+ readonly queueMax: number;
63
+ /** Max delta payload size on a Core node (bytes). */
64
+ readonly deltaMaxCoreBytes: number;
65
+ /** Max delta payload size on an Edge node (bytes). */
66
+ readonly deltaMaxEdgeBytes: number;
67
+ /** Subscriber TTL on a Core node (ms). */
68
+ readonly subscriberTtlCoreMs: number;
69
+ /** Subscriber TTL on an Edge node (ms). */
70
+ readonly subscriberTtlEdgeMs: number;
71
+ /** Transactions per block — drives tail rotation. Simulator-validated-pending. */
72
+ readonly blockFillSize: number;
73
+ /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
74
+ readonly tDrainMs: number;
75
+ /** Transactions remaining before anticipatory warm-up. */
76
+ readonly warmThreshold: number;
77
+ /** Subscriber re-registration jitter span after a rotation (ms); inherited from cohort-topic. */
78
+ readonly tRejoinJitterMs: number;
79
+ }
80
+
81
+ /** The default reactivity config (`docs/reactivity.md` §Configuration). */
82
+ export const DEFAULT_REACTIVITY_CONFIG: ReactivityConfig = {
83
+ w: W_DEFAULT,
84
+ dedupeWindow: DEDUPE_WINDOW_DEFAULT,
85
+ wCheckpoint: W_CHECKPOINT_DEFAULT,
86
+ queueMax: QUEUE_MAX_DEFAULT,
87
+ deltaMaxCoreBytes: DELTA_MAX_CORE_BYTES,
88
+ deltaMaxEdgeBytes: DELTA_MAX_EDGE_BYTES,
89
+ subscriberTtlCoreMs: SUBSCRIBER_TTL_CORE_MS,
90
+ subscriberTtlEdgeMs: SUBSCRIBER_TTL_EDGE_MS,
91
+ blockFillSize: BLOCK_FILL_SIZE_DEFAULT,
92
+ tDrainMs: T_DRAIN_MS,
93
+ warmThreshold: WARM_THRESHOLD_DEFAULT,
94
+ tRejoinJitterMs: T_REJOIN_JITTER_MS,
95
+ };
96
+
97
+ /** `delta_max` for a node profile: Core admits deltas up to `delta_max`, Edge declines them (`0`). */
98
+ export function deltaMaxForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
99
+ return profile.kind === "edge" ? config.deltaMaxEdgeBytes : config.deltaMaxCoreBytes;
100
+ }
101
+
102
+ /** Subscriber TTL for a node profile (`docs/reactivity.md` §Subscription): Core 90 s / Edge 60 s. */
103
+ export function subscriberTtlForProfile(profile: NodeProfile, config: ReactivityConfig = DEFAULT_REACTIVITY_CONFIG): number {
104
+ return profile.kind === "edge" ? config.subscriberTtlEdgeMs : config.subscriberTtlCoreMs;
105
+ }
106
+
107
+ /**
108
+ * Resolve the replay-buffer depth `W` for a collection.
109
+ *
110
+ * Static default (no `cps`): returns the configured `config.w` unchanged — the simulator-confirmed
111
+ * Edge/low-rate default. Adaptive (a measured `cps` and `minCoverageSeconds`): returns
112
+ * `⌈minCoverageSeconds × cps⌉` clamped to `[config.w, maxW]`, the simulator's REVISED guidance for hot
113
+ * collections. This is the single hook the backfill/resume ticket extends; the hot path here only ever
114
+ * calls the static form, so behavior is unchanged until a `cps` is wired through.
115
+ */
116
+ export function resolveW(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; config?: ReactivityConfig } = {}): number {
117
+ const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
118
+ if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
119
+ return config.w;
120
+ }
121
+ if (!Number.isFinite(opts.cps) || opts.cps <= 0 || !Number.isFinite(opts.minCoverageSeconds) || opts.minCoverageSeconds <= 0) {
122
+ return config.w;
123
+ }
124
+ const adaptive = Math.ceil(opts.minCoverageSeconds * opts.cps);
125
+ const maxW = opts.maxW ?? Number.POSITIVE_INFINITY;
126
+ return Math.min(Math.max(config.w, adaptive), maxW);
127
+ }
128
+
129
+ /** Default `W_checkpoint`-to-`W` ratio (`docs/reactivity.md` §Parent checkpoint summaries: 16×). */
130
+ export const W_CHECKPOINT_RATIO = 16;
131
+
132
+ /**
133
+ * Resolve the parent-checkpoint span `W_checkpoint` for a collection.
134
+ *
135
+ * Static default (no `cps`): the configured `config.wCheckpoint` (4096). Adaptive: `W_checkpoint`
136
+ * "scales the same way and may stay a fixed 16× multiple of the resolved `W`" (`docs/reactivity.md`
137
+ * §Configuration), so when a `cps` is supplied it tracks `W_CHECKPOINT_RATIO × resolveW(opts)`. This is
138
+ * the single hook the simulator fold-back ([fold-simulator-findings-into-design-docs]) retunes; the
139
+ * resume classifier reads it so a hot collection's stacked recovery range scales with the replay depth.
140
+ */
141
+ export function resolveWCheckpoint(opts: { cps?: number; minCoverageSeconds?: number; maxW?: number; ratio?: number; config?: ReactivityConfig } = {}): number {
142
+ const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
143
+ if (opts.cps === undefined || opts.minCoverageSeconds === undefined) {
144
+ return config.wCheckpoint;
145
+ }
146
+ const ratio = opts.ratio ?? W_CHECKPOINT_RATIO;
147
+ return resolveW(opts) * ratio;
148
+ }
149
+
150
+ /**
151
+ * Resolve the per-subscriber bounded-queue depth `queue_max` for a cohort.
152
+ *
153
+ * Static default (no scaling input): the configured `config.queueMax` (32). The simulator flags whether
154
+ * `queue_max` should scale with cohort size / tier on hot collections; this is the single hook the
155
+ * fold-back ([fold-simulator-findings-into-design-docs]) retunes. When a `cohortSubscribers` count is
156
+ * supplied, the depth scales as `⌈queue_max × subscribers / scaleBaseline⌉` clamped to `[queueMax, maxQueue]`
157
+ * — never below the static default, optionally capped at a per-cohort memory budget. With no scaling input
158
+ * the hot path is unchanged (constant `queue_max`).
159
+ */
160
+ export function resolveQueueMax(opts: { cohortSubscribers?: number; scaleBaseline?: number; maxQueue?: number; config?: ReactivityConfig } = {}): number {
161
+ const config = opts.config ?? DEFAULT_REACTIVITY_CONFIG;
162
+ if (opts.cohortSubscribers === undefined) {
163
+ return config.queueMax;
164
+ }
165
+ const baseline = opts.scaleBaseline ?? 1;
166
+ if (!Number.isFinite(opts.cohortSubscribers) || opts.cohortSubscribers <= 0 || !(baseline > 0)) {
167
+ return config.queueMax;
168
+ }
169
+ const scaled = Math.ceil((config.queueMax * opts.cohortSubscribers) / baseline);
170
+ const maxQueue = opts.maxQueue ?? Number.POSITIVE_INFINITY;
171
+ return Math.min(Math.max(config.queueMax, scaled), maxQueue);
172
+ }
@@ -1,132 +1,132 @@
1
- /**
2
- * Reactivity — per-revision dedupe (sliding-window set), `docs/reactivity.md` §Per-revision dedupe.
3
- *
4
- * A scalar `lastRevision` is insufficient under partition healing: the same revision may legitimately
5
- * arrive from multiple parents during a merge, and dropping all but the first on `revision > lastRevision`
6
- * would discard honest retransmits exactly when a subscriber needs them. Instead each forwarder keeps a
7
- * sliding set of `(revision, sigDigest)` pairs for the last `dedupe_window` revisions (default 64).
8
- *
9
- * A notification is forwarded if:
10
- * - it is for the *highest revision* seen in the window (normal case), OR
11
- * - it is for an earlier revision, its `(revision, sigDigest)` is not already in the set, and it passes
12
- * verification (recovery: a retransmit closing a gap).
13
- *
14
- * Both reduce to: **forward iff the `(revision, sigDigest)` key is not already present** (verification is
15
- * the forwarder's prior step, applied to every inbound). Keys already in the set are dropped silently.
16
- * The set is gossiped within the cohort ({@link DedupeWindow.serialize} / {@link DedupeWindow.merge}) so
17
- * all members agree on what has been seen.
18
- */
19
-
20
- import { DEDUPE_WINDOW_DEFAULT } from "./config.js";
21
-
22
- /** The dedupe decision for one inbound notification. */
23
- export type DedupeOutcome = "forward" | "duplicate";
24
-
25
- /** Serializable dedupe state for intra-cohort gossip convergence. */
26
- export interface DedupeStateV1 {
27
- /** Highest revision observed (anchors the sliding window's high edge). */
28
- readonly highestRevision: number;
29
- /** Seen `(revision, sigDigest)` keys with their revision, for window-bounded merge. */
30
- readonly entries: ReadonlyArray<{ readonly key: string; readonly revision: number }>;
31
- }
32
-
33
- /** A sliding-window dedupe set over `(revision, sigDigest)` pairs. */
34
- export interface DedupeWindow {
35
- /** Highest revision observed so far (`-1` before any observation). */
36
- readonly highestRevision: number;
37
- /** Number of retained keys. */
38
- readonly size: number;
39
- /** True iff `(revision, sigDigest)` is already in the set. */
40
- has(revision: number, sigDigest: string): boolean;
41
- /**
42
- * Record `(revision, sigDigest)` and report whether it should be forwarded. Returns `"duplicate"`
43
- * (no state change) if already seen, else records it, advances the window, and returns `"forward"`.
44
- */
45
- observe(revision: number, sigDigest: string): DedupeOutcome;
46
- /** Snapshot for gossip. */
47
- serialize(): DedupeStateV1;
48
- /** Union another member's gossiped state into this one (idempotent, commutative within the window). */
49
- merge(state: DedupeStateV1): void;
50
- }
51
-
52
- class SlidingDedupeWindow implements DedupeWindow {
53
- private readonly windowSize: number;
54
- /** key → revision, for window-bounded eviction. */
55
- private readonly seen = new Map<string, number>();
56
- private highest = -1;
57
-
58
- constructor(windowSize: number) {
59
- if (!Number.isInteger(windowSize) || windowSize < 1) {
60
- throw new RangeError(`reactivity dedupe: windowSize must be an integer >= 1, got ${windowSize}`);
61
- }
62
- this.windowSize = windowSize;
63
- }
64
-
65
- get highestRevision(): number {
66
- return this.highest;
67
- }
68
-
69
- get size(): number {
70
- return this.seen.size;
71
- }
72
-
73
- has(revision: number, sigDigest: string): boolean {
74
- return this.seen.has(keyOf(revision, sigDigest));
75
- }
76
-
77
- observe(revision: number, sigDigest: string): DedupeOutcome {
78
- const key = keyOf(revision, sigDigest);
79
- if (this.seen.has(key)) {
80
- return "duplicate";
81
- }
82
- this.insert(key, revision);
83
- return "forward";
84
- }
85
-
86
- serialize(): DedupeStateV1 {
87
- return {
88
- highestRevision: this.highest,
89
- entries: [...this.seen].map(([key, rev]) => ({ key, revision: rev })),
90
- };
91
- }
92
-
93
- merge(state: DedupeStateV1): void {
94
- if (state.highestRevision > this.highest) {
95
- this.highest = state.highestRevision;
96
- }
97
- for (const { key, revision } of state.entries) {
98
- if (!this.seen.has(key)) {
99
- this.seen.set(key, revision);
100
- }
101
- }
102
- this.evictBelowWindow();
103
- }
104
-
105
- private insert(key: string, revision: number): void {
106
- if (revision > this.highest) {
107
- this.highest = revision;
108
- }
109
- this.seen.set(key, revision);
110
- this.evictBelowWindow();
111
- }
112
-
113
- /** Retain only revisions within `[highest - windowSize + 1, highest]`. */
114
- private evictBelowWindow(): void {
115
- const low = this.highest - this.windowSize + 1;
116
- for (const [key, revision] of this.seen) {
117
- if (revision < low) {
118
- this.seen.delete(key);
119
- }
120
- }
121
- }
122
- }
123
-
124
- /** `${revision}:${sigDigest}` — the dedupe-set key. */
125
- function keyOf(revision: number, sigDigest: string): string {
126
- return `${revision}:${sigDigest}`;
127
- }
128
-
129
- /** Build a {@link DedupeWindow} with the configured (default {@link DEDUPE_WINDOW_DEFAULT}) span. */
130
- export function createDedupeWindow(windowSize: number = DEDUPE_WINDOW_DEFAULT): DedupeWindow {
131
- return new SlidingDedupeWindow(windowSize);
132
- }
1
+ /**
2
+ * Reactivity — per-revision dedupe (sliding-window set), `docs/reactivity.md` §Per-revision dedupe.
3
+ *
4
+ * A scalar `lastRevision` is insufficient under partition healing: the same revision may legitimately
5
+ * arrive from multiple parents during a merge, and dropping all but the first on `revision > lastRevision`
6
+ * would discard honest retransmits exactly when a subscriber needs them. Instead each forwarder keeps a
7
+ * sliding set of `(revision, sigDigest)` pairs for the last `dedupe_window` revisions (default 64).
8
+ *
9
+ * A notification is forwarded if:
10
+ * - it is for the *highest revision* seen in the window (normal case), OR
11
+ * - it is for an earlier revision, its `(revision, sigDigest)` is not already in the set, and it passes
12
+ * verification (recovery: a retransmit closing a gap).
13
+ *
14
+ * Both reduce to: **forward iff the `(revision, sigDigest)` key is not already present** (verification is
15
+ * the forwarder's prior step, applied to every inbound). Keys already in the set are dropped silently.
16
+ * The set is gossiped within the cohort ({@link DedupeWindow.serialize} / {@link DedupeWindow.merge}) so
17
+ * all members agree on what has been seen.
18
+ */
19
+
20
+ import { DEDUPE_WINDOW_DEFAULT } from "./config.js";
21
+
22
+ /** The dedupe decision for one inbound notification. */
23
+ export type DedupeOutcome = "forward" | "duplicate";
24
+
25
+ /** Serializable dedupe state for intra-cohort gossip convergence. */
26
+ export interface DedupeStateV1 {
27
+ /** Highest revision observed (anchors the sliding window's high edge). */
28
+ readonly highestRevision: number;
29
+ /** Seen `(revision, sigDigest)` keys with their revision, for window-bounded merge. */
30
+ readonly entries: ReadonlyArray<{ readonly key: string; readonly revision: number }>;
31
+ }
32
+
33
+ /** A sliding-window dedupe set over `(revision, sigDigest)` pairs. */
34
+ export interface DedupeWindow {
35
+ /** Highest revision observed so far (`-1` before any observation). */
36
+ readonly highestRevision: number;
37
+ /** Number of retained keys. */
38
+ readonly size: number;
39
+ /** True iff `(revision, sigDigest)` is already in the set. */
40
+ has(revision: number, sigDigest: string): boolean;
41
+ /**
42
+ * Record `(revision, sigDigest)` and report whether it should be forwarded. Returns `"duplicate"`
43
+ * (no state change) if already seen, else records it, advances the window, and returns `"forward"`.
44
+ */
45
+ observe(revision: number, sigDigest: string): DedupeOutcome;
46
+ /** Snapshot for gossip. */
47
+ serialize(): DedupeStateV1;
48
+ /** Union another member's gossiped state into this one (idempotent, commutative within the window). */
49
+ merge(state: DedupeStateV1): void;
50
+ }
51
+
52
+ class SlidingDedupeWindow implements DedupeWindow {
53
+ private readonly windowSize: number;
54
+ /** key → revision, for window-bounded eviction. */
55
+ private readonly seen = new Map<string, number>();
56
+ private highest = -1;
57
+
58
+ constructor(windowSize: number) {
59
+ if (!Number.isInteger(windowSize) || windowSize < 1) {
60
+ throw new RangeError(`reactivity dedupe: windowSize must be an integer >= 1, got ${windowSize}`);
61
+ }
62
+ this.windowSize = windowSize;
63
+ }
64
+
65
+ get highestRevision(): number {
66
+ return this.highest;
67
+ }
68
+
69
+ get size(): number {
70
+ return this.seen.size;
71
+ }
72
+
73
+ has(revision: number, sigDigest: string): boolean {
74
+ return this.seen.has(keyOf(revision, sigDigest));
75
+ }
76
+
77
+ observe(revision: number, sigDigest: string): DedupeOutcome {
78
+ const key = keyOf(revision, sigDigest);
79
+ if (this.seen.has(key)) {
80
+ return "duplicate";
81
+ }
82
+ this.insert(key, revision);
83
+ return "forward";
84
+ }
85
+
86
+ serialize(): DedupeStateV1 {
87
+ return {
88
+ highestRevision: this.highest,
89
+ entries: [...this.seen].map(([key, rev]) => ({ key, revision: rev })),
90
+ };
91
+ }
92
+
93
+ merge(state: DedupeStateV1): void {
94
+ if (state.highestRevision > this.highest) {
95
+ this.highest = state.highestRevision;
96
+ }
97
+ for (const { key, revision } of state.entries) {
98
+ if (!this.seen.has(key)) {
99
+ this.seen.set(key, revision);
100
+ }
101
+ }
102
+ this.evictBelowWindow();
103
+ }
104
+
105
+ private insert(key: string, revision: number): void {
106
+ if (revision > this.highest) {
107
+ this.highest = revision;
108
+ }
109
+ this.seen.set(key, revision);
110
+ this.evictBelowWindow();
111
+ }
112
+
113
+ /** Retain only revisions within `[highest - windowSize + 1, highest]`. */
114
+ private evictBelowWindow(): void {
115
+ const low = this.highest - this.windowSize + 1;
116
+ for (const [key, revision] of this.seen) {
117
+ if (revision < low) {
118
+ this.seen.delete(key);
119
+ }
120
+ }
121
+ }
122
+ }
123
+
124
+ /** `${revision}:${sigDigest}` — the dedupe-set key. */
125
+ function keyOf(revision: number, sigDigest: string): string {
126
+ return `${revision}:${sigDigest}`;
127
+ }
128
+
129
+ /** Build a {@link DedupeWindow} with the configured (default {@link DEDUPE_WINDOW_DEFAULT}) span. */
130
+ export function createDedupeWindow(windowSize: number = DEDUPE_WINDOW_DEFAULT): DedupeWindow {
131
+ return new SlidingDedupeWindow(windowSize);
132
+ }