@optimystic/db-core 1.20.1 → 1.22.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 (77) hide show
  1. package/dist/src/btree/btree.d.ts +36 -4
  2. package/dist/src/btree/btree.d.ts.map +1 -1
  3. package/dist/src/btree/btree.js +86 -18
  4. package/dist/src/btree/btree.js.map +1 -1
  5. package/dist/src/cohort-topic/gossip/bus.d.ts +15 -14
  6. package/dist/src/cohort-topic/gossip/bus.d.ts.map +1 -1
  7. package/dist/src/cohort-topic/gossip/bus.js +15 -16
  8. package/dist/src/cohort-topic/gossip/bus.js.map +1 -1
  9. package/dist/src/cohort-topic/ports.d.ts +30 -4
  10. package/dist/src/cohort-topic/ports.d.ts.map +1 -1
  11. package/dist/src/cohort-topic/ports.js +14 -0
  12. package/dist/src/cohort-topic/ports.js.map +1 -1
  13. package/dist/src/cohort-topic/registration/renewal.d.ts +27 -1
  14. package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
  15. package/dist/src/cohort-topic/registration/renewal.js +15 -4
  16. package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
  17. package/dist/src/cohort-topic/service.d.ts +21 -4
  18. package/dist/src/cohort-topic/service.d.ts.map +1 -1
  19. package/dist/src/cohort-topic/service.js +208 -18
  20. package/dist/src/cohort-topic/service.js.map +1 -1
  21. package/dist/src/cohort-topic/willingness.d.ts +1 -1
  22. package/dist/src/cohort-topic/willingness.js +1 -1
  23. package/dist/src/cohort-topic/wire/codec.d.ts +3 -1
  24. package/dist/src/cohort-topic/wire/codec.d.ts.map +1 -1
  25. package/dist/src/cohort-topic/wire/codec.js +7 -1
  26. package/dist/src/cohort-topic/wire/codec.js.map +1 -1
  27. package/dist/src/cohort-topic/wire/index.d.ts +1 -1
  28. package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
  29. package/dist/src/cohort-topic/wire/index.js +1 -1
  30. package/dist/src/cohort-topic/wire/index.js.map +1 -1
  31. package/dist/src/cohort-topic/wire/types.d.ts +17 -1
  32. package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
  33. package/dist/src/cohort-topic/wire/validate.d.ts +15 -1
  34. package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
  35. package/dist/src/cohort-topic/wire/validate.js +39 -0
  36. package/dist/src/cohort-topic/wire/validate.js.map +1 -1
  37. package/dist/src/collection/collection.d.ts +43 -5
  38. package/dist/src/collection/collection.d.ts.map +1 -1
  39. package/dist/src/collection/collection.js +60 -13
  40. package/dist/src/collection/collection.js.map +1 -1
  41. package/dist/src/collection/struct.d.ts +6 -0
  42. package/dist/src/collection/struct.d.ts.map +1 -1
  43. package/dist/src/collection/struct.js.map +1 -1
  44. package/dist/src/collections/tree/tree.d.ts +3 -1
  45. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  46. package/dist/src/collections/tree/tree.js +11 -5
  47. package/dist/src/collections/tree/tree.js.map +1 -1
  48. package/dist/src/network/struct.d.ts +15 -0
  49. package/dist/src/network/struct.d.ts.map +1 -1
  50. package/dist/src/network/struct.js.map +1 -1
  51. package/dist/src/testing/test-transactor.js +6 -2
  52. package/dist/src/testing/test-transactor.js.map +1 -1
  53. package/dist/src/transaction/coordinator.d.ts +6 -0
  54. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  55. package/dist/src/transaction/coordinator.js +6 -0
  56. package/dist/src/transaction/coordinator.js.map +1 -1
  57. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  58. package/dist/src/transactor/network-transactor.js +1 -0
  59. package/dist/src/transactor/network-transactor.js.map +1 -1
  60. package/package.json +1 -1
  61. package/src/btree/btree.ts +92 -18
  62. package/src/cohort-topic/gossip/bus.ts +25 -26
  63. package/src/cohort-topic/ports.ts +31 -4
  64. package/src/cohort-topic/registration/renewal.ts +40 -5
  65. package/src/cohort-topic/service.ts +251 -21
  66. package/src/cohort-topic/willingness.ts +1 -1
  67. package/src/cohort-topic/wire/codec.ts +12 -0
  68. package/src/cohort-topic/wire/index.ts +3 -0
  69. package/src/cohort-topic/wire/types.ts +20 -0
  70. package/src/cohort-topic/wire/validate.ts +45 -0
  71. package/src/collection/collection.ts +3098 -3039
  72. package/src/collection/struct.ts +463 -456
  73. package/src/collections/tree/tree.ts +15 -7
  74. package/src/network/struct.ts +770 -755
  75. package/src/testing/test-transactor.ts +5 -2
  76. package/src/transaction/coordinator.ts +6 -0
  77. package/src/transactor/network-transactor.ts +1897 -1896
