@optimystic/db-core 1.9.0 → 1.10.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 (117) hide show
  1. package/dist/src/cohort-topic/addressing.d.ts +46 -6
  2. package/dist/src/cohort-topic/addressing.d.ts.map +1 -1
  3. package/dist/src/cohort-topic/addressing.js +58 -18
  4. package/dist/src/cohort-topic/addressing.js.map +1 -1
  5. package/dist/src/cohort-topic/member-engine.d.ts +21 -1
  6. package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
  7. package/dist/src/cohort-topic/member-engine.js +39 -9
  8. package/dist/src/cohort-topic/member-engine.js.map +1 -1
  9. package/dist/src/cohort-topic/membership/publisher.js +1 -1
  10. package/dist/src/cohort-topic/membership/publisher.js.map +1 -1
  11. package/dist/src/cohort-topic/membership/source.d.ts +4 -0
  12. package/dist/src/cohort-topic/membership/source.d.ts.map +1 -1
  13. package/dist/src/cohort-topic/membership/source.js +4 -0
  14. package/dist/src/cohort-topic/membership/source.js.map +1 -1
  15. package/dist/src/cohort-topic/membership/verifier.d.ts +51 -9
  16. package/dist/src/cohort-topic/membership/verifier.d.ts.map +1 -1
  17. package/dist/src/cohort-topic/membership/verifier.js +138 -46
  18. package/dist/src/cohort-topic/membership/verifier.js.map +1 -1
  19. package/dist/src/cohort-topic/ports.d.ts +85 -14
  20. package/dist/src/cohort-topic/ports.d.ts.map +1 -1
  21. package/dist/src/cohort-topic/ports.js +1 -1
  22. package/dist/src/cohort-topic/ports.js.map +1 -1
  23. package/dist/src/cohort-topic/registration/renewal.d.ts +26 -5
  24. package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
  25. package/dist/src/cohort-topic/registration/renewal.js +71 -21
  26. package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
  27. package/dist/src/cohort-topic/service.d.ts +34 -2
  28. package/dist/src/cohort-topic/service.d.ts.map +1 -1
  29. package/dist/src/cohort-topic/service.js +86 -28
  30. package/dist/src/cohort-topic/service.js.map +1 -1
  31. package/dist/src/cohort-topic/sig/payloads.d.ts +5 -1
  32. package/dist/src/cohort-topic/sig/payloads.d.ts.map +1 -1
  33. package/dist/src/cohort-topic/sig/payloads.js +6 -1
  34. package/dist/src/cohort-topic/sig/payloads.js.map +1 -1
  35. package/dist/src/cohort-topic/sig/threshold.d.ts +29 -4
  36. package/dist/src/cohort-topic/sig/threshold.d.ts.map +1 -1
  37. package/dist/src/cohort-topic/sig/threshold.js +39 -7
  38. package/dist/src/cohort-topic/sig/threshold.js.map +1 -1
  39. package/dist/src/cohort-topic/walk.d.ts +19 -4
  40. package/dist/src/cohort-topic/walk.d.ts.map +1 -1
  41. package/dist/src/cohort-topic/walk.js +29 -6
  42. package/dist/src/cohort-topic/walk.js.map +1 -1
  43. package/dist/src/cohort-topic/willingness.d.ts +17 -1
  44. package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
  45. package/dist/src/cohort-topic/willingness.js +18 -3
  46. package/dist/src/cohort-topic/willingness.js.map +1 -1
  47. package/dist/src/cohort-topic/wire/index.d.ts +1 -1
  48. package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
  49. package/dist/src/cohort-topic/wire/index.js +1 -1
  50. package/dist/src/cohort-topic/wire/index.js.map +1 -1
  51. package/dist/src/cohort-topic/wire/payloads.d.ts +14 -0
  52. package/dist/src/cohort-topic/wire/payloads.d.ts.map +1 -1
  53. package/dist/src/cohort-topic/wire/payloads.js +20 -0
  54. package/dist/src/cohort-topic/wire/payloads.js.map +1 -1
  55. package/dist/src/cohort-topic/wire/primitives.d.ts +8 -0
  56. package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
  57. package/dist/src/cohort-topic/wire/primitives.js +24 -4
  58. package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
  59. package/dist/src/cohort-topic/wire/types.d.ts +37 -0
  60. package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
  61. package/dist/src/cohort-topic/wire/validate.d.ts +9 -1
  62. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  63. package/dist/src/cohort-topic/wire/validate.js +23 -4
  64. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  65. package/dist/src/reactivity/config.d.ts +9 -10
  66. package/dist/src/reactivity/config.d.ts.map +1 -1
  67. package/dist/src/reactivity/config.js +9 -9
  68. package/dist/src/reactivity/config.js.map +1 -1
  69. package/dist/src/reactivity/index.d.ts +4 -3
  70. package/dist/src/reactivity/index.d.ts.map +1 -1
  71. package/dist/src/reactivity/index.js +4 -3
  72. package/dist/src/reactivity/index.js.map +1 -1
  73. package/dist/src/reactivity/rotation.d.ts +73 -57
  74. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  75. package/dist/src/reactivity/rotation.js +54 -54
  76. package/dist/src/reactivity/rotation.js.map +1 -1
  77. package/dist/src/reactivity/subscription.d.ts +12 -9
  78. package/dist/src/reactivity/subscription.d.ts.map +1 -1
  79. package/dist/src/reactivity/subscription.js +9 -6
  80. package/dist/src/reactivity/subscription.js.map +1 -1
  81. package/dist/src/reactivity/topic-anchor.d.ts +36 -31
  82. package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
  83. package/dist/src/reactivity/topic-anchor.js +41 -39
  84. package/dist/src/reactivity/topic-anchor.js.map +1 -1
  85. package/dist/src/reactivity/verify.d.ts +26 -9
  86. package/dist/src/reactivity/verify.d.ts.map +1 -1
  87. package/dist/src/reactivity/verify.js +26 -11
  88. package/dist/src/reactivity/verify.js.map +1 -1
  89. package/dist/src/reactivity/wire.d.ts +1 -1
  90. package/dist/src/reactivity/wire.d.ts.map +1 -1
  91. package/dist/src/transactor/change-notifier.d.ts +1 -1
  92. package/package.json +1 -1
  93. package/src/cohort-topic/addressing.ts +83 -23
  94. package/src/cohort-topic/member-engine.ts +77 -8
  95. package/src/cohort-topic/membership/publisher.ts +1 -1
  96. package/src/cohort-topic/membership/source.ts +4 -0
  97. package/src/cohort-topic/membership/verifier.ts +169 -51
  98. package/src/cohort-topic/ports.ts +87 -15
  99. package/src/cohort-topic/registration/renewal.ts +87 -24
  100. package/src/cohort-topic/service.ts +157 -35
  101. package/src/cohort-topic/sig/payloads.ts +7 -2
  102. package/src/cohort-topic/sig/threshold.ts +41 -7
  103. package/src/cohort-topic/walk.ts +46 -9
  104. package/src/cohort-topic/willingness.ts +34 -3
  105. package/src/cohort-topic/wire/index.ts +1 -0
  106. package/src/cohort-topic/wire/payloads.ts +21 -0
  107. package/src/cohort-topic/wire/primitives.ts +26 -4
  108. package/src/cohort-topic/wire/types.ts +37 -0
  109. package/src/cohort-topic/wire/validate.ts +26 -3
  110. package/src/reactivity/config.ts +10 -10
  111. package/src/reactivity/index.ts +4 -3
  112. package/src/reactivity/rotation.ts +86 -78
  113. package/src/reactivity/subscription.ts +12 -9
  114. package/src/reactivity/topic-anchor.ts +42 -45
  115. package/src/reactivity/verify.ts +36 -17
  116. package/src/reactivity/wire.ts +1 -1
  117. package/src/transactor/change-notifier.ts +1 -1
