@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
@@ -1,49 +1,47 @@
1
1
  /**
2
- * Reactivity — tail rotation lifecycle (`docs/reactivity.md` §Rotating tail anchor, §Tail rotation).
2
+ * Reactivity — tail rotation lifecycle (`docs/reactivity.md` §Anchor, §Tail rotation).
3
3
  *
4
- * `topicId = H(tailId ‖ "reactivity")` is derived per emission ({@link reactivityTopicId}). When the tail
5
- * block fills (`block_fill_size` transactions, default 64) a new tail block is born and `tailId` — hence
6
- * `topicId` — changes; the cohort-topic layer treats the new `topicId` as an **entirely new topic** (fresh
7
- * tree, new ring coord). Reactivity manages the subscriber/replay-state migration explicitly. This module
8
- * owns that lifecycle:
4
+ * A collection's topic is stable (`reactivityCollectionTopicId`, `topic-anchor.ts`); what rotates is its
5
+ * **root**. When the tail block fills (`block_fill_size` entries, the log's `EntriesPerBlock`) a new tail
6
+ * block is born and the root — the tail's storage group at `H(tailId)` — moves to the new tail's group. The
7
+ * tiers below the root sit at `coord_d(P, topicId)` and never move, so a rotation is "same topic, the root
8
+ * moved": a registration at the root re-registers under the new root key; one below the root keeps its place
9
+ * and only updates the root key a later re-walk would use (`CohortTopicService.moveRoot`). This module owns
10
+ * the subscriber- and root-side lifecycle around that move:
9
11
  *
10
12
  * - **Pre-announce** — the block-filling commit's notification carries {@link RotationHintV1}; built here
11
13
  * by {@link buildRotationHint} and detected subscriber-side by {@link detectRotation}.
12
14
  * - **Block-fill tracking** — {@link BlockFillTracker} counts transactions in the current tail block and
13
15
  * fires anticipatory **warm-up** at `block_fill_size − warm_threshold` and the **filling** signal at
14
16
  * `block_fill_size` (the commit that carries the hint).
15
- * - **Drain** — {@link TailDrainGate} keeps the outgoing tail serving renewals/replays for `T_drain` while
16
- * bouncing *new* subscriptions with a `Promoted`-shaped {@link RotationRedirectV1} to the new tree.
17
+ * - **Drain** — {@link TailDrainGate} keeps the outgoing root serving renewals/replays for `T_drain` while
18
+ * bouncing *new* subscriptions with a `Promoted`-shaped {@link RotationRedirectV1} naming the new tail.
17
19
  * - **Jittered re-registration** — {@link planReRegistration} / {@link planReRegistrationWave} schedule a
18
- * subscriber's move to the new `topicId` over `T_rejoin_jitter` (the cohort-topic {@link RejoinJitter}),
20
+ * subscriber's follow of the new tail over `T_rejoin_jitter` (the cohort-topic {@link RejoinJitter}),
19
21
  * carrying its existing `lastRevision` (revisions are continuous across rotations).
20
- * - **Buffer-to-checkpoint handoff** — {@link buildRotationHandoffCheckpoint} folds the outgoing tail's
22
+ * - **Buffer-to-checkpoint handoff** — {@link buildRotationHandoffCheckpoint} folds the outgoing root's
21
23
  * replay buffer into a final {@link CheckpointSummary} covering `[lastCheckpoint.toRevision + 1,
22
24
  * rotationRevision]`, the **only** state migrated across a rotation; {@link applyRotationHandoff} lands it
23
- * at the new tail so a `ResumeV1` spanning the rotation is recoverable.
25
+ * at the new root so a `ResumeV1` spanning the rotation is recoverable.
24
26
  *
25
- * Forwarder draining is *emergent*: forwarders under the old tail watch their direct-subscriber count drop
26
- * as subscribers re-register elsewhere and demote naturally per the cohort-topic demotion protocol (no
27
- * state migrates; the new tree rebuilds via re-registration). It needs no code here.
27
+ * Tiers below the root do not drain on a rotation: only the old root stops receiving commits and releases its
28
+ * state after `T_drain`. It needs no code here.
28
29
  *
29
30
  * Coordination with [reactivity-backfill-resume-checkpoints]: that ticket owns the `ResumeReplyV1.TailRotated`
30
- * variant and the `latestKnownTailId`-staleness classification; this ticket produces the handoff checkpoint
31
- * and the rotation *condition*. The new tail's {@link PushState.inheritedCheckpoint} (set by
31
+ * variant and the `latestKnownTailId`-staleness classification; this module produces the handoff checkpoint
32
+ * and the rotation *condition*. The new root's {@link PushState.inheritedCheckpoint} (set by
32
33
  * {@link applyRotationHandoff}) is the seam the resume classifier consults to answer a checkpoint-window
33
- * resume whose span crosses the rotation: `classifyResume`/`serveResume` now read it (after the rolling
34
+ * resume whose span crosses the rotation: `classifyResume`/`serveResume` read it (after the rolling
34
35
  * `checkpoint` misses) and serve the inherited summary, so a cross-rotation resume no longer falls to
35
36
  * `out_of_window` (`docs/reactivity.md` §Resume, §Tail rotation step 5). The drain-window redirect a new
36
37
  * subscription receives, {@link RotationRedirectV1}, is serialized by {@link validateRotationRedirectV1} and
37
38
  * rides the recover reply envelope as `kind: "rotated"` ({@link import("./recover.js").RecoverReplyV1}).
38
39
  */