@@ -12,8 +12,9 @@
12
12
  * a cohort member (`docs/cohort-topic.md` §FRET integration — all four protocols on one node).
13
13
  *
14
14
  * Composition wired here: {@link WalkEngine} (lookup / register), the `d_max` computer + tier
15
- * addressing, the participant-side {@link RenewalParticipant} (the `ttl/3` ping with crash-failover),
16
- * and the application integration hooks ({@link CohortGossipBus}, {@link MembershipVerifier}). The
15
+ * addressing, the participant-side {@link RenewalParticipant} (the `ttl/3` ping with crash-failover,
16
+ * whose pings {@link CohortTopicService.renewMany} sends one request per primary), and the application
17
+ * integration hooks ({@link CohortGossipBus}, {@link MembershipVerifier}). The
17
18
  * cohort-side modules (willingness, promotion, traffic, store, membership publisher, anti-DoS) are
18
19
  * assembled by the member engine the FRET host wires into the `RouteAndMaybeAct` activity callback.
19
20
  */
@@ -22,10 +23,11 @@ import { randomBytes } from "@noble/hashes/utils.js";
22
23
  import { createTierAddressing, type TierAddressing } from "./addressing.js";
23
24
  import { makeDMaxComputer, type DMaxComputer } from "./dmax.js";
24
25
  import { DEFAULT_FANOUT } from "./addressing.js";
