@optimystic/db-core 1.8.1 → 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 (127) 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/collection/collection.d.ts +17 -0
  66. package/dist/src/collection/collection.d.ts.map +1 -1
  67. package/dist/src/collection/collection.js +19 -0
  68. package/dist/src/collection/collection.js.map +1 -1
  69. package/dist/src/reactivity/config.d.ts +9 -5
  70. package/dist/src/reactivity/config.d.ts.map +1 -1
  71. package/dist/src/reactivity/config.js +9 -4
  72. package/dist/src/reactivity/config.js.map +1 -1
  73. package/dist/src/reactivity/index.d.ts +4 -3
  74. package/dist/src/reactivity/index.d.ts.map +1 -1
  75. package/dist/src/reactivity/index.js +4 -3
  76. package/dist/src/reactivity/index.js.map +1 -1
  77. package/dist/src/reactivity/notification.d.ts +7 -0
  78. package/dist/src/reactivity/notification.d.ts.map +1 -1
  79. package/dist/src/reactivity/notification.js +1 -1
  80. package/dist/src/reactivity/notification.js.map +1 -1
  81. package/dist/src/reactivity/rotation.d.ts +73 -57
  82. package/dist/src/reactivity/rotation.d.ts.map +1 -1
  83. package/dist/src/reactivity/rotation.js +54 -54
  84. package/dist/src/reactivity/rotation.js.map +1 -1
  85. package/dist/src/reactivity/subscription.d.ts +12 -9
  86. package/dist/src/reactivity/subscription.d.ts.map +1 -1
  87. package/dist/src/reactivity/subscription.js +9 -6
  88. package/dist/src/reactivity/subscription.js.map +1 -1
  89. package/dist/src/reactivity/topic-anchor.d.ts +36 -31
  90. package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
  91. package/dist/src/reactivity/topic-anchor.js +41 -39
  92. package/dist/src/reactivity/topic-anchor.js.map +1 -1
  93. package/dist/src/reactivity/verify.d.ts +26 -9
  94. package/dist/src/reactivity/verify.d.ts.map +1 -1
  95. package/dist/src/reactivity/verify.js +26 -11
  96. package/dist/src/reactivity/verify.js.map +1 -1
  97. package/dist/src/reactivity/wire.d.ts +1 -1
  98. package/dist/src/reactivity/wire.d.ts.map +1 -1
  99. package/dist/src/transactor/change-notifier.d.ts +1 -1
  100. package/package.json +5 -5
  101. package/src/cohort-topic/addressing.ts +83 -23
  102. package/src/cohort-topic/member-engine.ts +77 -8
  103. package/src/cohort-topic/membership/publisher.ts +1 -1
  104. package/src/cohort-topic/membership/source.ts +4 -0
  105. package/src/cohort-topic/membership/verifier.ts +169 -51
  106. package/src/cohort-topic/ports.ts +87 -15
  107. package/src/cohort-topic/registration/renewal.ts +87 -24
  108. package/src/cohort-topic/service.ts +157 -35
  109. package/src/cohort-topic/sig/payloads.ts +7 -2
  110. package/src/cohort-topic/sig/threshold.ts +41 -7
  111. package/src/cohort-topic/walk.ts +46 -9
  112. package/src/cohort-topic/willingness.ts +34 -3
  113. package/src/cohort-topic/wire/index.ts +1 -0
  114. package/src/cohort-topic/wire/payloads.ts +21 -0
  115. package/src/cohort-topic/wire/primitives.ts +26 -4
  116. package/src/cohort-topic/wire/types.ts +37 -0
  117. package/src/cohort-topic/wire/validate.ts +26 -3
  118. package/src/collection/collection.ts +20 -0
  119. package/src/reactivity/config.ts +10 -5
  120. package/src/reactivity/index.ts +4 -3
  121. package/src/reactivity/notification.ts +8 -1
  122. package/src/reactivity/rotation.ts +86 -78
  123. package/src/reactivity/subscription.ts +12 -9
  124. package/src/reactivity/topic-anchor.ts +42 -45
  125. package/src/reactivity/verify.ts +36 -17
  126. package/src/reactivity/wire.ts +1 -1
  127. package/src/transactor/change-notifier.ts +1 -1
@@ -22,9 +22,15 @@ import { randomBytes } from "@noble/hashes/utils.js";
22
22
  import { createTierAddressing, type TierAddressing } from "./addressing.js";
23
23
  import { makeDMaxComputer, type DMaxComputer } from "./dmax.js";
24
24
  import { DEFAULT_FANOUT } from "./addressing.js";