39
40
 
40
- import { bytesToB64url, b64urlToBytes } from "../cohort-topic/wire/codec.js";
41
- import { createRingHash } from "../cohort-topic/ring-hash.js";
42
- import type { IRingHash } from "../cohort-topic/ports.js";
41
+ import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
43
42
  import type { RejoinJitter } from "../cohort-topic/antiflood/jitter.js";
44
43
  import { BLOCK_FILL_SIZE_DEFAULT, T_DRAIN_MS, WARM_THRESHOLD_DEFAULT } from "./config.js";
45
44
  import { buildCheckpointSummary, type CheckpointSummary } from "./checkpoint.js";
46
- import { reactivityTopicId } from "./topic-anchor.js";
47
45
  import type { PushState } from "./push-state.js";
48
46
  import type { NotificationV1, RotationHintV1 } from "./wire.js";
49
47
  import { asObject, b64urlField, failWire, reqIntInRange, reqString, requireV1 } from "./wire-validate.js";
@@ -62,30 +60,52 @@ export function buildRotationHint(newTailId: string, fillingRevision: number): R
62
60
 
63
61
  /** The subscriber-side rotation verdict for one delivered notification. */
64
62
  export interface RotationDetection {
65
- /** True iff the subscriber's tree has rotated (delivered tail differs) or a rotation is pre-announced. */
63
+ /** True iff the subscriber's root has moved (delivered tail differs, at a newer revision) or a rotation is pre-announced. */
66
64
  readonly rotated: boolean;
67
65
  /** The tail id to re-register under, base64url — present iff `rotated`. */
68
66
  readonly newTailId?: string;
69
67
  /**
70
- * True iff this is a **pre-announce**: the delivered `tailId` still matches `tailIdAtAttach`, but the
71
- * notification's `rotationHint.newTailId` names a different successor. (False when the delivered tail
72
- * already differs — the tree has *already* migrated.)
68
+ * True iff this is a **pre-announce**: the delivered `tailId` still matches the tail the subscriber follows,
69
+ * but the notification's `rotationHint.newTailId` names a different successor. (False when the delivered
70
+ * tail already differs — the root has *already* moved.)
73
71
  */
74
72
  readonly preAnnounced: boolean;
75
73
  }
76
74
 
75
+ /** What a subscriber knows of the collection's log when a notification arrives, for {@link detectRotation}. */
76
+ export interface FollowedTail {
77
+ /** The latest tail the subscriber has followed, base64url. */
78
+ readonly tailId: string;
79
+ /**
80
+ * The newest revision the subscriber has seen: delivered or verified from a notification, replayed by a
81
+ * backfill or resume, or read from the log by its host. Revisions are allocated in order and the tail only
82
+ * moves forward, so no revision at or below it was announced at a tail newer than the newest tail the
83
+ * subscriber has seen a notification for.
84
+ */
85
+ readonly newestRevision: number;
86
+ }
87
+
77
88
  /**
78
- * Detect tail rotation for a subscriber attached at `tailIdAtAttach` (base64url) from a delivered
79
- * notification. Rotation is signaled when the delivered `tailId` **or** the `rotationHint.newTailId`
80
- * differs from `tailIdAtAttach` (`docs/reactivity.md` §Rotating tail anchor). An already-rotated delivery
81
- * (different `tailId`) takes precedence over a pre-announce.
89
+ * Detect tail rotation for a subscriber following `followed.tailId` from a delivered notification. Rotation
90
+ * is signaled when the delivered `tailId` **or** the `rotationHint.newTailId` differs from it
91
+ * (`docs/reactivity.md` §Tail rotation). An already-rotated delivery (different `tailId`) takes precedence
92
+ * over a pre-announce.
93
+ *
94
+ * A differing `tailId` at a revision at or below `followed.newestRevision` is **not** a rotation: the
95
+ * notification was announced at a tail the subscriber has already moved past. The old and the new root are
96
+ * different machines delivering independently, so the last notification announced at the old tail can arrive
97
+ * after the subscriber followed the new one; without the revision check it would read as a rotation back to
98
+ * the old tail and cost a registration at a root that announces nothing further.
82
99
  */