25
- import type { ISizeEstimator, ITopicRouter, IRingHash } from "./ports.js";
26
+ import { RenewBatchUnsupportedError, type ISizeEstimator, type ITopicRouter, type IRingHash, type PeerRef } from "./ports.js";
26
27
  import { createWalkEngine, type AcceptedWalkOutcome, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
27
28
  import {
28
29
  createRenewalParticipant,
30
+ type PreparedPing,
29
31
  type RenewalAssignment,
30
32
  type RenewalParticipant,
31
33
  type RenewalParticipantTransport,
@@ -33,14 +35,24 @@ import {
33
35
  } from "./registration/renewal.js";
34
36
  import type { RegistrationRecord } from "./registration/types.js";
35
37
  import { DEFAULT_TTL_MS } from "./registration/types.js";
36
- import { recordKey } from "./registration/bytes.js";
38
+ import { bytesKey, recordKey } from "./registration/bytes.js";
37
39
  import type { CohortGossipBus } from "./gossip/bus.js";
38
40
  import type { MembershipVerifier } from "./membership/verifier.js";
39
41
  import type { Tier } from "./tiers.js";
40
- import { bytesToB64url, b64urlToBytes, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
41
- import { MAX_ROOT_KEY_BYTES } from "./wire/validate.js";
42
- import type { RegisterV1, RenewReplyV1, TopicTrafficV1 } from "./wire/types.js";
42
+ import { bytesToB64url, b64urlToBytes, decodeRenewBatchReplyV1, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
43
+ import { CohortWireError, MAX_RENEW_BATCH_ENTRIES, MAX_ROOT_KEY_BYTES } from "./wire/validate.js";
44
+ import type { RegisterV1, RenewBatchV1, RenewReplyV1, RenewV1, TopicTrafficV1 } from "./wire/types.js";
43
45
  import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
46
+ import { createLogger } from "../logger.js";
47
+
48
+ const log = createLogger("cohort-topic:service");
49
+
50
+ /**
51
+ * How long a member that refused the renew-batch protocol (a build that predates it) is sent single pings before
52
+ * a batch is tried again: an older member then costs one refused negotiation per interval, and an upgraded one is
53
+ * batched to again within it.
54
+ */
55
+ export const RENEW_BATCH_UNSUPPORTED_RECHECK_MS = 10 * 60 * 1000;
44
56
 
45
57
  /** A resolved cohort for a topic/tier — the return of {@link CohortTopicService.lookup}. */
46
58
  export interface CohortHint {
@@ -118,8 +130,18 @@ export interface RegisterRequest {
118
130
  export interface CohortTopicService {
119
131
  /** Walk → register for `topicId` at `tier`; resolves a live {@link RegistrationHandle} or throws {@link CohortBackoffError}. */
120
132
  register(req: RegisterRequest): Promise<RegistrationHandle>;
121
- /** Run one `ttl/3` renewal cycle for `handle` (handles `primary_moved` + crash-failover). */
133
+ /** Run one `ttl/3` renewal cycle for `handle` (handles `primary_moved` + crash-failover): {@link renewMany} of one. */
122
134
  renew(handle: RegistrationHandle): Promise<void>;
135
+ /**
136
+ * Run one renewal cycle for each of `handles`, sending the plain pings bound for one member in one request
137
+ * (§TTL and renewal) — singly to a member that does not speak the batch protocol. Each registration is answered
138
+ * and acted on exactly as a single renewal would be. Skipped: a stale or withdrawn handle, and a registration
139
+ * whose previous cycle is still running (usually a failover held up by a re-walk), so no two cycles of one
140
+ * registration run side by side. A handle displaced or withdrawn while its ping was out is not acted on, so it
141
+ * never fails over. Resolves once every cycle has; when some threw, rejects after all of them with that error,
142
+ * or an `AggregateError` of them when several did.
143
+ */
144
+ renewMany(handles: readonly RegistrationHandle[]): Promise<void>;
123
145
  /**
124
146
  * Resolve the cohort for `topicId` at `tier` without keeping a live registration. `rootKey` names the
125
147
  * root of a root-placed topic (see {@link RegisterRequest.rootKey}).
@@ -235,6 +257,20 @@ interface LiveRenewal {
235
257
  readonly renewal: RenewalParticipant;
236
258
  readonly root: RootKeySlot;
237
259
  readonly landing: WalkLanding;
260
+ /** The renewal cycle running for it, if one is; {@link CohortTopicService.renewMany} skips it until that cycle ends. */
261
+ cycle: RenewalCycle | undefined;
262
+ }
263
+
264
+ /** One registration {@link CohortTopicService.renewMany} is running a cycle for. */
265
+ interface RenewalCycle {
266
+ readonly handle: RegistrationHandle;
267
+ readonly live: LiveRenewal;
268
+ }
269
+
270
+ /** The prepared pings bound for one member, by their position in the cycle list. */
271
+ interface PingGroup {
272
+ readonly target: Uint8Array;
273
+ readonly positions: number[];
238
274
  }
239
275
 
240
276
  class WalkRegisterService implements CohortTopicService {
@@ -248,6 +284,13 @@ class WalkRegisterService implements CohortTopicService {
248
284
  private readonly maxMessageBytes?: number;
249
285
  /** Live renewals, keyed by `(topicId, participantId)` so renew/withdraw/moveRoot find their handle. */
250
286
  private readonly renewals = new Map<string, LiveRenewal>();
287
+ /**
288
+ * Members that refused the renew-batch protocol, by `bytesKey`, with the time after which a batch is tried again.
289
+ * NOTE: bounded by the distinct primaries this node renews with, and an entry is dropped only when read after it
290
+ * expires; if a node ever renews with very many distinct primaries, cap it.
291
+ */
292
+ private readonly batchUnsupportedUntil = new Map<string, number>();
293
+ private readonly dialRenewBatch: ((member: PeerRef, frame: Uint8Array) => Promise<Uint8Array>) | undefined;
251
294
  private readonly participantId: Uint8Array;
252
295
 
253
296
  constructor(private readonly deps: CohortTopicServiceDeps) {
@@ -256,6 +299,7 @@ class WalkRegisterService implements CohortTopicService {
256
299
  this.clock = deps.clock ?? ((): number => Date.now());
257
300
  this.ttl = cfg.ttl ?? DEFAULT_TTL_MS;
258
301
  this.maxMessageBytes = cfg.maxMessageBytes;
302
+ this.dialRenewBatch = deps.router.dialMemberRenewBatch?.bind(deps.router);
259
303
  // The participant identity carried on the wire (`participantCoord` on register, `participantId`
260
304
  // on renew) IS `self` — the dialable peer id db-p2p supplies via its peer-codec. It is the
261
305
  // record key the cohort stores AND the signer id its peer-key signature verifies against, so it
@@ -294,16 +338,25 @@ class WalkRegisterService implements CohortTopicService {
294
338
  return this.hintFromReply(topicId, tier, outcome, rootKey);
295
339
  }
296
340
 
297
- async renew(handle: RegistrationHandle): Promise<void> {
298
- // Act only if this handle is still the live entry. A stale handle (superseded by a second
299
- // register() for the same pair) must not drive the new registration's ping loop, and a
300
- // withdrawn handle must not silently re-start it.
301
- const live = this.liveRenewal(handle);
302
- if (live === undefined) {
341
+ renew(handle: RegistrationHandle): Promise<void> {
342
+ return this.renewMany([handle]);
343
+ }
344
+
345
+ async renewMany(handles: readonly RegistrationHandle[]): Promise<void> {
346
+ const cycles = this.beginCycles(handles);
347
+ if (cycles.length === 0) {
303
348
  return;
304
349
  }
305
- await handle.renewal.pingLoop();
306
- this.syncHandle(handle, live.landing);
350
+ try {
351
+ const pings = await Promise.all(cycles.map((cycle) => this.preparePing(cycle)));
352
+ // Every send finishes before anything is settled, so one registration's failover (re-attaches, then a
353
+ // re-walk) never holds back another's ping.
354
+ const answers = await this.sendPings(pings);
355
+ throwFailures(await this.settleCycles(cycles, answers));
356
+ } finally {
357
+ // Each cycle has ended by now, its own settle having ended it; this covers a throw before settling.
358
+ cycles.forEach(endCycle);
359
+ }
307
360
  }
308
361
 
309
362
  moveRoot(handle: RegistrationHandle, rootKey: Uint8Array): void {
@@ -362,6 +415,142 @@ class WalkRegisterService implements CohortTopicService {
362
415
  return live?.renewal === handle.renewal ? live : undefined;
363
416
  }
364
417
 
418
+ /**
419
+ * Mark and return the registrations among `handles` a cycle may run for: live (a stale handle must not drive the
420
+ * registration that displaced it, nor a withdrawn one re-start its pings) and not already renewing. A handle
421
+ * named twice is taken once.
422
+ */
423
+ private beginCycles(handles: readonly RegistrationHandle[]): RenewalCycle[] {
424
+ const cycles: RenewalCycle[] = [];
425
+ for (const handle of handles) {
426
+ const live = this.liveRenewal(handle);
427
+ if (live === undefined || live.cycle !== undefined) {
428
+ continue;
429
+ }
430
+ const cycle: RenewalCycle = { handle, live };
431
+ live.cycle = cycle;
432
+ cycles.push(cycle);
433
+ }
434
+ return cycles;
435
+ }
436
+
437
+ /** The cycle's signed ping, or `undefined` when signing failed — a failed ping, as a single renewal counts it. */
438
+ private async preparePing({ handle, live }: RenewalCycle): Promise<PreparedPing | undefined> {
439
+ try {
440
+ return await live.renewal.preparePing();
441
+ } catch (err) {
442
+ log("renew ping for topic %s could not be signed (a failed ping): %o", bytesKey(handle.topicId), err);
443
+ return undefined;
444
+ }
445
+ }
446
+
447
+ /** Send every prepared ping and return each one's answer by position, `undefined` for none. Never rejects. */
448
+ private async sendPings(pings: ReadonlyArray<PreparedPing | undefined>): Promise<(RenewReplyV1 | undefined)[]> {
449
+ const answers = new Array<RenewReplyV1 | undefined>(pings.length).fill(undefined);
450
+ const sends = groupByTarget(pings).flatMap(({ target, positions }) =>
451
+ chunked(positions, MAX_RENEW_BATCH_ENTRIES).map(async (chunk) => {
452
+ const replies = await this.sendToMember(target, chunk.map((position) => pings[position]!.msg));
453
+ chunk.forEach((position, i) => {
454
+ answers[position] = replies[i];
455
+ });
456
+ }));
457
+ await Promise.all(sends);
458
+ return answers;
459
+ }
460
+
461
+ /**
462
+ * Send `msgs` to `target` as one batch frame when that can work, else singly. A member that does not speak the
463
+ * batch protocol is sent the same pings singly at once, and remembered. Any other batch failure — the link, or a
464
+ * reply that is malformed or of the wrong length — is no answer for every ping in it, as the same pings sent
465
+ * singly over that link would each have been. Never rejects.
466
+ */
467
+ private async sendToMember(target: Uint8Array, msgs: readonly RenewV1[]): Promise<(RenewReplyV1 | undefined)[]> {
468
+ const dialBatch = this.dialRenewBatch;
469
+ if (msgs.length === 1 || dialBatch === undefined || this.refusedBatches(target)) {
470
+ return this.sendSingly(target, msgs);
471
+ }
472
+ try {
473
+ return await this.sendBatch(dialBatch, target, msgs);
474
+ } catch (err) {
475
+ if (err instanceof RenewBatchUnsupportedError) {
476
+ this.batchUnsupportedUntil.set(bytesKey(target), this.clock() + RENEW_BATCH_UNSUPPORTED_RECHECK_MS);
477
+ return this.sendSingly(target, msgs);
478
+ }
479
+ log("renew batch of %d pings to %s got no usable answer (each a failed ping): %o", msgs.length, bytesKey(target), err);
480
+ return msgs.map(() => undefined);
481
+ }
482
+ }
483
+
484
+ private async sendBatch(
485
+ dialBatch: (member: PeerRef, frame: Uint8Array) => Promise<Uint8Array>,
486
+ target: Uint8Array,
487
+ msgs: readonly RenewV1[],
488
+ ): Promise<RenewReplyV1[]> {
489
+ const batch: RenewBatchV1 = { v: 1, renews: [...msgs] };
490
+ const raw = await dialBatch({ id: target }, encodeCohortMessage(batch, this.maxMessageBytes));
491
+ const { replies } = decodeRenewBatchReplyV1(raw, this.maxMessageBytes);
492
+ if (replies.length !== msgs.length) {
493
+ throw new CohortWireError(`RenewBatchReplyV1: ${replies.length} replies to a batch of ${msgs.length} pings`);
494
+ }
495
+ return replies;
496
+ }
497
+
498
+ private sendSingly(target: Uint8Array, msgs: readonly RenewV1[]): Promise<(RenewReplyV1 | undefined)[]> {
499
+ return Promise.all(msgs.map(async (msg) => {
500
+ try {
501
+ return await this.sendRenew(target, msg);
502
+ } catch (err) {
503
+ log("renew ping to %s got no answer (a failed ping): %o", bytesKey(target), err);
504
+ return undefined;
505
+ }
506
+ }));
507
+ }
508
+
509
+ /** One renew — ping, re-attach or withdraw — to `target` over the router's direct dial. */
510
+ private async sendRenew(target: Uint8Array, msg: RenewV1): Promise<RenewReplyV1> {
511
+ const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
512
+ return decodeRenewReplyV1(raw, this.maxMessageBytes);
513
+ }
514
+
515
+ /** Whether `target` refused the batch protocol within the last {@link RENEW_BATCH_UNSUPPORTED_RECHECK_MS}; an expired entry is dropped. */
516
+ private refusedBatches(target: Uint8Array): boolean {
517
+ const key = bytesKey(target);
518
+ const until = this.batchUnsupportedUntil.get(key);
519
+ if (until === undefined) {
520
+ return false;
521
+ }
522
+ if (this.clock() < until) {
523
+ return true;
524
+ }
525
+ this.batchUnsupportedUntil.delete(key);
526
+ return false;
527
+ }
528
+
529
+ /** Settle every cycle with its answer, side by side; resolves, once all have, with what the ones that threw threw. */
530
+ private async settleCycles(cycles: readonly RenewalCycle[], answers: ReadonlyArray<RenewReplyV1 | undefined>): Promise<unknown[]> {
531
+ const outcomes = await Promise.allSettled(cycles.map((cycle, i) => this.settleCycle(cycle, answers[i])));
532
+ return outcomes.flatMap((outcome): unknown[] => (outcome.status === "rejected" ? [outcome.reason] : []));
533
+ }
534
+
535
+ /**
536
+ * Act on one cycle's answer — unless a later register displaced the handle (a tail follow at the root) or it was
537
+ * withdrawn while its ping was out. Settling a displaced registration's strikes would fail it over and re-walk
538
+ * it; its record at the old cohort expires by TTL instead. The cycle ends when this does, not when the slowest
539
+ * cycle of the same call does, so another registration's long failover does not keep this one out of the next call.
540
+ */
541
+ private async settleCycle(cycle: RenewalCycle, answer: RenewReplyV1 | undefined): Promise<void> {
542
+ const { handle, live } = cycle;
543
+ try {
544
+ if (this.liveRenewal(handle) !== live) {
545
+ return;
546
+ }
547
+ await live.renewal.settlePing(answer);
548
+ this.syncHandle(handle, live.landing);
549
+ } finally {
550
+ endCycle(cycle);
551
+ }
552
+ }
553
+
365
554
  private startRenewal(req: RegisterRequest, hint: CohortHint, correlationId: string): RenewalParticipant {
366
555
  const ttl = req.ttl ?? this.ttl;
367
556
  const initial: RegistrationRecord = {
@@ -398,7 +587,7 @@ class WalkRegisterService implements CohortTopicService {
398
587
  // record still lives at the old one, and a machine in both roots' storage groups holds both; a
399
588
  // tombstone resolves through the host's `findHolder`, which picks the newer record there, so it would
400
589
  // 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 });
590
+ this.renewals.set(recordKey(req.topicId, this.participantId), { renewal, root, landing, cycle: undefined });
402
591
  return renewal;
403
592
  }
404
593
 
@@ -410,10 +599,7 @@ class WalkRegisterService implements CohortTopicService {
410
599
  */
411
600
  private renewalTransport(req: RegisterRequest, root: RootKeySlot, landing: WalkLanding): RenewalParticipantTransport {
412
601
  return {
413
- send: async (target: Uint8Array, msg): Promise<RenewReplyV1> => {
414
- const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
415
- return decodeRenewReplyV1(raw, this.maxMessageBytes);
416
- },
602
+ send: (target: Uint8Array, msg): Promise<RenewReplyV1> => this.sendRenew(target, msg),
417
603
  relookup: async (): Promise<RenewalAssignment | undefined> => {
418
604
  // NOTE: re-sends the first registration's `appPayload` (for a collection watch, its `tailIdAtAttach`
419
605
  // and `lastKnownRev`). No cohort reads those fields off a held record today; if one ever does, the
@@ -532,6 +718,50 @@ function assertRootKey(rootKey: Uint8Array | undefined): void {
532
718
  }
533
719
  }
534
720
 
721
+ /** The prepared pings grouped by the member each goes to, in first-seen order; an unprepared one is in no group. */
722
+ function groupByTarget(pings: ReadonlyArray<PreparedPing | undefined>): PingGroup[] {
723
+ const groups = new Map<string, PingGroup>();
724
+ pings.forEach((ping, position) => {
725
+ if (ping === undefined) {
726
+ return;
727
+ }
728
+ const key = bytesKey(ping.target);
729
+ const group = groups.get(key);
730
+ if (group !== undefined) {
731
+ group.positions.push(position);
732
+ } else {
733
+ groups.set(key, { target: ping.target, positions: [position] });
734
+ }
735
+ });
736
+ return [...groups.values()];
737
+ }
738
+
739
+ /** `items` in consecutive runs of at most `size`. */
740
+ function chunked<T>(items: readonly T[], size: number): T[][] {
741
+ const chunks: T[][] = [];
742
+ for (let i = 0; i < items.length; i += size) {
743
+ chunks.push(items.slice(i, i + size));
744
+ }
745
+ return chunks;
746
+ }
747
+
748
+ /** Release the registration `cycle` ran for — only if that cycle still holds it, never a later call's cycle. */
749
+ function endCycle(cycle: RenewalCycle): void {
750
+ if (cycle.live.cycle === cycle) {
751
+ cycle.live.cycle = undefined;
752
+ }
753
+ }
754
+
755
+ /** Rethrow what the settled cycles threw: the one error itself, or an `AggregateError` when several threw. */
756
+ function throwFailures(failures: readonly unknown[]): void {
757
+ if (failures.length === 1) {
758
+ throw failures[0];
759
+ }
760
+ if (failures.length > 1) {
761
+ throw new AggregateError(failures, `cohort-topic: ${failures.length} renewal cycles failed`);
762
+ }
763
+ }
764
+
535
765
  /** Build the participant-facing {@link CohortTopicService} over the injected ports. */
536
766
  export function createCohortTopicService(deps: CohortTopicServiceDeps): CohortTopicService {
537
767
  return new WalkRegisterService(deps);
@@ -88,7 +88,7 @@ export function willingnessBitsHex(bits: number): string {
88
88
  * This member's gossiped (coarse) willingness vector: bit `t` set iff the profile serves `t` and the
89
89
  * tier is not shed under load. The per-tier primary-topic budget is deliberately **not** folded in
90
90
  * — it is a live per-registration gate, not a gossiped signal (§Willingness: the gossiped vector is
91
- * "one bit per tier per member… refreshed every gossip round").
91
+ * "one bit per tier per member, sent on the next gossip round whenever it changes").
92
92
  */
93
93
  export function selfWillingnessBits(self: NodeProfile, barometer: LoadBarometerState): number {
94
94
  return packWillingnessBits((t) => self.willingTiers.has(t) && barometer.loadWilling(t));
@@ -20,6 +20,8 @@ import {
20
20
  validatePromotionNoticeV1,
21
21
  validateRegisterReplyV1,
22
22
  validateRegisterV1,
23
+ validateRenewBatchReplyV1,
24
+ validateRenewBatchV1,
23
25
  validateRenewReplyV1,
24
26
  validateRenewV1,
25
27
  validateSignRequestV1,
@@ -34,6 +36,8 @@ import type {
34
36
  PromotionNoticeV1,
35
37
  RegisterReplyV1,
36
38
  RegisterV1,
39
+ RenewBatchReplyV1,
40
+ RenewBatchV1,
37
41
  RenewReplyV1,
38
42
  RenewV1,
39
43
  SignRequestV1,
@@ -189,6 +193,14 @@ export function decodeRenewReplyV1(bytes: Uint8Array, maxMessageBytes?: number):
189
193
  return validateRenewReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
190
194
  }
191
195
 
196
+ export function decodeRenewBatchV1(bytes: Uint8Array, maxMessageBytes?: number): RenewBatchV1 {
197
+ return validateRenewBatchV1(decodeCohortMessage(bytes, maxMessageBytes));
198
+ }
199
+
200
+ export function decodeRenewBatchReplyV1(bytes: Uint8Array, maxMessageBytes?: number): RenewBatchReplyV1 {
201
+ return validateRenewBatchReplyV1(decodeCohortMessage(bytes, maxMessageBytes));
202
+ }
203
+
192
204
  export function decodeChildLinkV1(bytes: Uint8Array, maxMessageBytes?: number, minSigs?: number): ChildLinkV1 {
193
205
  return validateChildLinkV1(decodeCohortMessage(bytes, maxMessageBytes), minSigs);
194
206
  }
@@ -4,10 +4,13 @@ export * from "./payloads.js";
4
4
  export { CohortWireError } from "./validate.js";
5
5
  export {
6
6
  MAX_ROOT_KEY_BYTES,
7
+ MAX_RENEW_BATCH_ENTRIES,
7
8
  validateRegisterV1,
8
9
  validateRegisterReplyV1,
9
10
  validateRenewV1,
10
11
  validateRenewReplyV1,
12
+ validateRenewBatchV1,
13
+ validateRenewBatchReplyV1,
11
14
  validateChildLinkV1,
12
15
  validateChildLinkReplyV1,
13
16
  validatePromotionNoticeV1,
@@ -170,6 +170,24 @@ export interface RenewReplyV1 {
170
170
  cohortEpoch?: string;
171
171
  }
172
172
 
173
+ /**
174
+ * Several plain renewal pings to one cohort member, in one frame (`/renew-batch`). Each entry is a complete,
175
+ * individually signed {@link RenewV1}, byte-for-byte what a single ping sends. Only plain pings travel this
176
+ * way: an entry carrying `reattach` or `withdraw` makes the whole frame malformed, since those are judged per
177
+ * record by the member's freshness gate and keep going singly over `/register`.
178
+ */
179
+ export interface RenewBatchV1 {
180
+ v: 1;
181
+ /** 1..`MAX_RENEW_BATCH_ENTRIES` plain pings. */
182
+ renews: RenewV1[];
183
+ }
184
+
185
+ /** The answer to a {@link RenewBatchV1}: one {@link RenewReplyV1} per entry, same length and order. */
186
+ export interface RenewBatchReplyV1 {
187
+ v: 1;
188
+ replies: RenewReplyV1[];
189
+ }
190
+
173
191
  /**
174
192
  * Child cohort → parent cohort link: "I am the tier-`d` cohort at {@link childCohortCoord}; record me as
175
193
  * your child." A freshly cold-started deeper forwarder sends this to its tier-`(d − 1)` parent (routed the
@@ -506,6 +524,8 @@ export type CohortMessageV1 =
506
524
  | RegisterReplyV1
507
525
  | RenewV1
508
526
  | RenewReplyV1
527
+ | RenewBatchV1
528
+ | RenewBatchReplyV1
509
529
  | ChildLinkV1
510
530
  | ChildLinkReplyV1
511
531
  | PromotionNoticeV1
@@ -44,6 +44,8 @@ import type {
44
44
  RegisterReplyV1,
45
45
  RegisterResult,
46
46
  RegisterV1,
47
+ RenewBatchReplyV1,
48
+ RenewBatchV1,
47
49
  RenewReplyV1,
48
50
  RenewV1,
49
51
  SignKind,
@@ -227,6 +229,49 @@ export function validateRenewReplyV1(value: unknown): RenewReplyV1 {
227
229
  return out;
228
230
  }
229
231
 
232
+ /**
233
+ * Most pings one {@link RenewBatchV1} carries. A `RenewV1` encodes to a few hundred bytes, so a full batch is
234
+ * far under the frame ceiling; it also bounds the member's work for one frame at that many record lookups. A
235
+ * sender with more pings for one member splits them over several frames.
236
+ */
237
+ export const MAX_RENEW_BATCH_ENTRIES = 64;
238
+
239
+ /** `value[field]` as an array of 1..{@link MAX_RENEW_BATCH_ENTRIES} entries. */
240
+ function batchEntries(obj: Record<string, unknown>, field: string, what: string): unknown[] {
241
+ const entries = obj[field];
242
+ if (!Array.isArray(entries) || entries.length === 0 || entries.length > MAX_RENEW_BATCH_ENTRIES) {
243
+ fail(`${what}: field "${field}" must be an array of 1..${MAX_RENEW_BATCH_ENTRIES} entries`);
244
+ }
245
+ return entries;
246
+ }
247
+
248
+ /**
249
+ * Validate a {@link RenewBatchV1}: 1..{@link MAX_RENEW_BATCH_ENTRIES} entries, each a valid `RenewV1` carrying
250
+ * neither `reattach` nor `withdraw` (present at all, whatever its value). Those two are privileged and judged per
251
+ * record by the member's freshness gate, so a batch may not carry one past it.
252
+ */
253
+ export function validateRenewBatchV1(value: unknown): RenewBatchV1 {
254
+ const what = "RenewBatchV1";
255
+ const obj = asObject(value, what);
256
+ requireV1(obj, what);
257
+ const renews = batchEntries(obj, "renews", what).map((entry) => {
258
+ const renew = validateRenewV1(entry);
259
+ if (renew.reattach !== undefined || renew.withdraw !== undefined) {
260
+ fail(`${what}: an entry may be a plain ping only (no reattach, no withdraw)`);
261
+ }
262
+ return renew;
263
+ });
264
+ return { v: 1, renews };
265
+ }
266
+
267
+ /** Validate a {@link RenewBatchReplyV1}: 1..{@link MAX_RENEW_BATCH_ENTRIES} valid `RenewReplyV1`s. Matching the request's length is the sender's check. */
268
+ export function validateRenewBatchReplyV1(value: unknown): RenewBatchReplyV1 {
269
+ const what = "RenewBatchReplyV1";
270
+ const obj = asObject(value, what);
271
+ requireV1(obj, what);
272
+ return { v: 1, replies: batchEntries(obj, "replies", what).map(validateRenewReplyV1) };
273
+ }
274
+
230
275
  export function validatePromotionNoticeV1(value: unknown): PromotionNoticeV1 {
231
276
  const what = "PromotionNoticeV1";
232
277
  const obj = asObject(value, what);