@@ -13,7 +13,9 @@
13
13
  * - **{@link UnwillingCohortOutcome}** — fewer than a quorum of members are willing to serve the
14
14
  * tier, so the cohort declines the tier entirely; the caller backs off in *time* (no spatial
15
15
  * move — see §Why the caller doesn't walk on UnwillingCohort). The `retryAfterMs` follows the
16
- * capped-doubling curve in {@link backoffRetryMs}.
16
+ * capped-doubling curve in {@link backoffRetryMs}. The outcome also says whether the quorum is short
17
+ * only for want of members that have not gossiped yet (`awaitingMembers`), which the member engine
18
+ * answers by holding the request for their gossip rather than declining at once.
17
19
  *
18
20
  * A member's *live* willingness for a tier is: its profile serves the tier, the tier's load bucket
19
21
  * is below `overloadBucket`, **and** it is under its per-tier primary-topic budget. The coarse 1-bit
@@ -43,6 +45,14 @@ export interface UnwillingMemberOutcome {
43
45
  export interface UnwillingCohortOutcome {
44
46
  readonly kind: "unwilling_cohort";
45
47
  readonly retryAfterMs: number;
48
+ /**
49
+ * True iff the quorum is short only because cohort members have not gossiped yet: it would be met if
50
+ * every member this check holds no contribution from turned out willing. A member that has gossiped
51
+ * *unwilling* counts as heard, so a cohort whose answers are in and short reports `false` — as does an
52
+ * unserviceable tier, and a check given no {@link WillingnessDeps.cohortMembers}. The cohort side may hold
53
+ * the request briefly for those answers instead of declining (§Cold-start instantiation).
54
+ */
55
+ readonly awaitingMembers: boolean;
46
56
  }
47
57
 
48
58
  export type WillingnessOutcome = AcceptedOutcome | UnwillingMemberOutcome | UnwillingCohortOutcome;
@@ -146,6 +156,12 @@ export interface WillingnessDeps {
146
156
  view: CohortView;
147
157
  /** This member's own id, base64url (the `fromMember` key) — excluded from the sibling scan. */
148
158
  selfMember: string;
159
+ /**
160
+ * The cohort's current members, base64url (the form {@link selfMember} and the view keys use), read at
161
+ * each evaluation. It tells a member that has not gossiped yet apart from one that gossiped unwilling
162
+ * ({@link UnwillingCohortOutcome.awaitingMembers}). Absent → no member counts as unheard.
163
+ */
164
+ cohortMembers?: () => readonly string[];
149
165
  /** Count of topics this member is already `primary` for at `tier` (the budget gate input). */
150
166
  primaryTopicCount: (tier: Tier) => number;
151
167
  /**
@@ -182,7 +198,7 @@ class GossipWillingnessCheck implements WillingnessCheck {
182
198
  const tier = reg.tier as Tier;
183
199
  if (!ALL_TIERS.includes(tier)) {
184
200
  // An op tier outside T0..T3 is not serviceable; treat as a cohort-level decline.
185
- return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff) };
201
+ return this.declineCohort(reg, false);
186
202
  }
187
203
 
188
204
  const selfWilling = this.selfLiveWilling(self, tier);
@@ -192,7 +208,7 @@ class GossipWillingnessCheck implements WillingnessCheck {
192
208
  // Quorum gate (§Tier ladder): the cohort takes on tier-T duties only if a quorum of members
193
209
  // is willing; otherwise registrations get UnwillingCohort and the caller backs off in time.
194
210
  if (willingCount < this.quorum) {
195
- return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff) };
211
+ return this.declineCohort(reg, willingCount + this.unheardMemberCount() >= this.quorum);
196
212
  }
197
213
  if (selfWilling) {
198
214
  return { kind: "accepted" };
@@ -201,6 +217,21 @@ class GossipWillingnessCheck implements WillingnessCheck {
201
217
  return { kind: "unwilling_member", candidateMembers: siblings.map((m) => b64urlToBytes(m)) };
202
218
  }
203
219
 
220
+ private declineCohort(reg: RegisterV1, awaitingMembers: boolean): UnwillingCohortOutcome {
221
+ return { kind: "unwilling_cohort", retryAfterMs: backoffRetryMs(this.attempts(reg), this.backoff), awaitingMembers };
222
+ }
223
+
224
+ /** Cohort members other than self this check holds no gossiped contribution from. */
225
+ private unheardMemberCount(): number {
226
+ const unheard = new Set<string>();
227
+ for (const member of this.deps.cohortMembers?.() ?? []) {
228
+ if (member !== this.deps.selfMember && this.deps.view.get(member) === undefined) {
229
+ unheard.add(member);
230
+ }
231
+ }
232
+ return unheard.size;
233
+ }
234
+
204
235
  /** Live willingness of *this* member for `tier`: profile ∧ load-under-threshold ∧ under budget. */
205
236
  private selfLiveWilling(self: NodeProfile, tier: Tier): boolean {
206
237
  return (
@@ -3,6 +3,7 @@ export * from "./codec.js";
3
3
  export * from "./payloads.js";
4
4
  export { CohortWireError } from "./validate.js";
5
5
  export {
6
+ MAX_ROOT_KEY_BYTES,
6
7
  validateRegisterV1,
7
8
  validateRegisterReplyV1,
8
9
  validateRenewV1,
@@ -13,6 +13,12 @@
13
13
  * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
14
14
  * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
15
15
  * optional can never disagree across the wire round-trip.
16
+ *
17
+ * The root-placement fields (`RegisterV1.rootKey`, `CohortGossipV1.rootPlaced`) are the exception: each
18
+ * is appended to its image **only when present**, with no placeholder. A frame without the field
19
+ * therefore signs exactly the bytes it signed before the field existed, and the two forms cannot be
20
+ * confused — they differ in array length, and neither field has a "present but default" spelling (the
21
+ * validator rejects an empty `rootKey` and a `rootPlaced` other than `true`).
16
22
  */
17
23
 
18
24
  import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
@@ -53,9 +59,21 @@ export function registerSigningPayload(body: RegisterSignable): Uint8Array {
53
59
  // signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
54
60
  // signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
55
61
  body.followOn ?? false,
62
+ // The root key of a root-placed topic, appended only when present: a frame without one keeps the
63
+ // image above byte-for-byte, and stripping or swapping the key changes the image and fails verify.
64
+ ...presentOnly(body.rootKey),
56
65
  ]));
57
66
  }
58
67
 
68
+ /**
69
+ * `[value]` when the optional field is present, `[]` when absent — spread into a signed image for an optional
70
+ * element with no placeholder, so a frame without the field keeps the image it signed before the field existed.
71
+ * Shared with the threshold-signature images in `sig/payloads.ts`.
72
+ */
73
+ export function presentOnly<T>(value: T | undefined): T[] {
74
+ return value === undefined ? [] : [value];
75
+ }
76
+
59
77
  /** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
60
78
  export function renewSigningPayload(body: RenewSignable): Uint8Array {
61
79
  return utf8.encode(JSON.stringify([
@@ -86,6 +104,8 @@ export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
86
104
  * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
87
105
  * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
88
106
  * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
107
+ * `rootPlaced` is appended after `timestamp` only when present, so a gossip for a default-addressed coord
108
+ * keeps its image unchanged and the flag cannot be added to, or removed from, a signed frame.
89
109
  */
90
110
  export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
91
111
  return utf8.encode(JSON.stringify([
@@ -122,5 +142,6 @@ export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array
122
142
  (g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
123
143
  (g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
124
144
  g.timestamp,
145
+ ...presentOnly(g.rootPlaced),
125
146
  ]));
126
147
  }
@@ -121,6 +121,22 @@ export function optBool(obj: Record<string, unknown>, key: string, what: string)
121
121
  return value;
122
122
  }
123
123
 
124
+ /**
125
+ * Return `true` when `obj[key]` is literally `true`, `undefined` when absent; throw on anything else —
126
+ * `false` included. For a presence flag whose only legal value is `true`, so an absent flag and a
127
+ * `false` one cannot be two spellings of the same thing in a signed image.
128
+ */
129
+ export function optTrue(obj: Record<string, unknown>, key: string, what: string): true | undefined {
130
+ const value = obj[key];
131
+ if (value === undefined) {
132
+ return undefined;
133
+ }
134
+ if (value !== true) {
135
+ failWire(`${what}: field "${key}" must be true when present`);
136
+ }
137
+ return true;
138
+ }
139
+
124
140
  /**
125
141
  * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
126
142
  * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
@@ -180,16 +196,22 @@ export function b64urlField(value: string, key: string, what: string): string {
180
196
  return value;
181
197
  }
182
198
 
183
- /** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
184
- export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
199
+ /** Assert a base64url string decodes cleanly to between `min` and `max` bytes inclusive; returns it unchanged. */
200
+ export function b64urlBoundedLen(value: string, key: string, min: number, max: number, what: string): string {
185
201
  let bytes: Uint8Array;
186
202
  try {
187
203
  bytes = b64urlToBytes(value);
188
204
  } catch {
189
205
  return failWire(`${what}: field "${key}" is not valid base64url`);
190
206
  }
191
- if (bytes.length !== len) {
192
- failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
207
+ if (bytes.length < min || bytes.length > max) {
208
+ const expected = min === max ? `${min}` : `${min}..${max}`;
209
+ failWire(`${what}: field "${key}" must decode to ${expected} bytes, got ${bytes.length}`);
193
210
  }
194
211
  return value;
195
212
  }
213
+
214
+ /** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
215
+ export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
216
+ return b64urlBoundedLen(value, key, len, len, what);
217
+ }
@@ -67,6 +67,16 @@ export interface RegisterV1 {
67
67
  * absent (it normalizes to the same signed-image placeholder as an absent field).
68
68
  */
69
69
  bootstrapEvidence?: string;
70
+ /**
71
+ * Root key of a **root-placed** topic, base64url of the raw key bytes (1..`MAX_ROOT_KEY_BYTES`) — for
72
+ * reactivity, the routing key of the collection's log tail block. When present the topic's tier-0
73
+ * coordinate is `H(rootKey)` instead of `H(0x00 ‖ topicId)` (§Tier addressing → Root placement at a
74
+ * routing key). Set on **every** tier's frame of such a topic, not only the root's: tiers `d ≥ 1` keep
75
+ * their usual coordinate, but a tier-1 cohort needs the key to find its parent. Absent for every topic
76
+ * that uses the default addressing. Covered by `signature` (appended to `registerSigningPayload` only
77
+ * when present) so a MITM cannot strip or swap it.
78
+ */
79
+ rootKey?: string;
70
80
  /** Unix ms. */
71
81
  timestamp: number;
72
82
  /** 16 random bytes, base64url. */
@@ -197,6 +207,13 @@ export interface ChildLinkV1 {
197
207
  signers: string[];
198
208
  /** Child cohort epoch, 32 bytes base64url (the epoch the threshold sig was collected under). */
199
209
  cohortEpoch: string;
210
+ /**
211
+ * Root key of a root-placed topic (see {@link RegisterV1.rootKey}), base64url. Set by a **tier-1** child
212
+ * of such a topic so its parent — the root, which sits at `H(rootKey)` rather than `coord_0(topicId)` —
213
+ * can recompute its own served coord when binding the parent-child relationship. Absent otherwise.
214
+ * Covered by the child cohort's threshold signature (`childLinkSigningPayload`, only when present).
215
+ */
216
+ rootKey?: string;
200
217
  }
201
218
 
202
219
  /** Parent → child ack. `linked` flips the child `awaiting_parent → serving`; `rejected` keeps it awaiting. */
@@ -363,6 +380,13 @@ export interface CohortGossipV1 {
363
380
  * converges to unlinked regardless of arrival order.
364
381
  */
365
382
  childUnlinks?: ChildLinkRefV1[];
383
+ /**
384
+ * Present (and literally `true`) when {@link coord} is the root of a root-placed topic. It tells a
385
+ * co-member that has no engine for the coord yet to derive the **root group** around it rather than the
386
+ * FRET cohort (§Tier addressing → Root placement at a routing key). Absent for every other coord.
387
+ * Covered by {@link signature} when present.
388
+ */
389
+ rootPlaced?: true;
366
390
  timestamp: number;
367
391
  signature: string;
368
392
  }
@@ -410,6 +434,19 @@ export interface SignRequestV1 {
410
434
  cohortEpoch: string;
411
435
  /** The already-canonical signing bytes (the requester's `sig/payloads.ts` image), base64url. */
412
436
  payload: string;
437
+ /**
438
+ * Present (and literally `true`) when `coord` is the root of a root-placed topic, so an endorser with no
439
+ * engine for the coord derives the root group around it rather than the FRET cohort. The request is not
440
+ * itself signed, so the flag is forgeable — harmlessly: the endorser still applies its own member and
441
+ * epoch checks against the group it derives, and a signature set collected from a root group has at
442
+ * most that group's size, which falls short of the default threshold a verifier applies to a coord it
443
+ * was not told is root-placed (a storage group is smaller than the default `minSigs` of 14).
444
+ *
445
+ * NOTE: that last step rests on `clusterSize` (default 10) staying below `DEFAULT_MIN_SIGS` (14). A
446
+ * deployment whose storage groups reach 14 members loses it; sign the request (or fold the flag into the
447
+ * endorsed payload) before raising `clusterSize` that far.
448
+ */
449
+ rootPlaced?: true;
413
450
  }
414
451
 
415
452
  /** A member's endorsement of a {@link SignRequestV1}: its peer-key signature over the request payload. */
@@ -12,6 +12,7 @@ import { DEFAULT_D_MAX_CAP } from "../dmax.js";
12
12
  import {
13
13
  assignDefined,
14
14
  asObject,
15
+ b64urlBoundedLen,
15
16
  b64urlField,
16
17
  b64urlFixedLen,
17
18
  COORD_BYTES,
@@ -20,6 +21,7 @@ import {
20
21
  optFiniteNumber,
21
22
  optString,
22
23
  optStringArray,
24
+ optTrue,
23
25
  reqBool,
24
26
  reqEnum,
25
27
  reqFiniteNumber,
@@ -79,6 +81,20 @@ function treeTier(value: number, what: string): number {
79
81
  /** Correlation-id byte width (a 16-byte nonce minted per walk probe / renew). */
80
82
  const CORRELATION_BYTES = 16;
81
83
 
84
+ /**
85
+ * Ceiling on a decoded `rootKey` (the root key of a root-placed topic). A root key is a block's routing
86
+ * key — the UTF-8 of its block id, 43 bytes for a generated id — so 256 leaves room for a named block
87
+ * while keeping a hostile frame from carrying an arbitrarily large key into a hash input and a stored
88
+ * per-engine field.
89
+ */
90
+ export const MAX_ROOT_KEY_BYTES = 256;
91
+
92
+ /** Validate an optional `rootKey`: base64url of 1..{@link MAX_ROOT_KEY_BYTES} bytes, or absent. */
93
+ function optRootKey(obj: Record<string, unknown>, what: string): string | undefined {
94
+ const rootKey = optString(obj, "rootKey", what);
95
+ return rootKey === undefined ? undefined : b64urlBoundedLen(rootKey, "rootKey", 1, MAX_ROOT_KEY_BYTES, what);
96
+ }
97
+
82
98
  const REGISTER_RESULTS: readonly RegisterResult[] = [
83
99
  "accepted",
84
100
  "no_state",
@@ -136,6 +152,7 @@ export function validateRegisterV1(value: unknown): RegisterV1 {
136
152
  if (bootstrapEvidence !== undefined && bootstrapEvidence !== "") {
137
153
  out.bootstrapEvidence = b64urlField(bootstrapEvidence, "bootstrapEvidence", what);
138
154
  }
155
+ assignDefined(out, "rootKey", optRootKey(obj, what));
139
156
  return out;
140
157
  }
141
158
 
@@ -259,7 +276,8 @@ export function validateDemotionNoticeV1(value: unknown): DemotionNoticeV1 {
259
276
  * coord is not always 32 raw bytes, e.g. a multihash-encoded peer id in tests). When `minSigs`
260
277
  * is supplied AND the frame carries a threshold signature (`thresholdSig` non-empty), `signers.length` must
261
278
  * be `>= minSigs`; a key-less-interim frame carries neither, so that cross-field bound is skipped. `minSigs`
262
- * is optional so a bare structural decode (no quorum context) still narrows the frame.
279
+ * is optional so a bare structural decode (no quorum context) still narrows the frame. An optional
280
+ * `rootKey` (a tier-1 child of a root-placed topic) is bounded to 1..{@link MAX_ROOT_KEY_BYTES} bytes.
263
281
  */
264
282
  export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLinkV1 {
265
283
  const what = "ChildLinkV1";
@@ -274,7 +292,7 @@ export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLink
274
292
  if (minSigs !== undefined && thresholdSig.length > 0 && signers.length < minSigs) {
275
293
  fail(`${what}: a signed child-link needs signers.length >= ${minSigs}, got ${signers.length}`);
276
294
  }
277
- return {
295
+ const out: ChildLinkV1 = {
278
296
  v: 1,
279
297
  topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
280
298
  childCohortCoord: b64urlFixedLen(reqString(obj, "childCohortCoord", what), "childCohortCoord", COORD_BYTES, what),
@@ -286,6 +304,8 @@ export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLink
286
304
  signers,
287
305
  cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
288
306
  };
307
+ assignDefined(out, "rootKey", optRootKey(obj, what));
308
+ return out;
289
309
  }
290
310
 
291
311
  /** Validate a {@link ChildLinkReplyV1}: `result` in `linked | rejected`, optional human-readable `reason`. */
@@ -424,6 +444,7 @@ export function validateCohortGossipV1(value: unknown): CohortGossipV1 {
424
444
  }
425
445
  out.childUnlinks = childUnlinks.map(validateChildLinkRefV1);
426
446
  }
447
+ assignDefined(out, "rootPlaced", optTrue(obj, "rootPlaced", what));
427
448
  return out;
428
449
  }
429
450
 
@@ -433,13 +454,15 @@ export function validateSignRequestV1(value: unknown): SignRequestV1 {
433
454
  const what = "SignRequestV1";
434
455
  const obj = asObject(value, what);
435
456
  requireV1(obj, what);
436
- return {
457
+ const out: SignRequestV1 = {
437
458
  v: 1,
438
459
  kind: reqEnum(obj, "kind", SIGN_KINDS, what),
439
460
  coord: b64urlFixedLen(reqString(obj, "coord", what), "coord", COORD_BYTES, what),
440
461
  cohortEpoch: b64urlFixedLen(reqString(obj, "cohortEpoch", what), "cohortEpoch", COORD_BYTES, what),
441
462
  payload: b64urlField(reqString(obj, "payload", what), "payload", what),
442
463
  };
464
+ assignDefined(out, "rootPlaced", optTrue(obj, "rootPlaced", what));
465
+ return out;
443
466
  }
444
467
 
445
468
  export function validateSignReplyV1(value: unknown): SignReplyV1 {
@@ -6,8 +6,8 @@
6
6
  * simulator fold-back ([fold-simulator-findings-into-design-docs]) can retune `W` / `dedupe_window`
7
7
  * without touching origination, forwarding, the replay buffer, or delivery.
8
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],
9
+ * **Simulator-validated-pending.** `W` (replay buffer depth), `dedupe_window`, `T_drain` and `queue_max`
10
+ * are *provisional* pending the design simulator ([simulator-reactivity-replay],
11
11
  * folded back by [fold-simulator-findings-into-design-docs]). The simulator's REVISED guidance is that `W`
12
12
  * SHOULD become adaptive per measured commit-rate on hot collections (`W ≈ ⌈min_coverage × cps⌉`); the
13
13
  * static `W = 256` is kept as the Edge/low-rate default. {@link resolveW} exposes that hook; the
@@ -24,6 +24,7 @@
24
24
 
25
25
  import type { NodeProfile } from "../cohort-topic/tiers.js";
26
26
  import { DEFAULT_T_REJOIN_JITTER_MS } from "../cohort-topic/antiflood/jitter.js";
27
+ import { EntriesPerBlock } from "../chain/chain.js";
27
28
 
28
29
  /** Replay buffer depth (revisions per cohort, per collection). Simulator-validated-pending. */
29
30
  export const W_DEFAULT = 256;
@@ -41,13 +42,12 @@ export const DELTA_MAX_EDGE_BYTES = 0;
41
42
  export const SUBSCRIBER_TTL_CORE_MS = 90_000;
42
43
  /** Subscriber registration TTL on an Edge node (ms), inherited from cohort-topic. */
43
44
  export const SUBSCRIBER_TTL_EDGE_MS = 60_000;
44
- /** Transactions per block — drives tail rotation. Simulator-validated-pending.
45
- *
46
- * NOTE: the collection log starts a new tail block every `EntriesPerBlock` (32) entries
47
- * (`chain/chain.ts`), not every 64, so on a live node the fill tracker's warm-up and filling signals
48
- * fire at the wrong commit counts. Harmless while those signals are only logged; reconcile the two
49
- * numbers before anything on a live node acts on them. */
50
- export const BLOCK_FILL_SIZE_DEFAULT = 64;
45
+ /**
46
+ * Entries per log block — drives tail rotation. The collection log starts a new tail block every
47
+ * `EntriesPerBlock` entries (`chain/chain.ts`), so this is that number, not a tunable of its own: the fill
48
+ * tracker's warm-up and filling signals fire at the commit counts the log actually rotates at.
49
+ */
50
+ export const BLOCK_FILL_SIZE_DEFAULT = EntriesPerBlock;
51
51
  /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
52
52
  export const T_DRAIN_MS = 60_000;
53
53
  /** Transactions remaining in tail before anticipatory warm-up. Owned by the rotation ticket. */
@@ -73,7 +73,7 @@ export interface ReactivityConfig {
73
73
  readonly subscriberTtlCoreMs: number;
74
74
  /** Subscriber TTL on an Edge node (ms). */
75
75
  readonly subscriberTtlEdgeMs: number;
76
- /** Transactions per block — drives tail rotation. Simulator-validated-pending. */
76
+ /** Entries per log block — drives tail rotation; the log's `EntriesPerBlock`. */
77
77
  readonly blockFillSize: number;
78
78
  /** Old-tail drain time after rotation (ms). Simulator-validated-pending. */
79
79
  readonly tDrainMs: number;
@@ -1,9 +1,10 @@
1
1
  /**
2
2
  * Reactivity — push-based change notifications on the cohort-topic substrate.
3
3
  *
4
- * See `docs/reactivity.md`. This module lands the reactivity hot path — the rotating tail-anchored topic,
5
- * the subscribe `appPayload`, notification origination (reusing the commit cert unchanged), the forwarder
6
- * receive path (verify → dedupe → buffer → forward), the `W`-entry replay ring with cohort gossip, the
4
+ * See `docs/reactivity.md`. This module lands the reactivity hot path — the collection anchor (one topic per
5
+ * collection, a root at the tail block's storage group), the subscribe `appPayload`, notification
6
+ * origination (reusing the commit cert unchanged), the forwarder receive path (verify → dedupe → buffer →
7
+ * forward), the `W`-entry replay ring with cohort gossip, the
7
8
  * sliding `(revision, sigDigest)` dedupe window, and subscriber-side verify/deliver with gap detection
8
9
  * ([reactivity-origination-replay-delivery]) — plus **recovery beyond the live stream**
9
10
  * ([reactivity-backfill-resume-checkpoints]): the {@link ./backfill.js} RPC served from the replay ring,