25
- import type { ISizeEstimator, ITopicRouter, IRingHash, RingCoord } from "./ports.js";
26
- import { createWalkEngine, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
27
- import { createRenewalParticipant, type RenewalParticipant, type RenewalParticipantTransport, type UnsignedRenew } from "./registration/renewal.js";
25
+ import type { ISizeEstimator, ITopicRouter, IRingHash } from "./ports.js";
26
+ import { createWalkEngine, type AcceptedWalkOutcome, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
27
+ import {
28
+ createRenewalParticipant,
29
+ type RenewalAssignment,
30
+ type RenewalParticipant,
31
+ type RenewalParticipantTransport,
32
+ type UnsignedRenew,
33
+ } from "./registration/renewal.js";
28
34
  import type { RegistrationRecord } from "./registration/types.js";
29
35
  import { DEFAULT_TTL_MS } from "./registration/types.js";
30
36
  import { recordKey } from "./registration/bytes.js";
@@ -32,13 +38,20 @@ import type { CohortGossipBus } from "./gossip/bus.js";
32
38
  import type { MembershipVerifier } from "./membership/verifier.js";
33
39
  import type { Tier } from "./tiers.js";
34
40
  import { bytesToB64url, b64urlToBytes, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
35
- import type { RegisterReplyV1, RegisterV1, RenewReplyV1, TopicTrafficV1 } from "./wire/types.js";
41
+ import { MAX_ROOT_KEY_BYTES } from "./wire/validate.js";
42
+ import type { RegisterV1, RenewReplyV1, TopicTrafficV1 } from "./wire/types.js";
36
43
  import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
37
44
 
38
45
  /** A resolved cohort for a topic/tier — the return of {@link CohortTopicService.lookup}. */
39
46
  export interface CohortHint {
40
47
  readonly topicId: Uint8Array;
41
48
  readonly tier: Tier;
49
+ /**
50
+ * The tree tier `d` the walk landed at: `0` is the topic's root cohort, `d ≥ 1` a cohort below it. A
51
+ * root-placed topic's root can move while the tiers below it stay put, so a caller following a moved
52
+ * root reads this to choose between {@link CohortTopicService.moveRoot} and registering again.
53
+ */
54
+ readonly treeTier: number;
42
55
  /** Serving cohort member. */
43
56
  readonly primary: Uint8Array;
44
57
  /** Warm-failover cohort members (1..2). */
@@ -48,6 +61,13 @@ export interface CohortHint {
48
61
  readonly cohortMembers: Uint8Array[];
49
62
  /** Coarse traffic barometer, when the cohort attached one. */
50
63
  readonly topicTraffic?: TopicTrafficV1;
64
+ /**
65
+ * The root key the topic was resolved under, when it is root-placed (its tier-0 cohort sits at
66
+ * `H(rootKey)`) — on a handle, the key {@link CohortTopicService.moveRoot} last named, which a handle at
67
+ * the root (`treeTier` 0) holds before it has registered there. Absent for the default addressing. A
68
+ * caller verifying a message signed by that root needs it to know the root's threshold rule applies.
69
+ */
70
+ readonly rootKey?: Uint8Array;
51
71
  }
52
72
 
53
73
  /** A live registration: a {@link CohortHint} plus the participant-side renewal handle behind it. */
@@ -85,6 +105,13 @@ export interface RegisterRequest {
85
105
  readonly ttl?: number;
86
106
  /** Mark this a cold-root bootstrap request. */
87
107
  readonly bootstrap?: boolean;
108
+ /**
109
+ * Place this topic's root at a routing key: raw key bytes (1..`MAX_ROOT_KEY_BYTES`), e.g. a block's
110
+ * routing key. The topic's tier-0 cohort is then the group responsible for that key, at `H(rootKey)`,
111
+ * instead of the cohort at `H(0x00 ‖ topicId)` (§Tier addressing → Root placement at a routing key).
112
+ * Every participant of one topic must name the same key. Absent → the default addressing.
113
+ */
114
+ readonly rootKey?: Uint8Array;
88
115
  }
89
116
 
90
117
  /** The substrate's participant-facing contract. */
@@ -93,11 +120,23 @@ export interface CohortTopicService {
93
120
  register(req: RegisterRequest): Promise<RegistrationHandle>;
94
121
  /** Run one `ttl/3` renewal cycle for `handle` (handles `primary_moved` + crash-failover). */
95
122
  renew(handle: RegistrationHandle): Promise<void>;
96
- /** Resolve the cohort for `topicId` at `tier` without keeping a live registration. */
97
- lookup(topicId: Uint8Array, tier: Tier): Promise<CohortHint>;
123
+ /**
124
+ * Resolve the cohort for `topicId` at `tier` without keeping a live registration. `rootKey` names the
125
+ * root of a root-placed topic (see {@link RegisterRequest.rootKey}).
126
+ */
127
+ lookup(topicId: Uint8Array, tier: Tier, rootKey?: Uint8Array): Promise<CohortHint>;
98
128
  /** Stop renewing `handle` and send a best-effort signed withdraw tombstone so the cohort frees the
99
129
  * record immediately (TTL expiry remains the fallback if the primary is unreachable). */
100
130
  withdraw(handle: RegistrationHandle): Promise<void>;
131
+ /**
132
+ * The topic's root moved to `rootKey` (a root-placed topic only — a handle registered without a root key
133
+ * throws). Nothing is sent: a registration at a tier below the root stays where it is. A later re-walk of
134
+ * this registration (renewal failover) names the new key, so it lands at the new root rather than the old
135
+ * one. A registration AT the root (`handle.treeTier === 0`) is left at the old root by this call and must
136
+ * be re-registered instead — `register` with the new key displaces it (see the NOTE at `startRenewal`).
137
+ * A stale handle (no longer the live registration for its topic) is a no-op.
138
+ */
139
+ moveRoot(handle: RegistrationHandle, rootKey: Uint8Array): void;
101
140
  /** Origination hook the change-notifier bridge invokes per local member commit; see {@link LocalChangeHook}. */
102
141
  onLocalCommit?: LocalChangeHook;
103
142
  /** Cohort gossip bus — applications fold app state into the existing gossip. */
@@ -175,6 +214,29 @@ export interface CohortTopicServiceDeps {
175
214
  readonly config?: CohortServiceConfig;
176
215
  }
177
216
 
217
+ /** The root key a renewal's re-walk names — mutable, so {@link CohortTopicService.moveRoot} can re-point it. */
218
+ interface RootKeySlot {
219
+ key: Uint8Array | undefined;
220
+ }
221
+
222
+ /**
223
+ * What the walk that last placed a registration reported beyond its primary, backups and epoch — set by the
224
+ * register, replaced by each renewal re-walk. The participant's record stays the authority for primary,
225
+ * backups and epoch, since later `primary_moved` replies change those without a walk.
226
+ */
227
+ interface WalkLanding {
228
+ treeTier: number;
229
+ cohortMembers: Uint8Array[];
230
+ topicTraffic: TopicTrafficV1 | undefined;
231
+ }
232
+
233
+ /** A live registration's renewal driver, the root key its re-walk reads, and where it last landed. */
234
+ interface LiveRenewal {
235
+ readonly renewal: RenewalParticipant;
236
+ readonly root: RootKeySlot;
237
+ readonly landing: WalkLanding;
238
+ }
239
+
178
240
  class WalkRegisterService implements CohortTopicService {
179
241
  public onLocalCommit?: LocalChangeHook;
180
242
 
@@ -184,8 +246,8 @@ class WalkRegisterService implements CohortTopicService {
184
246
  private readonly clock: () => number;
185
247
  private readonly ttl: number;
186
248
  private readonly maxMessageBytes?: number;
187
- /** Live renewal drivers, keyed by `(topicId, participantId)` so renew/withdraw find their handle. */
188
- private readonly renewals = new Map<string, RenewalParticipant>();
249
+ /** Live renewals, keyed by `(topicId, participantId)` so renew/withdraw/moveRoot find their handle. */
250
+ private readonly renewals = new Map<string, LiveRenewal>();
189
251
  private readonly participantId: Uint8Array;
190
252
 
191
253
  constructor(private readonly deps: CohortTopicServiceDeps) {
@@ -213,32 +275,48 @@ class WalkRegisterService implements CohortTopicService {
213
275
  }
214
276
 
215
277
  async register(req: RegisterRequest): Promise<RegistrationHandle> {
216
- const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload);
278
+ assertRootKey(req.rootKey);
279
+ const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload, { rootKey: req.rootKey });
217
280
  return this.handleFromOutcome(req, outcome);
218
281
  }
219
282
 
220
- async lookup(topicId: Uint8Array, tier: Tier): Promise<CohortHint> {
283
+ async lookup(topicId: Uint8Array, tier: Tier, rootKey?: Uint8Array): Promise<CohortHint> {
284
+ assertRootKey(rootKey);
221
285
  // A read-only probe: it walks to the responsible cohort exactly as a register would and returns the
222
286
  // same cohort snapshot, but admits NOTHING — no soft-state record, no arrival, no promotion trigger,
223
287
  // no topic-budget touch, and never a cold-start instantiation. A topic served nowhere resolves to a
224
288
  // `CohortBackoffError` (the probe never bootstraps a cold root), so a lookup leaves no throwaway
225
289
  // registration behind to TTL-expire (§Application policies; the lookup-as-register interim is gone).
226
- const outcome = await this.walk.register(topicId, tier, undefined, { probe: true });
290
+ const outcome = await this.walk.register(topicId, tier, undefined, { probe: true, rootKey });
227
291
  if (outcome.kind !== "accepted") {
228
292
  throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
229
293
  }
230
- return this.hintFromReply(topicId, tier, outcome.reply);
294
+ return this.hintFromReply(topicId, tier, outcome, rootKey);
231
295
  }
232
296
 
233
297
  async renew(handle: RegistrationHandle): Promise<void> {
234
298
  // Act only if this handle is still the live entry. A stale handle (superseded by a second
235
299
  // register() for the same pair) must not drive the new registration's ping loop, and a
236
300
  // withdrawn handle must not silently re-start it.
237
- if (this.renewals.get(recordKey(handle.topicId, this.participantId)) !== handle.renewal) {
301
+ const live = this.liveRenewal(handle);
302
+ if (live === undefined) {
238
303
  return;
239
304
  }
240
305
  await handle.renewal.pingLoop();
241
- this.syncHandle(handle);
306
+ this.syncHandle(handle, live.landing);
307
+ }
308
+
309
+ moveRoot(handle: RegistrationHandle, rootKey: Uint8Array): void {
310
+ assertRootKey(rootKey);
311
+ if (handle.rootKey === undefined) {
312
+ throw new Error("cohort-topic: moveRoot needs a root-placed registration; this one was registered without a rootKey");
313
+ }
314
+ const live = this.liveRenewal(handle);
315
+ if (live === undefined) {
316
+ return;
317
+ }
318
+ live.root.key = rootKey;
319
+ (handle as { rootKey?: Uint8Array }).rootKey = rootKey;
242
320
  }
243
321
 
244
322
  async withdraw(handle: RegistrationHandle): Promise<void> {
@@ -247,17 +325,16 @@ class WalkRegisterService implements CohortTopicService {
247
325
  // primary so the cohort frees the record immediately instead of holding it for up to a full TTL.
248
326
  // The delete happens FIRST so a concurrent renew() already no-ops before the tombstone is sent. If
249
327
  // the tombstone send fails (primary unreachable), the cohort soft-state TTL-expires as the
250
- // fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds
251
- // `renewal !== handle.renewal` (undefined ≠ any object) and no-ops.
328
+ // fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds no
329
+ // live entry for the handle and no-ops.
252
330
  // Guard: act only if this handle is still the live entry. A stale handle must not evict the
253
331
  // new registration or send a tombstone on its behalf.
254
- const key = recordKey(handle.topicId, this.participantId);
255
- const renewal = this.renewals.get(key);
256
- if (renewal !== handle.renewal) {
332
+ const live = this.liveRenewal(handle);
333
+ if (live === undefined) {
257
334
  return;
258
335
  }
259
- this.renewals.delete(key);
260
- await renewal.withdraw();
336
+ this.renewals.delete(recordKey(handle.topicId, this.participantId));
337
+ await live.renewal.withdraw();
261
338
  }
262
339
 
263
340
  cohortGossip(): CohortGossipBus {
@@ -274,11 +351,17 @@ class WalkRegisterService implements CohortTopicService {
274
351
  if (outcome.kind !== "accepted") {
275
352
  throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
276
353
  }
277
- const hint = this.hintFromReply(req.topicId, req.tier, outcome.reply);
354
+ const hint = this.hintFromReply(req.topicId, req.tier, outcome, req.rootKey);
278
355
  const renewal = this.startRenewal(req, hint, outcome.correlationId);
279
356
  return { ...hint, renewal };
280
357
  }
281
358
 
359
+ /** The live renewal `handle` drives, or `undefined` when a later register displaced it or it was withdrawn. */
360
+ private liveRenewal(handle: RegistrationHandle): LiveRenewal | undefined {
361
+ const live = this.renewals.get(recordKey(handle.topicId, this.participantId));
362
+ return live?.renewal === handle.renewal ? live : undefined;
363
+ }
364
+
282
365
  private startRenewal(req: RegisterRequest, hint: CohortHint, correlationId: string): RenewalParticipant {
283
366
  const ttl = req.ttl ?? this.ttl;
284
367
  const initial: RegistrationRecord = {
@@ -292,7 +375,9 @@ class WalkRegisterService implements CohortTopicService {
292
375
  ttl,
293
376
  appState: req.appPayload,
294
377
  };
295
- const transport = this.renewalTransport(req);
378
+ const root: RootKeySlot = { key: req.rootKey };
379
+ const landing: WalkLanding = { treeTier: hint.treeTier, cohortMembers: hint.cohortMembers, topicTraffic: hint.topicTraffic };
380
+ const transport = this.renewalTransport(req, root, landing);
296
381
  const renewal = createRenewalParticipant(initial, {
297
382
  transport,
298
383
  clock: this.clock,
@@ -307,44 +392,65 @@ class WalkRegisterService implements CohortTopicService {
307
392
  correlationId,
308
393
  initialCohortEpoch: hint.cohortEpoch,
309
394
  });
310
- // NOTE: a second register() for the same (topicId, participantId) overwrites the map entry here,
311
- // orphaning the prior renewal. renew()/withdraw() on the stale handle now no-op (identity guard),
312
- // but no tombstone is sent for the superseded record — the cohort frees it via TTL expiry. Harmless
313
- // for occasional re-registers; if callers ever churn-register the same pair, send a withdraw for the
314
- // displaced renewal here so the cohort reclaims immediately instead of holding up to a full TTL.
315
- this.renewals.set(recordKey(req.topicId, this.participantId), renewal);
395
+ // NOTE: accepted — a second register() for the same (topicId, participantId) displaces the first:
396
+ // renew()/withdraw()/moveRoot() on the displaced handle no-op (identity guard), and NO tombstone is
397
+ // sent for the displaced record, by design. A participant re-registers at a moved root while its old
398
+ // record still lives at the old one, and a machine in both roots' storage groups holds both; a
399
+ // tombstone resolves through the host's `findHolder`, which picks the newer record there, so it would
400
+ // evict the live registration. The displaced record expires by TTL at its cohort.
401
+ this.renewals.set(recordKey(req.topicId, this.participantId), { renewal, root, landing });
316
402
  return renewal;
317
403
  }
318
404
 
319
- /** Renewal transport: dial the cached primary directly; a full failure re-runs the register walk. */
320
- private renewalTransport(req: RegisterRequest): RenewalParticipantTransport {
405
+ /**
406
+ * Renewal transport: dial the cached primary directly; a full failure re-runs the register walk. The
407
+ * re-walk reads the root key from `root` when it runs, so after {@link CohortTopicService.moveRoot} it
408
+ * lands at the topic's current root rather than the one it registered under. An accepted re-walk records
409
+ * its tree tier, cohort and traffic in `landing` and hands its assignment to the participant to adopt.
410
+ */
411
+ private renewalTransport(req: RegisterRequest, root: RootKeySlot, landing: WalkLanding): RenewalParticipantTransport {
321
412
  return {
322
413
  send: async (target: Uint8Array, msg): Promise<RenewReplyV1> => {
323
414
  const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
324
415
  return decodeRenewReplyV1(raw, this.maxMessageBytes);
325
416
  },
326
- relookup: async (): Promise<void> => {
327
- await this.walk.register(req.topicId, req.tier, req.appPayload);
417
+ relookup: async (): Promise<RenewalAssignment | undefined> => {
418
+ // NOTE: re-sends the first registration's `appPayload` (for a collection watch, its `tailIdAtAttach`
419
+ // and `lastKnownRev`). No cohort reads those fields off a held record today; if one ever does, the
420
+ // re-walk needs a fresh payload from the registering caller.
421
+ const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload, { rootKey: root.key });
422
+ if (outcome.kind !== "accepted") {
423
+ return undefined;
424
+ }
425
+ const hint = this.hintFromReply(req.topicId, req.tier, outcome, root.key);
426
+ landing.treeTier = hint.treeTier;
427
+ landing.cohortMembers = hint.cohortMembers;
428
+ landing.topicTraffic = hint.topicTraffic;
429
+ return { primary: hint.primary, backups: hint.backups, cohortEpoch: hint.cohortEpoch, correlationId: outcome.correlationId };
328
430
  },
329
431
  };
330
432
  }
331
433
 
332
- private hintFromReply(topicId: Uint8Array, tier: Tier, reply: RegisterReplyV1): CohortHint {
434
+ private hintFromReply(topicId: Uint8Array, tier: Tier, outcome: AcceptedWalkOutcome, rootKey: Uint8Array | undefined): CohortHint {
435
+ const reply = outcome.reply;
333
436
  if (reply.primary === undefined || reply.cohortEpoch === undefined) {
334
437
  throw new CohortBackoffError(0);
335
438
  }
336
439
  return {
337
440
  topicId,
338
441
  tier,
442
+ treeTier: outcome.treeTier,
339
443
  primary: b64urlToBytes(reply.primary),
340
444
  backups: (reply.backups ?? []).map(b64urlToBytes),
341
445
  cohortEpoch: b64urlToBytes(reply.cohortEpoch),
342
446
  cohortMembers: (reply.cohortMembers ?? []).map(b64urlToBytes),
343
447
  topicTraffic: reply.topicTraffic,
448
+ ...(rootKey === undefined ? {} : { rootKey }),
344
449
  };
345
450
  }
346
451
 
347
- private syncHandle(handle: RegistrationHandle): void {
452
+ /** Copy the registration's current placement onto `handle`: the participant's record, and the last walk's landing. */
453
+ private syncHandle(handle: RegistrationHandle, landing: WalkLanding): void {
348
454
  const rec = handle.renewal.record;
349
455
  (handle as { primary: Uint8Array }).primary = rec.primary;
350
456
  (handle as { backups: Uint8Array[] }).backups = [...rec.backups];
@@ -352,6 +458,9 @@ class WalkRegisterService implements CohortTopicService {
352
458
  if (epoch !== undefined) {
353
459
  (handle as { cohortEpoch: Uint8Array }).cohortEpoch = epoch;
354
460
  }
461
+ (handle as { treeTier: number }).treeTier = landing.treeTier;
462
+ (handle as { cohortMembers: Uint8Array[] }).cohortMembers = landing.cohortMembers;
463
+ (handle as { topicTraffic?: TopicTrafficV1 }).topicTraffic = landing.topicTraffic;
355
464
  }
356
465
 
357
466
  /** The per-probe `RegisterV1` builder: stamps participant coord/ttl/correlation and signs. */
@@ -398,6 +507,9 @@ class WalkRegisterService implements CohortTopicService {
398
507
  if (params.appPayload !== undefined) {
399
508
  body.appPayload = bytesToB64url(params.appPayload);
400
509
  }
510
+ if (params.rootKey !== undefined) {
511
+ body.rootKey = bytesToB64url(params.rootKey);
512
+ }
401
513
  return { ...body, signature: await this.deps.signer.signRegister(body) };
402
514
  },
403
515
  };
@@ -410,6 +522,16 @@ class WalkRegisterService implements CohortTopicService {
410
522
  }
411
523
  }
412
524
 
525
+ /**
526
+ * Reject a root key no cohort would accept. The wire validator refuses an empty or over-long `rootKey`,
527
+ * so sending one would only surface as a remote decode failure; it is a caller error, raised here.
528
+ */
529
+ function assertRootKey(rootKey: Uint8Array | undefined): void {
530
+ if (rootKey !== undefined && (rootKey.length === 0 || rootKey.length > MAX_ROOT_KEY_BYTES)) {
531
+ throw new RangeError(`cohort-topic: rootKey must be 1..${MAX_ROOT_KEY_BYTES} bytes, got ${rootKey.length}`);
532
+ }
533
+ }
534
+
413
535
  /** Build the participant-facing {@link CohortTopicService} over the injected ports. */
414
536
  export function createCohortTopicService(deps: CohortTopicServiceDeps): CohortTopicService {
415
537
  return new WalkRegisterService(deps);
@@ -18,6 +18,7 @@
18
18
  * version to negotiate).
19
19
  */
20
20
 
21
+ import { presentOnly } from "../wire/payloads.js";
21
22
  import type { ChildLinkV1, DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
22
23
 
23
24
  const utf8 = new TextEncoder();
@@ -47,13 +48,17 @@ export function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
47
48
  }
48
49
 
49
50
  /** Fields of a `ChildLinkV1` covered by the child cohort's threshold signature. */
50
- export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch">;
51
+ export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch" | "rootKey">;
51
52
 
52
53
  /**
53
54
  * Canonical signed byte image of a child-link frame. `cohortEpoch` stays **last** so the `/sign` endorser
54
55
  * (`handleSignRequest`) reads the embedded epoch positionally as `image[image.length - 1]`, exactly as it
55
56
  * does for a promotion / demotion notice.
57
+ *
58
+ * `rootKey` (a tier-1 child of a root-placed topic) is covered only when present, and is inserted **before**
59
+ * `cohortEpoch` for that same reason. A link without one keeps the eight-element image unchanged; one
60
+ * with it signs nine elements, so stripping or swapping the key fails verification.
56
61
  */
57
62
  export function childLinkSigningPayload(n: ChildLinkSignable): Uint8Array {
58
- return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, n.cohortEpoch]));
63
+ return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, ...presentOnly(n.rootKey), n.cohortEpoch]));
59
64
  }
@@ -12,13 +12,42 @@
12
12
  * the signature must verify against the payload. Either failure → not verified.
13
13
  */
14
14
 
15
- import type { ICohortThresholdCrypto } from "../ports.js";
15
+ import type { ICohortThresholdCrypto, RootPlacement } from "../ports.js";
16
16
  import { bytesToB64url } from "../wire/codec.js";
17
17
  import type { MembershipCertV1 } from "../wire/types.js";
18
18
 
19
- /** Default cohort-signature threshold, `k − x` (see §Configuration). */
19
+ /** Default cohort-signature threshold, `k − x` (see §Configuration). The rule for every coord that is not root-placed. */
20
20
  export const DEFAULT_MIN_SIGS = 14;
21
21
 
22
+ /**
23
+ * Build the {@link RootPlacement} for a root-placed cohort from this node's own quorum ratio. A ratio
24
+ * outside `(0, 1]` (or not a number) is a configuration error and throws here, at construction, so
25
+ * verification never has to judge a malformed rule. `rootKey` is the routing key the root coordinate is
26
+ * the hash of, when the caller knows it (see {@link RootPlacement.rootKey}); it is carried, never checked
27
+ * here — the anchor that uses it checks that it hashes to the coordinate being judged.
28
+ */
29
+ export function createRootPlacement(quorumRatio: number, rootKey?: Uint8Array): RootPlacement {
30
+ if (!(quorumRatio > 0 && quorumRatio <= 1)) {
31
+ throw new RangeError(`root placement quorumRatio must be in (0, 1], got ${quorumRatio}`);
32
+ }
33
+ return rootKey === undefined ? { quorumRatio } : { quorumRatio, rootKey };
34
+ }
35
+
36
+ /**
37
+ * Signature threshold of a root-placed cohort of `memberCount` members: `ceil(memberCount × quorumRatio)`.
38
+ *
39
+ * This is the formula `captureCommitCert` (`packages/db-p2p/src/cluster/cluster-repo.ts`) applies to a
40
+ * storage group's commit certificate — `ceil(|group| × superMajorityThreshold)` — written the same way on
41
+ * purpose (same multiplication, same rounding), so a commit certificate and a verifier given the same ratio
42
+ * agree on the threshold by construction. One member needs 1; four members at `0.75` need 3.
43
+ *
44
+ * The floor of 1 only matters for an empty member list, where the formula would yield 0 and "no signers"
45
+ * would count as a quorum; with it, a cert naming no members can never verify.
46
+ */
47
+ export function rootPlacedMinSigs(memberCount: number, placement: RootPlacement): number {
48
+ return Math.max(1, Math.ceil(memberCount * placement.quorumRatio));
49
+ }
50
+
22
51
  /** Threshold signer/verifier over the injected cohort crypto. Peer ids are raw bytes. */
23
52
  export interface CohortSigner {
24
53
  /** Assemble a cohort threshold signature over `payload` (collects `minSigs` signers). */
@@ -31,10 +60,10 @@ export interface CohortSigner {
31
60
  }
32
61
 
33
62
  class CryptoCohortSigner implements CohortSigner {
34
- constructor(private readonly crypto: ICohortThresholdCrypto, private readonly minSigs: number) {}
63
+ constructor(private readonly crypto: ICohortThresholdCrypto, private readonly minSigsNow: () => number) {}
35
64
 
36
65
  thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
37
- return this.crypto.assemble(payload, this.minSigs);
66
+ return this.crypto.assemble(payload, this.minSigsNow());
38
67
  }
39
68
 
40
69
  verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean {
@@ -58,7 +87,12 @@ class CryptoCohortSigner implements CohortSigner {
58
87
  }
59
88
  }
60
89
 
61
- /** Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. */
62
- export function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs: number = DEFAULT_MIN_SIGS): CohortSigner {
63
- return new CryptoCohortSigner(crypto, minSigs);
90
+ /**
91
+ * Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. `minSigs` is the assembly
92
+ * threshold: a number for a cohort whose threshold is fixed (the node-wide `k − x`), or a function read at
93
+ * each signing for one whose threshold follows its member count (a root-placed cohort under
94
+ * {@link rootPlacedMinSigs}). Verification takes its threshold as an argument either way.
95
+ */
96
+ export function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs: number | (() => number) = DEFAULT_MIN_SIGS): CohortSigner {
97
+ return new CryptoCohortSigner(crypto, typeof minSigs === "number" ? (): number => minSigs : minSigs);
64
98
  }
@@ -25,6 +25,11 @@
25
25
  * `afterMs` — which begins again at `d_max`, decorrelating retries across the ring (§Anti-flood
26
26
  * claim 4: never re-hit the declined coord immediately).
27
27
  *
28
+ * **Root-placed topics.** A walk given a `rootKey` (§Tier addressing → Root placement at a routing key)
29
+ * stamps it on every frame it builds and addresses its tier-0 step at `H(rootKey)` — delivered through
30
+ * {@link ITopicRouter.routeToRoot} when the router has it, else `routeAndAct` on the root key. Every other
31
+ * step, reply and back-off rule above is unchanged.
32
+ *
28
33
  * This module is FRET-free: it drives the {@link ITopicRouter} port (db-p2p binds it to FRET's
29
34
  * `RouteAndMaybeAct` / direct dial) and the {@link TierAddressing} math, and delegates building +
30
35
  * signing the {@link RegisterV1} to the injected {@link RegisterMessageFactory} (participant identity
@@ -49,6 +54,8 @@ export interface AcceptedWalkOutcome {
49
54
  * probe carries a distinct correlationId; this is the one the cohort admitted.
50
55
  */
51
56
  readonly correlationId: string;
57
+ /** The tree tier `d` of the register frame the cohort accepted — where the registration landed. */
58
+ readonly treeTier: number;
52
59
  }
53
60
 
54
61
  /**
@@ -84,6 +91,7 @@ export interface RegisterMessageFactory {
84
91
  * (§Anti-DoS — a follow-on is gated identically to a bootstrap) via the injected builder seam before
85
92
  * signing — keyed off `bootstrap`/`followOn`, so no extra parameter is needed (the walk decides both
86
93
  * internally, not the application). `bootstrap`, `followOn`, and `probe` are mutually exclusive.
94
+ * A `rootKey` is stamped on the frame as `RegisterV1.rootKey` **before** signing, at every tier.
87
95
  */
88
96
  build(params: {
89
97
  topicId: Uint8Array;
@@ -95,9 +103,19 @@ export interface RegisterMessageFactory {
95
103
  /** Read-only lookup probe: the factory stamps `RegisterV1.probe` and never mints cold-start evidence. */
96
104
  probe: boolean;
97
105
  appPayload?: Uint8Array;
106
+ /** Root key of a root-placed topic; absent for the default addressing. */
107
+ rootKey?: Uint8Array;
98
108
  }): Promise<RegisterV1>;
99
109
  }
100
110
 
111
+ /** Per-walk options for {@link WalkEngine.register}. */
112
+ export interface WalkOptions {
113
+ /** Read-only lookup: classify without admitting, and never cold-start. */
114
+ readonly probe?: boolean;
115
+ /** Root key of a root-placed topic: the walk's tier-0 step targets `H(rootKey)` and every frame carries the key. */
116
+ readonly rootKey?: Uint8Array;
117
+ }
118
+
101
119
  export interface WalkConfig {
102
120
  /** Cohort size requested from the router (`wantK`). Default 16. */
103
121
  wantK?: number;
@@ -139,9 +157,9 @@ export interface WalkEngine {
139
157
  * redirects outward. Resolves with the terminal {@link WalkOutcome}. With `opts.probe` the walk is a
140
158
  * **read-only lookup**: identical routing discipline, but the terminal cohort classifies rather than
141
159
  * admits and the root `no_state` branch backs off instead of issuing a `bootstrap: true` cold-start
142
- * (a probe never instantiates a cold root).
160
+ * (a probe never instantiates a cold root). With `opts.rootKey` the topic is root-placed.
143
161
  */
144
- register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: { probe?: boolean }): Promise<WalkOutcome>;
162
+ register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: WalkOptions): Promise<WalkOutcome>;
145
163
  }
146
164
 
147
165
  /**
@@ -172,10 +190,11 @@ class RouterWalkEngine implements WalkEngine {
172
190
  this.maxMessageBytes = cfg.maxMessageBytes;
173
191
  }
174
192
 
175
- async register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: { probe?: boolean }): Promise<WalkOutcome> {
193
+ async register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: WalkOptions): Promise<WalkOutcome> {
176
194
  const dMax = this.deps.dmax.dMax();
177
195
  const maxSteps = this.configuredMaxSteps ?? 2 * (dMax + 2) + this.maxMemberRetries + 8;
178
196
  const probe = opts?.probe ?? false;
197
+ const rootKey = opts?.rootKey;
179
198
 
180
199
  let d = dMax;
181
200
  let bootstrap = false;
@@ -200,21 +219,18 @@ class RouterWalkEngine implements WalkEngine {
200
219
  return { kind: "retry_later", afterMs: backoffRetryMs(0) };
201
220
  }
202
221
 
203
- const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, followOn, probe, appPayload });
222
+ const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, followOn, probe, appPayload, rootKey });
204
223
  const activity = encodeCohortMessage(reg, this.maxMessageBytes);
205
224
  const raw = dialTarget !== undefined
206
225
  ? await this.deps.router.dialMember(dialTarget, activity)
207
- : await this.deps.router.routeAndAct(this.deps.addressing.coord(d, this.deps.self, topicId), activity, {
208
- wantK: this.wantK,
209
- minSigs: this.minSigs,
210
- });
226
+ : await this.routeToTier(d, topicId, rootKey, activity);
211
227
  const reply = decodeRegisterReplyV1(raw, this.maxMessageBytes);
212
228
 
213
229
  switch (reply.result) {
214
230
  case "accepted": {
215
231
  // Surface the accepted probe's correlationId so the participant's renewals can echo it
216
232
  // (RenewV1 correlationId "matches original RegisterV1"). `reg` is the frame just admitted.
217
- return { kind: "accepted", reply, correlationId: reg.correlationId };
233
+ return { kind: "accepted", reply, correlationId: reg.correlationId, treeTier: reg.treeTier };
218
234
  }
219
235
  case "no_state": {
220
236
  // Step toward the root. The cohort served nothing here; no spatial sibling state.
@@ -318,6 +334,27 @@ class RouterWalkEngine implements WalkEngine {
318
334
  }
319
335
  }
320
336
  }
337
+
338
+ /**
339
+ * Route one probe to the cohort at tier `d`, on that tier's route key — the router hashes it once into
340
+ * `coord_d`. The root of a root-placed topic goes through the router's `routeToRoot` when it has one, so
341
+ * the frame reaches the root group by the rule that chose it; a router without it (a mock, an older
342
+ * binding) routes the same frame on the root key itself, which lands at the root coordinate `H(rootKey)`.
343
+ *
344
+ * NOTE: the fallback reaches the root coordinate by ring routing, which is the root group whenever the
345
+ * ring's nearest peers to `H(rootKey)` are the key network's storage group for that key. `routeToRoot`
346
+ * exists only because the two can differ on a ring shared with another network.
347
+ */
348
+ private routeToTier(d: number, topicId: Uint8Array, rootKey: Uint8Array | undefined, activity: Uint8Array): Promise<Uint8Array> {
349
+ const router = this.deps.router;
350
+ if (d === 0 && rootKey !== undefined && router.routeToRoot !== undefined) {
351
+ return router.routeToRoot(rootKey, activity);
352
+ }
353
+ return router.routeAndAct(this.deps.addressing.routeKey(d, this.deps.self, topicId, rootKey), activity, {
354
+ wantK: this.wantK,
355
+ minSigs: this.minSigs,
356
+ });
357
+ }
321
358
  }
322
359
 
323
360
  /** Build a {@link WalkEngine} over the injected router, addressing, `d_max`, and message factory. */