83
- export function detectRotation(tailIdAtAttach: string, n: Pick<NotificationV1, "tailId" | "rotationHint">): RotationDetection {
84
- if (n.tailId !== tailIdAtAttach) {
85
- // The delivered notification rides the *new* tree already — a hard rotation, not a pre-announce.
100
+ export function detectRotation(followed: FollowedTail, n: Pick<NotificationV1, "tailId" | "rotationHint" | "revision">): RotationDetection {
101
+ if (n.tailId !== followed.tailId) {
102
+ if (n.revision <= followed.newestRevision) {
103
+ return { rotated: false, preAnnounced: false };
104
+ }
105
+ // The delivered notification was announced at the *new* root already — a hard rotation, not a pre-announce.
86
106
  return { rotated: true, newTailId: n.tailId, preAnnounced: false };
87
107
  }
88
- if (n.rotationHint !== undefined && n.rotationHint.newTailId !== tailIdAtAttach) {
108
+ if (n.rotationHint !== undefined && n.rotationHint.newTailId !== followed.tailId) {
89
109
  return { rotated: true, newTailId: n.rotationHint.newTailId, preAnnounced: true };
90
110
  }
91
111
  return { rotated: false, preAnnounced: false };
@@ -111,7 +131,7 @@ export type BlockFillSignal =
111
131
 
112
132
  /** Construction inputs for a {@link BlockFillTracker}. */
113
133
  export interface BlockFillTrackerInit {
114
- /** Transactions per block before the tail rotates (default {@link BLOCK_FILL_SIZE_DEFAULT}). */
134
+ /** Entries per log block before the tail rotates (default {@link BLOCK_FILL_SIZE_DEFAULT}, the log's `EntriesPerBlock`). */
115
135
  readonly blockFillSize?: number;
116
136
  /** Transactions remaining in the tail when anticipatory warm-up fires (default {@link WARM_THRESHOLD_DEFAULT}). */
117
137
  readonly warmThreshold?: number;
@@ -186,16 +206,17 @@ export type DrainOp =
186
206
  | "replay";
187
207
 
188
208
  /**
189
- * A `Promoted`-shaped redirect to the rotated tree (`docs/reactivity.md` §Tail rotation step 2). Unlike the
190
- * cohort-topic tier-based `Promoted`, this redirects to an entirely **new topic** — the new tail's tree at
191
- * `coord_0(_, newTopicId)` — so it carries the successor's `newTailId` + derived `newTopicId`.
209
+ * A `Promoted`-shaped redirect to the moved root (`docs/reactivity.md` §Tail rotation step 2). Unlike the
210
+ * cohort-topic tier-based `Promoted`, this redirects to the same topic's **new root** — the new tail's storage
211
+ * group at `H(newTailId)` — so a receiver acts on `newTailId`. `newTopicId` stays on the wire and carries the
212
+ * collection's unchanged topic (the field predates the stable topic; it is not a redirect target).
192
213
  */
193
214
  export interface RotationRedirectV1 {
194
215
  readonly v: 1;
195
216
  readonly result: "rotated";
196
- /** New tail block id the topic anchor rotated to, base64url. */
217
+ /** New tail block id the root moved to, base64url — the new root key. */
197
218
  readonly newTailId: string;
198
- /** `H(newTailId ‖ "reactivity")` — the new tree's topic id, base64url (the redirect target). */
219
+ /** The collection's topic id, base64url — unchanged by a rotation. */
199
220
  readonly newTopicId: string;
200
221
  /** Revision at which the rotation took effect. */
201
222
  readonly effectiveAtRevision: number;
@@ -237,19 +258,19 @@ export type DrainDecision =
237
258
  export interface TailDrainGateInit {
238
259
  /** Unix ms the rotation took effect (drain starts here). */
239
260
  readonly rotatedAt: number;
240
- /** New tail block id the topic rotated to, base64url. */
261
+ /** New tail block id the root moved to, base64url. */
241
262
  readonly newTailId: string;
263
+ /** The collection's topic id, base64url — carried unchanged on the redirect. */
264
+ readonly topicId: string;
242
265
  /** Revision at which the rotation took effect. */
243
266
  readonly effectiveAtRevision: number;
244
267
  /** Drain duration `T_drain` (ms, default {@link T_DRAIN_MS}). */
245
268
  readonly tDrainMs?: number;
246
- /** Ring hash for the `newTopicId` derivation (must match cohort-topic routing). Default db-core SHA-256. */
247
- readonly hash?: IRingHash;
248
269
  }
249
270
 
250
271
  /**
251
- * The outgoing tail's drain state machine. For `T_drain` after a rotation it accepts **renewals** and
252
- * serves **replays**, but bounces **new subscriptions** with a {@link RotationRedirectV1} to the new tree;
272
+ * The outgoing root's drain state machine. For `T_drain` after a rotation it accepts **renewals** and
273
+ * serves **replays**, but bounces **new subscriptions** with a {@link RotationRedirectV1} to the new root;
253
274
  * after `T_drain` it reports `drained` for everything (the subscriber re-registers from `d_max`).
254
275
  */
255
276
  export class TailDrainGate {
@@ -264,13 +285,11 @@ export class TailDrainGate {
264
285
  }
265
286
  this.rotatedAt = init.rotatedAt;
266
287
  this.tDrainMs = tDrainMs;
267
- const hash = init.hash ?? createRingHash();
268
- const newTopicId = bytesToB64url(reactivityTopicId(b64urlToBytes(init.newTailId), hash));
269
288
  this.redirect = {
270
289
  v: 1,
271
290
  result: "rotated",
272
291
  newTailId: init.newTailId,
273
- newTopicId,
292
+ newTopicId: init.topicId,
274
293
  effectiveAtRevision: init.effectiveAtRevision,
275
294
  };
276
295
  }
@@ -292,7 +311,7 @@ export class TailDrainGate {
292
311
 
293
312
  /**
294
313
  * Classify an inbound request. Within the drain window: `new_subscribe` → redirect, `renew`/`replay` →
295
- * serve. After the window: `drained` (the old tail has released its forwarder state).
314
+ * serve. After the window: `drained` (the old root has released its forwarder state).
296
315
  */
297
316
  classify(op: DrainOp, now: number): DrainDecision {
298
317
  if (!this.isDraining(now)) {
@@ -302,17 +321,15 @@ export class TailDrainGate {
302
321
  }
303
322
  }
304
323
 
305
- // --- jittered re-registration (subscriber moves to the new tree) -------------
324
+ // --- jittered re-registration (a subscriber follows the new root) -------------
306
325
 
307
- /** A subscriber's planned re-registration at the rotated tree. */
326
+ /** A subscriber's planned follow of the moved root. */
308
327
  export interface ReRegistrationPlan {
309
- /** New tail block id (raw bytes) to attach under. */
328
+ /** New tail block id (raw bytes) — the new root key to follow. */
310
329
  readonly newTailId: Uint8Array;
311
- /** `H(newTailId ‖ "reactivity")` (raw bytes) — the new tree's topic id to register at. */
312
- readonly newTopicId: Uint8Array;
313
330
  /** The subscriber's existing `lastRevision`, carried so revisions stay continuous across the rotation. */
314
331
  readonly lastRevision: number;
315
- /** Unix ms at which to fire the re-registration (jittered over `T_rejoin_jitter`). */
332
+ /** Unix ms at which to fire the follow (jittered over `T_rejoin_jitter`). */
316
333
  readonly fireAt: number;
317
334
  }
318
335
 
@@ -320,32 +337,23 @@ export interface ReRegistrationPlan {
320
337
  interface ReRegistrationTarget {
321
338
  /** The rotation hint (or any object carrying the successor `newTailId`), base64url. */
322
339
  readonly hint: Pick<RotationHintV1, "newTailId">;
323
- /** Ring hash for the `newTopicId` derivation. Default db-core SHA-256. */
324
- readonly hash?: IRingHash;
325
- }
326
-
327
- /** Resolve `(newTailId, newTopicId)` raw bytes for a rotation target. */
328
- function resolveRotationTarget(target: ReRegistrationTarget): { newTailId: Uint8Array; newTopicId: Uint8Array } {
329
- const newTailId = b64urlToBytes(target.hint.newTailId);
330
- const newTopicId = reactivityTopicId(newTailId, target.hash ?? createRingHash());
331
- return { newTailId, newTopicId };
332
340
  }
333
341
 
334
342
  /**
335
- * Plan **one** subscriber's re-registration at the rotated tree: derive the new `topicId` from the hint's
336
- * `newTailId`, carry the subscriber's `lastRevision`, and draw a jittered `fireAt` over `T_rejoin_jitter`
337
- * via the cohort-topic {@link RejoinJitter} (`scheduleRejoin` — a uniform offset, decorrelating this
338
- * subscriber's re-join from its peers).
343
+ * Plan **one** subscriber's follow of the moved root: carry the hint's `newTailId` and the subscriber's
344
+ * `lastRevision`, and draw a jittered `fireAt` over `T_rejoin_jitter` via the cohort-topic
345
+ * {@link RejoinJitter} (`scheduleRejoin` — a uniform offset, decorrelating this subscriber's re-join from
346
+ * its peers). Only a registration at the root sends anything when the plan fires; one below the root
347
+ * updates its root key locally.
339
348
  */
340
349
  export function planReRegistration(opts: ReRegistrationTarget & { lastRevision: number; now: number; jitter: RejoinJitter }): ReRegistrationPlan {
341
- const { newTailId, newTopicId } = resolveRotationTarget(opts);
342
- return { newTailId, newTopicId, lastRevision: opts.lastRevision, fireAt: opts.jitter.scheduleRejoin(opts.now) };
350
+ return { newTailId: b64urlToBytes(opts.hint.newTailId), lastRevision: opts.lastRevision, fireAt: opts.jitter.scheduleRejoin(opts.now) };
343
351
  }
344
352
 
345
353
  /**
346
- * Plan a **whole wave** of subscribers' re-registrations at the rotated tree. Uses the
354
+ * Plan a **whole wave** of subscribers' follows of the moved root. Uses the
347
355
  * {@link RejoinJitter.scheduleWave} hard-bound staggering so any `T_rejoin_jitter`-long window holds at
348
- * most the injected jitter's `capPromote` arrivals — the new tail never sees more than
356
+ * most the injected jitter's `capPromote` arrivals — the new root never sees more than
349
357
  * `capPromote / T_rejoin_jitter` re-registrations per second.
350
358
  *
351
359
  * **Caller contract:** rotation is governed by the *fast-promote* bound, so the host MUST build this `jitter`
@@ -357,14 +365,14 @@ export function planReRegistration(opts: ReRegistrationTarget & { lastRevision:
357
365
  export function planReRegistrationWave(
358
366
  opts: ReRegistrationTarget & { subscribers: readonly { readonly lastRevision: number }[]; now: number; jitter: RejoinJitter },
359
367
  ): ReRegistrationPlan[] {
360
- const { newTailId, newTopicId } = resolveRotationTarget(opts);
368
+ const newTailId = b64urlToBytes(opts.hint.newTailId);
361
369
  const fireAts = opts.jitter.scheduleWave(opts.subscribers.length, opts.now);
362
- return opts.subscribers.map((s, i) => ({ newTailId, newTopicId, lastRevision: s.lastRevision, fireAt: fireAts[i]! }));
370
+ return opts.subscribers.map((s, i) => ({ newTailId, lastRevision: s.lastRevision, fireAt: fireAts[i]! }));
363
371
  }
364
372
 
365
373
  // --- buffer-to-checkpoint handoff (the only state migrated across a rotation) -
366
374
 
367
- /** The state migrated from the outgoing tail to the new tail on rotation. */
375
+ /** The state migrated from the outgoing root to the new root on rotation. */
368
376
  export interface RotationHandoff {
369
377
  /** The final checkpoint covering `[lastCheckpoint.toRevision + 1, rotationRevision]`. */
370
378
  readonly checkpoint: CheckpointSummary;
@@ -373,7 +381,7 @@ export interface RotationHandoff {
373
381
  }
374
382
 
375
383
  /**
376
- * Fold the outgoing tail's replay buffer into the final {@link CheckpointSummary} handed to the new tail
384
+ * Fold the outgoing root's replay buffer into the final {@link CheckpointSummary} handed to the new root
377
385
  * (`docs/reactivity.md` §Tail rotation step 5 — the **only** state migration across a rotation). The
378
386
  * handoff covers `[lastCheckpoint.toRevision + 1, rotationRevision]`: the revisions still live in the
379
387
  * replay ring (above the rolling checkpoint's high edge) up to the rotation revision. Returns `undefined`
@@ -400,10 +408,10 @@ export function buildRotationHandoffCheckpoint(state: PushState, opts: { rotatio
400
408
  }
401
409
 
402
410
  /**
403
- * Land a {@link RotationHandoff} at the new tail's {@link PushState}: record the inherited checkpoint so a
404
- * `ResumeV1` whose span crosses the rotation is recoverable from the new tail (the new tail "holds the old
411
+ * Land a {@link RotationHandoff} at the new root's {@link PushState}: record the inherited checkpoint so a
412
+ * `ResumeV1` whose span crosses the rotation is recoverable from the new root (the new root "holds the old
405
413
  * checkpoint", `docs/reactivity.md` §Tail rotation step 5). The handoff is a one-time migration — it does
406
- * not feed the new tail's rolling checkpoint (that rolls from the new tree's own replay-ring eviction).
414
+ * not feed the new root's rolling checkpoint (that rolls from the new root's own replay-ring eviction).
407
415
  */
408
416
  export function applyRotationHandoff(newTailState: PushState, handoff: RotationHandoff): void {
409
417
  newTailState.adoptRotationCheckpoint(handoff.checkpoint);
@@ -2,13 +2,16 @@
2
2
  * Reactivity — subscriber-side subscription state (`docs/reactivity.md` §Subscription).
3
3
  *
4
4
  * Subscribing to a collection is an **ordinary cohort-topic registration** at tier T3 with a reactivity
5
- * `appPayload`: `topicId = H(currentTailId(C) ‖ "reactivity")`, the configured TTL (Edge 60 s / Core 90 s),
6
- * and the cohort-topic walk-toward-root / willingness / promotion / TTL-renewal all reused unchanged.
7
- * This module owns only the subscriber-side bookkeeping struct and the `appPayload` builder; the db-p2p
8
- * subscription manager drives the cohort-topic `RegisterV1`.
5
+ * `appPayload`: `topicId = H(collectionId ‖ "reactivity")` (stable for the collection's life), the tail
6
+ * block's routing key as the topic's `rootKey`, the configured TTL (Edge 60 s / Core 90 s), and the
7
+ * cohort-topic walk-toward-root / willingness / promotion / TTL-renewal all reused unchanged. This module
8
+ * owns only the subscriber-side bookkeeping struct and the `appPayload` builder; the db-p2p subscription
9
+ * manager drives the cohort-topic `RegisterV1`.
9
10
  *
10
- * `tailIdAtAttach` is the subscriber-side detector for tail rotation (the whole-tree migration the
11
- * rotation ticket handles); `cohortEpoch` detects membership drift within the topic.
11
+ * The payload's `tailIdAtAttach` is the tail at *that registration*; the subscriber itself keeps the latest
12
+ * tail it has followed (`tail` below), which is what detects a rotation (a delivered `tailId` or a
13
+ * `rotationHint` naming another tail) and what a resume names as `latestKnownTailId`. `cohortEpoch` detects
14
+ * membership drift within the topic.
12
15
  */
13
16
 
14
17
  import { encodeSubscribeAppPayload, type SubscribeAppPayloadV1 } from "./wire.js";
@@ -17,10 +20,10 @@ import { encodeSubscribeAppPayload, type SubscribeAppPayloadV1 } from "./wire.js
17
20
  export interface ActiveSubscription {
18
21
  /** Stable collection identity. */
19
22
  readonly collectionId: Uint8Array;
20
- /** Current tail-anchored topic id. */
23
+ /** The collection's topic id — `H(collectionId ‖ "reactivity")`, stable for the collection's life. */
21
24
  readonly topicId: Uint8Array;
22
- /** Tail block id at registration time — detects tail rotation. */
23
- readonly tailIdAtAttach: Uint8Array;
25
+ /** The latest tail block the subscription has followed: the topic's current root key, and what detects a rotation. */
26
+ tail: Uint8Array;
24
27
  /** Serving cohort member. */
25
28
  primary: Uint8Array;
26
29
  /** Warm-failover cohort members. */
@@ -1,71 +1,68 @@
1
1
  /**
2
- * Reactivity — rotating, tail-anchored topic.
2
+ * Reactivity — the collection anchor: one topic per collection, a root that follows the tail.
3
3
  *
4
4
  * Transcribed from `docs/reactivity.md` §Anchor:
5
5
  *
6
6
  * ```
7
- * topicId(collection C, tail T) = H(T.blockId ‖ "reactivity")
7
+ * topicId(C) = H(utf8(C.collectionId) ‖ "reactivity") (stable for the collection's life)
8
+ * coord_0 = H(tailId) (the root: the tail block's storage group; moves on rotation)
9
+ * coord_d(P) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) (d ≥ 1; never moves)
8
10
  * ```
9
11
  *
10
- * Unlike matchmaking (whose anchor is a stable `(kind, label)`), the reactivity anchor **rotates** with
11
- * the collection's tail block: when the tail fills and a new tail block is born, `topicId` changes and
12
- * the cohort-topic layer treats it as an entirely new topic. The whole-tree migration that follows is
13
- * the rotation ticket's concern; this module owns only the pure derivation.
12
+ * Like matchmaking's `(kind, label)` anchor, the reactivity topic is **stable**: it is a function of the
13
+ * collection id alone, so the tiers below the root sit at fixed positions for the collection's life. What
14
+ * moves is the **root**. The root (announcing) group is the tail block's own storage group — the machines
15
+ * that apply, and so announce, the collection's commits — at `H(tailId)`, the ring position the key network
16
+ * places the tail by. When the tail block fills and a new one is born, the root moves to the new tail's
17
+ * storage group and nothing else does: a rotation is "same topic, the root moved"
18
+ * (`docs/reactivity.md` §Tail rotation).
14
19
  *
15
- * The resulting `topicId` is fed verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`),
16
- * so it is derived with the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
17
- * db-core's own SHA-256 truncated to the ring width, **not** a FRET import. The trailing `"reactivity"`
18
- * literal domain-separates the reactivity tree from any other application anchoring on the same tail id.
20
+ * Both derivations use the **same** {@link IRingHash} primitive cohort-topic uses for `coord_d` input —
21
+ * db-core's own SHA-256 truncated to the ring width, **not** a FRET import — because the topic id is fed
22
+ * verbatim into cohort-topic tier addressing (`coord_d(self, topicId)`) and the root coordinate must equal the
23
+ * key network's placement of the tail block byte for byte. The trailing `"reactivity"` literal domain-separates
24
+ * the topic from any other application anchoring on the same collection id, and from the root coordinate,
25
+ * which hashes the bare tail bytes. Concatenation is delimiter-free, exactly as the spec writes it; the
26
+ * constant suffix is unambiguous because no collection-id byte string can alias a `(collectionId, "reactivity")`
27
+ * pair of a different length.
19
28
  *
20
- * Concatenation is delimiter-free, exactly as the spec writes it; the constant suffix is unambiguous
21
- * because no tail-id byte string can alias a `(tailId, "reactivity")` pair of a different length.
22
- *
23
- * `reactivityTopicId` is the small pure helper the ticket asks for once and the rotation ticket
24
- * ([reactivity-rotation-backpressure-policy]) reuses per-emission — define it here, not at the call site.
29
+ * `collectionId` is the UTF-8 of the id exactly as blocks carry it (`header.collectionId`, e.g. `app/users`) —
30
+ * the same bytes a notification's `collectionId` encodes (`reactivityCollectionIdBytes` in db-p2p's
31
+ * `reactivity/topic-bytes.ts`). Origination and every subscriber derive the topic from those bytes, so a
32
+ * notification routes to exactly the managers watching its collection.
25
33
  */
26
34
 
27
35
  import { createRingHash } from "../cohort-topic/ring-hash.js";
28
- import type { IRingHash } from "../cohort-topic/ports.js";
36
+ import { createTierAddressing } from "../cohort-topic/addressing.js";
37
+ import type { IRingHash, RingCoord } from "../cohort-topic/ports.js";
29
38
 
30
- /** Domain-separation suffix mixed into every reactivity anchor. */
39
+ /** Domain-separation suffix mixed into the reactivity topic. */
31
40
  const REACTIVITY_SUFFIX = "reactivity";
32
41
 
33
42
  const utf8 = new TextEncoder();
34
43
 
35
44
  /**
36
- * `H(tailId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` for the
37
- * reactivity tree anchored on `tailId` (the collection's current tail block id, as raw bytes).
38
- *
39
- * The shared helper consumed by subscriber attachment, origination, and (per-emission) the rotation
40
- * ticket. `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
45
+ * `H(collectionId ‖ "reactivity")` over the injected ring hash — the cohort-topic `topicId` of a collection's
46
+ * reactivity tree, stable for the collection's life. `collectionId` is the UTF-8 of the id as blocks carry it.
47
+ * `hash` defaults to db-core's own 256-bit SHA-256, byte-identical to the cohort-topic host's.
41
48
  */
42
- export function reactivityTopicId(tailId: Uint8Array, hash: IRingHash = createRingHash()): Uint8Array {
49
+ export function reactivityCollectionTopicId(collectionId: Uint8Array, hash: IRingHash = createRingHash()): Uint8Array {
43
50
  const suffixBytes = utf8.encode(REACTIVITY_SUFFIX);
44
- const input = new Uint8Array(tailId.length + suffixBytes.length);
45
- input.set(tailId, 0);
46
- input.set(suffixBytes, tailId.length);
51
+ const input = new Uint8Array(collectionId.length + suffixBytes.length);
52
+ input.set(collectionId, 0);
53
+ input.set(suffixBytes, collectionId.length);
47
54
  return hash.H(input);
48
55
  }
49
56
 
50
- /** Derives the rotating `topicId` for a collection's current tail. */
51
- export interface ReactivityTopicAnchor {
52
- /** `H(tailId ‖ "reactivity")` for the given tail block id (bytes). */
53
- topicId(tailId: Uint8Array): Uint8Array;
54
- }
55
-
56
- class HashReactivityTopicAnchor implements ReactivityTopicAnchor {
57
- constructor(private readonly hash: IRingHash) {}
58
-
59
- topicId(tailId: Uint8Array): Uint8Array {
60
- return reactivityTopicId(tailId, this.hash);
61
- }
62
- }
63
-
64
57
  /**
65
- * Build a {@link ReactivityTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
66
- * it binds to FRET's `RING_BITS` so the anchor and cohort-topic routing keys line up; the default
67
- * constructs db-core's own {@link createRingHash} (256-bit SHA-256).
58
+ * The reactivity root coordinate for a tail: `H(tailId)` over the injected ring hash — the tail block's
59
+ * own ring position, where its storage group sits. `tailId` is the tail's routing key bytes (the raw utf8
60
+ * of the block id, `reactivityTailBytes` on a node), so at the default 256-bit ring width this equals the
61
+ * key network's `hashKey(routingKeyForBlock(tail))` byte for byte; the `topic-bytes-encoding` spec in
62
+ * db-p2p pins that equality. Every party that derives the root group — the notification verifier, the
63
+ * subscriber walk's root step, the forwarder's gossip and recover reads — must start from this one value.
64
+ * It is the one coordinate of a collection's tree that changes when the tail rotates.
68
65
  */
69
- export function createReactivityTopicAnchor(hash: IRingHash = createRingHash()): ReactivityTopicAnchor {
70
- return new HashReactivityTopicAnchor(hash);
66
+ export function reactivityRootCoord(tailId: Uint8Array, hash: IRingHash = createRingHash()): RingCoord {
67
+ return createTierAddressing(hash).rootCoord(tailId);
71
68
  }
@@ -2,31 +2,44 @@
2
2
  * Reactivity — subscriber/forwarder notification verification seam
3
3
  * (`docs/reactivity.md` §Propagation, §Delivery, §Authentication).
4
4
  *
5
- * A forwarder and a subscriber both verify a notification's threshold signature against the **tail
6
- * cohort's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
5
+ * A forwarder and a subscriber both verify a notification's threshold signature against the **root
6
+ * group's** `MembershipCertV1` before trusting it — forwarders never re-sign, so the same end-to-end
7
7
  * signature is verified regardless of hop count. The standard cohort-topic membership-snapshot path
8
8
  * ({@link MembershipVerifier}) already provides the **one fetch-and-retry** on a stale/missing cached
9
- * cert, so this module is a thin adapter: derive the tail cohort's `coord_0(_, topicId)` from the
10
- * notification's `tailId`, then hand `(signers, coord, tier, digest, sig)` to the verifier.
9
+ * cert, so this module is a thin adapter: derive the root coordinate from the notification's `tailId`,
10
+ * then hand `(signers, coord, tier, digest, sig)` to the verifier under the root placement rule.
11
+ *
12
+ * **The root group is the tail's storage group** (`docs/reactivity.md` §Origination point). The
13
+ * notification's `tailId` is the base64url of the tail's routing key bytes, so `reactivityRootCoord`
14
+ * of those bytes is the ring position the key network stores the tail block at, and the group there is
15
+ * the one whose commit certificate the notification reuses as its signature. The signature threshold is
16
+ * therefore the **verifier's own** `ceil(|root group| × quorumRatio)` — the formula the commit certificate
17
+ * was captured under — never the cohort-topic `minSigs`, and never a value read from the notification.
11
18
  *
12
19
  * The signed payload is the commit `digest` (the commit cert's threshold signature is over the commit
13
20
  * hash — see {@link import("./notification.js").buildNotificationV1}). `signers` arrive base64url-encoded
14
21
  * as the cohort member-id bytes the verifier compares against `cert.members`; a custom `signersToBytes`
15
22
  * seam is exposed for bindings that carry signers in a different encoding.
23
+ *
24
+ * **The placement names the tail.** Every `verifyMessage` call carries a {@link RootPlacement} whose
25
+ * `rootKey` is the notification's tail bytes — the same bytes the root coordinate is derived from — so a
26
+ * direct anchor that can fetch the tail's own commit proof (db-p2p's commit-log anchor) knows which block to
27
+ * ask the root group about. Without the key that anchor answers `"unknown"` and a distant verifier is back
28
+ * to trusting the group's certificate on first use, with no other symptom; the verify spec pins the key.
16
29
  */
17
30
 
18
- import { createTierAddressing, DEFAULT_FANOUT } from "../cohort-topic/addressing.js";
19
31
  import { createRingHash } from "../cohort-topic/ring-hash.js";
20
32
  import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
21
33
  import { Tier } from "../cohort-topic/tiers.js";
22
- import type { IRingHash } from "../cohort-topic/ports.js";
34
+ import { createRootPlacement } from "../cohort-topic/sig/threshold.js";
35
+ import type { IRingHash, RootPlacement } from "../cohort-topic/ports.js";
23
36
  import type { MembershipVerifier, VerifyResult } from "../cohort-topic/membership/verifier.js";
24
- import { reactivityTopicId } from "./topic-anchor.js";
37
+ import { reactivityRootCoord } from "./topic-anchor.js";
25
38
  import type { NotificationV1 } from "./wire.js";
26
39
 
27
- /** Verifies a {@link NotificationV1}'s threshold signature against the tail cohort's membership. */
40
+ /** Verifies a {@link NotificationV1}'s threshold signature against the root group's membership. */
28
41
  export interface NotificationVerifier {
29
- /** `"verified"` iff `sig` is a valid `≥ minSigs` cohort signature over the commit digest. */
42
+ /** `"verified"` iff `sig` is a valid root-group signature over the commit digest, at the placement threshold. */
30
43
  verify(n: NotificationV1): Promise<VerifyResult>;
31
44
  }
32
45
 
@@ -34,10 +47,14 @@ export interface NotificationVerifier {
34
47
  export interface NotificationVerifierDeps {
35
48
  /** The cohort-topic participant-side membership verifier (owns the one fetch-and-retry). */
36
49
  readonly verifier: MembershipVerifier;
37
- /** Ring hash for `topicId` / `coord_0` derivation. Default db-core 256-bit SHA-256. */
50
+ /**
51
+ * The ratio the root group's commit certificates are signed under — this node's own consensus
52
+ * `superMajorityThreshold`, never a value off a message. The threshold applied to a notification is
53
+ * `ceil(|root group| × quorumRatio)`; a ratio outside `(0, 1]` throws here, at construction.
54
+ */
55
+ readonly quorumRatio: number;
56
+ /** Ring hash for the root-coordinate derivation. Default db-core 256-bit SHA-256. */
38
57
  readonly hash?: IRingHash;
39
- /** Fan-out `F` for tier addressing. Default {@link DEFAULT_FANOUT}. */
40
- readonly fanout?: number;
41
58
  /** Reactivity runs at T3; overridable for tests. */
42
59
  readonly tier?: Tier;
43
60
  /** Map a wire signer string to the verifier's member-id bytes. Default base64url decode. */
@@ -45,25 +62,27 @@ export interface NotificationVerifierDeps {
45
62
  }
46
63
 
47
64
  class MembershipNotificationVerifier implements NotificationVerifier {
48
- private readonly addressing: ReturnType<typeof createTierAddressing>;
49
65
  private readonly hash: IRingHash;
50
66
  private readonly tier: Tier;
67
+ private readonly placement: RootPlacement;
51
68
  private readonly signersToBytes: (signer: string) => Uint8Array;
52
69
 
53
70
  constructor(private readonly deps: NotificationVerifierDeps) {
54
71
  this.hash = deps.hash ?? createRingHash();
55
- this.addressing = createTierAddressing(this.hash, deps.fanout ?? DEFAULT_FANOUT);
56
72
  this.tier = deps.tier ?? Tier.T3;
73
+ this.placement = createRootPlacement(deps.quorumRatio);
57
74
  this.signersToBytes = deps.signersToBytes ?? b64urlToBytes;
58
75
  }
59
76
 
60
77
  async verify(n: NotificationV1): Promise<VerifyResult> {
61
- const topicId = reactivityTopicId(b64urlToBytes(n.tailId), this.hash);
62
- const expectedCoord = this.addressing.coord0(topicId);
78
+ const tailBytes = b64urlToBytes(n.tailId);
79
+ const expectedCoord = reactivityRootCoord(tailBytes, this.hash);
63
80
  const signers = n.signers.map(this.signersToBytes);
64
81
  const payload = b64urlToBytes(n.digest);
65
82
  const sig = b64urlToBytes(n.sig);
66
- return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig);
83
+ // The ratio was validated once at construction; the key is per notification, so spread it per call.
84
+ const placement: RootPlacement = { ...this.placement, rootKey: tailBytes };
85
+ return this.deps.verifier.verifyMessage(signers, expectedCoord, this.tier, payload, sig, { placement });
67
86
  }
68
87
  }
69
88
 
@@ -67,7 +67,7 @@ export interface SubscribeAppPayloadV1 {
67
67
 
68
68
  /** The tail cohort's rotation pre-announce, carried inside (and signed by) a {@link NotificationV1}. */
69
69
  export interface RotationHintV1 {
70
- /** New tail block id the topic anchor is rotating to, base64url. */
70
+ /** New tail block id the collection's root is moving to, base64url. */
71
71
  newTailId: string;
72
72
  /** Revision at which the new tail becomes effective. */
73
73
  effectiveAtRevision: number;
@@ -11,7 +11,7 @@ export type CollectionChangeEvent = {
11
11
  readonly rev: number;
12
12
  /**
13
13
  * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
14
- * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
14
+ * Names the reactivity root (the tail block's storage group, at `H(tailId)`). Present on commit-driven
15
15
  * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
16
16
  * those never originate anyway, and are cert-gated out downstream).
17
17
  */