@optimystic/db-core 0.13.5 → 0.14.0

package/src/cohort-topic/promotion.ts

@@ -0,0 +1,384 @@
+/**
+ * Cohort-topic substrate — promotion / demotion lifecycle.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Promotion and demotion lifecycle and folded back from the
+ * simulator-validated `packages/substrate-simulator/src/topic-tree.ts`. A forwarder cohort grows
+ * (promotes) and shrinks (demotes) for a topic `T` based on its per-topic direct-participant count
+ * and the per-tier load barometer; both transitions are **threshold-signed** (via the gossip ticket's
+ * {@link CohortSigner}) so participants can verify them.
+ *
+ * **Promote** when, for a quorum (the quorum is enforced by the threshold signature — `minSigs`
+ * signers must agree to the notice):
+ * - `directParticipants(T) ≥ cap_promote` (64), OR
+ * - `loadBucket[tier(T)] ≥ bucket_overload` (6) AND `directParticipants(T) ≥ cap_promote_fast` (32)
+ *   — the hot-load fast path from the capacity-barometer ticket, OR
+ * - the growth **slope** predicts crossing `cap_promote` within `T_promote_lookahead` (30s) — fires
+ *   early to avoid the gossip-lag overshoot (`§Promotion`: pre-promotion on slope).
+ *
+ * Once promoted, the state is **sticky** for ≥ `T_promote_sticky` (60s) before it can be reconsidered
+ * for demotion, so transient count drops don't flap a cohort back to accepting.
+ *
+ * **Demote** when, for a quorum: `directParticipants(T) ≤ cap_demote` (16) AND that has held for
+ * ≥ `T_demote` (5min) AND the cohort has no live child cohorts AND it has a parent (the root, tree
+ * tier 0, never demotes — it has nowhere to hand off). The `4×` gap between `cap_promote` and
+ * `cap_demote` plus `T_demote` is the hysteresis that prevents thrash.
+ *
+ * **Deviation from the doc's interface sketch (documented).** `docs/cohort-topic.md` sketches
+ * `onParticipantCountChange` as returning `void` and "may emit `PromotionNoticeV1`". Because
+ * threshold signing is asynchronous ({@link CohortSigner.thresholdSign} resolves a Promise), the
+ * methods here are `async` and **return** the signed notice (or `undefined`) instead of emitting it
+ * through a side channel — the caller broadcasts whatever it gets back. This keeps the module pure
+ * and unit-testable and avoids an awkward async callback. The op-tier `tier(T)` the barometer is
+ * indexed by is supplied through the injected {@link PromotionDeps.loadBucket} resolver, so this
+ * module never needs to know a topic's tier.
+ *
+ * **Remote apply path.** `promote()` / `demote()` set this cohort's per-topic state as a side effect of
+ * the **local** signing path — only the member that originates a notice adopts the new state that way. A
+ * member that *learns* of a promotion/demotion via gossip or a broadcast notice adopts it through
+ * {@link PromotionLifecycle.applyPromotionNotice} / {@link PromotionLifecycle.applyDemotionNotice},
+ * which set the same {@link PromotionState} **without re-signing** (the notice is already a verified
+ * quorum decision). **Precondition: the caller has already verified the notice's threshold signature**
+ * (db-p2p's `MembershipVerifier`); this module is crypto-free and trusts that gate. The apply path is
+ * idempotent and `effectiveAt`-ordered via the monotonic {@link PromotionState.lastEffectiveAt}
+ * high-water mark, so re-applying a notice (including this member's own echoed broadcast) or a replayed
+ * older notice is a no-op — a stale promotion can never un-demote a cohort that has since demoted.
+ */
+
+import { b64urlToBytes, bytesToB64url } from "./wire/codec.js";
+import type { CohortSigner } from "./sig/threshold.js";
+import { demotionNoticeSigningPayload, promotionNoticeSigningPayload } from "./sig/payloads.js";
+import type { DemotionNoticeV1, PromotionNoticeV1 } from "./wire/types.js";
+import type { RegistrationStore } from "./registration/types.js";
+import { bytesKey } from "./registration/bytes.js";
+
+// --- defaults (docs/cohort-topic.md §Configuration; simulator-confirmed) ---
+
+/** Direct-participant cap before promotion. */
+export const DEFAULT_CAP_PROMOTE = 64;
+/** Direct-participant cap when the load barometer is hot (fast path). */
+export const DEFAULT_CAP_PROMOTE_FAST = 32;
+/** Load-barometer bucket at/above which the fast promote path is armed. */
+export const DEFAULT_BUCKET_OVERLOAD = 6;
+/** Direct-participant floor for demotion (= `cap_promote / 4`). */
+export const DEFAULT_CAP_DEMOTE = 16;
+/** Hysteresis window the low-load condition must hold before demotion (ms). */
+export const DEFAULT_T_DEMOTE_MS = 300_000;
+/** Pre-promotion slope lookahead (ms). */
+export const DEFAULT_T_PROMOTE_LOOKAHEAD_MS = 30_000;
+/** Minimum time a cohort stays promoted before it can be reconsidered for demotion (ms). */
+export const DEFAULT_T_PROMOTE_STICKY_MS = 60_000;
+/**
+ * Slope window over which the growth rate is measured for pre-promotion. **Not pinned by
+ * `docs/cohort-topic.md`** — the simulator (`topic-tree.ts` `DEFAULT_LIFECYCLE_CONFIG`) uses 10s and
+ * this matches it.
+ */
+export const DEFAULT_GROWTH_WINDOW_MS = 10_000;
+
+export interface PromotionConfig {
+	capPromote?: number;
+	capPromoteFast?: number;
+	bucketOverload?: number;
+	capDemote?: number;
+	tDemoteMs?: number;
+	tPromoteLookaheadMs?: number;
+	tPromoteStickyMs?: number;
+	growthWindowMs?: number;
+}
+
+/** A sampled `(time, count)` growth point, for slope-based pre-promotion. */
+interface GrowthSample {
+	readonly t: number;
+	readonly count: number;
+}
+
+/** Per-topic promotion bookkeeping held by this cohort. */
+interface PromotionState {
+	promoted: boolean;
+	/** When the cohort last entered promoted mode (sticky-window anchor). */
+	promotedAt?: number;
+	/** When `directParticipants` last dropped to ≤ `cap_demote` (demotion hysteresis anchor). */
+	lowLoadSince?: number;
+	/** Recent growth samples within `growthWindowMs`, for slope extrapolation. */
+	samples: GrowthSample[];
+	/**
+	 * `effectiveAt` of the most recent promotion/demotion this cohort has adopted — locally originated
+	 * (`promote()` / `demote()`) or remotely applied (`applyPromotionNotice` / `applyDemotionNotice`).
+	 * Monotonic and **never cleared** (a demotion clears `promoted`/`promotedAt` but keeps this), so it
+	 * is the high-water mark the remote-apply path orders against: a notice whose `effectiveAt` is not
+	 * strictly newer is a no-op — re-applied (incl. this member's own echoed broadcast) or stale-replayed.
+	 */
+	lastEffectiveAt?: number;
+}
+
+export interface PromotionDeps {
+	/** Replicated registration store — supplies the per-topic `directParticipants` stock count. */
+	store: Pick<RegistrationStore, "directParticipants">;
+	/**
+	 * Current load-barometer bucket (0..7) for the topic's op tier `tier(T)`. The caller resolves the
+	 * topic→tier mapping and the barometer lookup, keeping this module tier-agnostic and FRET-free.
+	 */
+	loadBucket: (topicId: Uint8Array) => number;
+	/** Live child-cohort count for the topic (0 if none); `> 0` blocks demotion. */
+	childCohortCount: (topicId: Uint8Array) => number;
+	/** Tree tier `d` this cohort serves the topic at — `fromTier` on a notice; `toTier = d + 1`. */
+	treeTier: (topicId: Uint8Array) => number;
+	/** The tier-`(d − 1)` parent cohort coord, target of a {@link DemotionNoticeV1}. */
+	parentCoord: (topicId: Uint8Array) => Uint8Array;
+	/** Cohort epoch (raw bytes) the notices are signed under. */
+	cohortEpoch: () => Uint8Array;
+	/** Threshold signer (the gossip ticket's `k − x` cohort signer). */
+	signer: CohortSigner;
+	config?: PromotionConfig;
+}
+
+/**
+ * Promotion / demotion lifecycle for one cohort across all the topics it serves. Keyed by `topicId`;
+ * each topic carries its own promoted/low-load/sticky state.
+ */
+export interface PromotionLifecycle {
+	/**
+	 * React to a change in `topicId`'s direct-participant count (call after every arrival/eviction).
+	 * Refreshes the growth + hysteresis clocks and, if a promote trigger fires and the cohort is not
+	 * already promoted, threshold-signs and returns a {@link PromotionNoticeV1}. Returns `undefined`
+	 * when no promotion fires.
+	 */
+	onParticipantCountChange(topicId: Uint8Array, now: number): Promise<PromotionNoticeV1 | undefined>;
+	/**
+	 * Time-driven demotion check (call on the gossip tick). Returns a threshold-signed
+	 * {@link DemotionNoticeV1} for the parent when every demotion condition holds, else `undefined`.
+	 */
+	maybeDemote(topicId: Uint8Array, now: number): Promise<DemotionNoticeV1 | undefined>;
+	/** Whether `topicId` is currently in promoted mode (new registrations get `Promoted(d+1)`). */
+	isPromoted(topicId: Uint8Array): boolean;
+	/**
+	 * Adopt a promotion this member did **not** originate (learned via a verified broadcast notice).
+	 * Sets `promoted = true` for `n.topicId` without re-signing. **Precondition: the caller has verified
+	 * `n`'s threshold signature** — this module performs no crypto. Idempotent and `effectiveAt`-ordered
+	 * (see {@link PromotionState.lastEffectiveAt}): a notice not strictly newer than the last adopted
+	 * transition is a no-op, so this member's own echoed broadcast and stale replays are absorbed.
+	 */
+	applyPromotionNotice(n: PromotionNoticeV1, now: number): void;
+	/**
+	 * Adopt a demotion this member did **not** originate (learned via a verified broadcast notice).
+	 * Clears `promoted` state for `n.topicId` without re-signing. Same precondition, idempotency, and
+	 * `effectiveAt` ordering as {@link applyPromotionNotice} — a stale promotion can never un-demote.
+	 */
+	applyDemotionNotice(n: DemotionNoticeV1, now: number): void;
+}
+
+class CohortPromotionLifecycle implements PromotionLifecycle {
+	private readonly states = new Map<string, PromotionState>();
+	private readonly capPromote: number;
+	private readonly capPromoteFast: number;
+	private readonly bucketOverload: number;
+	private readonly capDemote: number;
+	private readonly tDemoteMs: number;
+	private readonly tPromoteLookaheadMs: number;
+	private readonly tPromoteStickyMs: number;
+	private readonly growthWindowMs: number;
+
+	constructor(private readonly deps: PromotionDeps) {
+		const cfg = deps.config ?? {};
+		this.capPromote = cfg.capPromote ?? DEFAULT_CAP_PROMOTE;
+		this.capPromoteFast = cfg.capPromoteFast ?? DEFAULT_CAP_PROMOTE_FAST;
+		this.bucketOverload = cfg.bucketOverload ?? DEFAULT_BUCKET_OVERLOAD;
+		this.capDemote = cfg.capDemote ?? DEFAULT_CAP_DEMOTE;
+		this.tDemoteMs = cfg.tDemoteMs ?? DEFAULT_T_DEMOTE_MS;
+		this.tPromoteLookaheadMs = cfg.tPromoteLookaheadMs ?? DEFAULT_T_PROMOTE_LOOKAHEAD_MS;
+		this.tPromoteStickyMs = cfg.tPromoteStickyMs ?? DEFAULT_T_PROMOTE_STICKY_MS;
+		this.growthWindowMs = cfg.growthWindowMs ?? DEFAULT_GROWTH_WINDOW_MS;
+	}
+
+	async onParticipantCountChange(topicId: Uint8Array, now: number): Promise<PromotionNoticeV1 | undefined> {
+		const state = this.stateFor(topicId);
+		const count = this.deps.store.directParticipants(topicId);
+		this.pushGrowthSample(state, count, now);
+		this.refreshLowLoadClock(state, count, now);
+		if (state.promoted) {
+			return undefined; // already promoted — sticky until a demotion clears it
+		}
+		if (!this.promotionTriggered(topicId, state, count, now)) {
+			return undefined;
+		}
+		return this.promote(topicId, state, now);
+	}
+
+	async maybeDemote(topicId: Uint8Array, now: number): Promise<DemotionNoticeV1 | undefined> {
+		const state = this.states.get(bytesKey(topicId));
+		if (state === undefined) {
+			return undefined;
+		}
+		if (!this.demotionTriggered(topicId, state, now)) {
+			return undefined;
+		}
+		return this.demote(topicId, state, now);
+	}
+
+	isPromoted(topicId: Uint8Array): boolean {
+		return this.states.get(bytesKey(topicId))?.promoted ?? false;
+	}
+
+	// --- remote apply (verified notices this member did not originate) ---
+
+	applyPromotionNotice(n: PromotionNoticeV1, now: number): void {
+		const state = this.stateFor(b64urlToBytes(n.topicId));
+		if (!this.isNewerTransition(state, n.effectiveAt)) {
+			return; // already adopted, our own echoed broadcast, or a stale replay
+		}
+		state.promoted = true;
+		state.promotedAt = now;
+		state.lastEffectiveAt = n.effectiveAt;
+	}
+
+	applyDemotionNotice(n: DemotionNoticeV1, _now: number): void {
+		const state = this.stateFor(b64urlToBytes(n.topicId));
+		if (!this.isNewerTransition(state, n.effectiveAt)) {
+			return;
+		}
+		// Mirror the local demote() release so a later re-growth re-evaluates cleanly.
+		state.promoted = false;
+		state.promotedAt = undefined;
+		state.lowLoadSince = undefined;
+		state.lastEffectiveAt = n.effectiveAt;
+	}
+
+	/** A notice is adopted only if strictly newer than the last transition we adopted (the high-water mark). */
+	private isNewerTransition(state: PromotionState, effectiveAt: number): boolean {
+		return state.lastEffectiveAt === undefined || effectiveAt > state.lastEffectiveAt;
+	}
+
+	// --- promotion ---
+
+	private promotionTriggered(topicId: Uint8Array, state: PromotionState, count: number, now: number): boolean {
+		if (count >= this.capPromote) {
+			return true;
+		}
+		if (this.deps.loadBucket(topicId) >= this.bucketOverload && count >= this.capPromoteFast) {
+			return true;
+		}
+		return this.slopePredictsCrossing(state, count, now);
+	}
+
+	/** Linear extrapolation over the growth window: will `directParticipants` cross `cap_promote` within lookahead? */
+	private slopePredictsCrossing(state: PromotionState, count: number, now: number): boolean {
+		const samples = state.samples;
+		if (samples.length < 2) {
+			return false;
+		}
+		const first = samples[0]!;
+		const last = samples[samples.length - 1]!;
+		const span = last.t - first.t;
+		if (span <= 0) {
+			return false;
+		}
+		const slope = (last.count - first.count) / span; // participants per ms
+		if (slope <= 0) {
+			return false;
+		}
+		const predicted = count + slope * this.tPromoteLookaheadMs;
+		return predicted >= this.capPromote;
+	}
+
+	private async promote(topicId: Uint8Array, state: PromotionState, now: number): Promise<PromotionNoticeV1> {
+		const fromTier = this.deps.treeTier(topicId);
+		const topicB64 = bytesToB64url(topicId);
+		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
+		const signable = { topicId: topicB64, fromTier, toTier: fromTier + 1, effectiveAt: now, cohortEpoch: epochB64 };
+		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(promotionNoticeSigningPayload(signable));
+		state.promoted = true;
+		state.promotedAt = now;
+		state.lastEffectiveAt = now; // local effectiveAt — so our own echoed broadcast applies as a no-op
+		return {
+			v: 1,
+			topicId: topicB64,
+			fromTier,
+			toTier: fromTier + 1,
+			effectiveAt: now,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+			cohortEpoch: epochB64,
+		};
+	}
+
+	// --- demotion ---
+
+	private demotionTriggered(topicId: Uint8Array, state: PromotionState, now: number): boolean {
+		// The root (tree tier 0) has no parent to hand off to — it never demotes.
+		if (this.deps.treeTier(topicId) <= 0) {
+			return false;
+		}
+		// Sticky: a freshly-promoted cohort holds promoted mode through transient drops.
+		if (state.promoted && state.promotedAt !== undefined && now - state.promotedAt < this.tPromoteStickyMs) {
+			return false;
+		}
+		// Never collapse a cohort that still has live children beneath it.
+		if (this.deps.childCohortCount(topicId) > 0) {
+			return false;
+		}
+		if (this.deps.store.directParticipants(topicId) > this.capDemote) {
+			return false;
+		}
+		if (state.lowLoadSince === undefined) {
+			return false;
+		}
+		return now - state.lowLoadSince >= this.tDemoteMs;
+	}
+
+	private async demote(topicId: Uint8Array, state: PromotionState, now: number): Promise<DemotionNoticeV1> {
+		const tier = this.deps.treeTier(topicId);
+		const topicB64 = bytesToB64url(topicId);
+		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
+		const parentB64 = bytesToB64url(this.deps.parentCoord(topicId));
+		const signable = { topicId: topicB64, tier, parentCohortCoord: parentB64, effectiveAt: now, cohortEpoch: epochB64 };
+		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(demotionNoticeSigningPayload(signable));
+		// Release forwarder state: a demoted cohort leaves promoted mode and resets its clocks so a
+		// later re-growth re-evaluates cleanly.
+		state.promoted = false;
+		state.promotedAt = undefined;
+		state.lowLoadSince = undefined;
+		state.lastEffectiveAt = now; // local effectiveAt — so our own echoed broadcast applies as a no-op
+		return {
+			v: 1,
+			topicId: topicB64,
+			tier,
+			parentCohortCoord: parentB64,
+			effectiveAt: now,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+			cohortEpoch: epochB64,
+		};
+	}
+
+	// --- bookkeeping ---
+
+	private stateFor(topicId: Uint8Array): PromotionState {
+		const key = bytesKey(topicId);
+		let state = this.states.get(key);
+		if (state === undefined) {
+			state = { promoted: false, samples: [] };
+			this.states.set(key, state);
+		}
+		return state;
+	}
+
+	private pushGrowthSample(state: PromotionState, count: number, now: number): void {
+		state.samples.push({ t: now, count });
+		const cutoff = now - this.growthWindowMs;
+		while (state.samples.length > 1 && state.samples[0]!.t < cutoff) {
+			state.samples.shift();
+		}
+	}
+
+	private refreshLowLoadClock(state: PromotionState, count: number, now: number): void {
+		if (count <= this.capDemote) {
+			state.lowLoadSince ??= now;
+		} else {
+			state.lowLoadSince = undefined;
+		}
+	}
+}
+
+/** Build a {@link PromotionLifecycle} over the injected store, barometer resolver, and signer. */
+export function createPromotionLifecycle(deps: PromotionDeps): PromotionLifecycle {
+	return new CohortPromotionLifecycle(deps);
+}

package/src/cohort-topic/registration/bytes.ts

@@ -0,0 +1,37 @@
+/**
+ * Cohort-topic substrate — byte-array helpers shared by the registration store, sharding, and
+ * handoff. Peer ids and topic ids are raw {@link Uint8Array}; these give them stable string map
+ * keys, value equality, and the ascending order the sharding hash relies on.
+ */
+
+import { compare as compareU8 } from "uint8arrays/compare";
+import { equals as equalsU8 } from "uint8arrays/equals";
+import { bytesToB64url } from "../wire/codec.js";
+
+/** Stable, collision-free string map key for a byte array (base64url, the package's canonical form). */
+export function bytesKey(b: Uint8Array): string {
+	return bytesToB64url(b);
+}
+
+/** Composite key for a registration, `topicKey|participantKey`. */
+export function recordKey(topicId: Uint8Array, participantId: Uint8Array): string {
+	return `${bytesKey(topicId)}|${bytesKey(participantId)}`;
+}
+
+/** Value equality over byte arrays. */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+	return equalsU8(a, b);
+}
+
+/** Lexicographic byte order — the `sort(... by PeerId ascending)` of §Primary and backup sharding. */
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+	return compareU8(a, b);
+}
+
+/** Concatenate two byte arrays into a fresh buffer (the `participantId ‖ cohortEpoch` hash input). */
+export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+}

package/src/cohort-topic/registration/handoff.ts

@@ -0,0 +1,154 @@
+/**
+ * Cohort-topic substrate — membership-rotation primary handoff.
+ *
+ * Per `docs/cohort-topic.md` §Membership rotation and primary handoff. When membership changes the
+ * deterministic slot may move a registration's primary. Each member runs this state machine:
+ *
+ * 1. New membership stabilizes; all members compute the new `cohortEpoch`.
+ * 2. Members exchange a "primary inventory" listing the records they hold as primary ({@link start}).
+ * 3. For each record, the new computed primary either already holds it (no-op) or **pulls** it from
+ *    the previous holder ({@link onInventory} → `transport.pull`).
+ * 4. **Resolved (GROUNDING):** the previous primary keeps serving (**dual-serve**) until the new
+ *    primary acknowledges receipt ({@link onAck}) — closing the delivery gap.
+ * 5. Participants discover the new primary on their next ping/delivery (renewal module).
+ *
+ * The gossip *transport* for the inventory comes from a later ticket; it is injected here so the
+ * machine is unit-testable with a mock. The machine is purely cohort-local — FRET is unaware of it.
+ */
+
+import { bytesEqual, recordKey } from "./bytes.js";
+import type { SlotAssigner } from "./sharding.js";
+import type { RegistrationRecord, RegistrationStore } from "./types.js";
+
+/** Identifies one registration in a {@link PrimaryInventory} or pull/ack exchange. */
+export interface RecordRef {
+	topicId: Uint8Array;
+	participantId: Uint8Array;
+}
+
+/** A member's list of registrations it currently holds as primary, under the new `cohortEpoch`. */
+export interface PrimaryInventory {
+	/** The advertising member. */
+	from: Uint8Array;
+	/** The new cohort epoch this inventory was computed under. */
+	epoch: Uint8Array;
+	entries: readonly RecordRef[];
+}
+
+/** Transport the handoff drives; supplied by the cohort-gossip ticket, mocked in tests. */
+export interface HandoffTransport {
+	/** Broadcast this member's primary inventory to the cohort. */
+	sendInventory(inv: PrimaryInventory): void;
+	/** Pull a record this member is now primary for from its previous holder. */
+	pull(from: Uint8Array, ref: RecordRef): Promise<RegistrationRecord | undefined>;
+	/** Acknowledge receipt to the previous holder, ending its dual-serve for `ref`. */
+	ack(to: Uint8Array, ref: RecordRef): void;
+}
+
+export interface HandoffDeps {
+	store: RegistrationStore;
+	/** This member's own peer id. */
+	self: Uint8Array;
+	slots: SlotAssigner;
+	/** The new (post-rotation) cohort snapshot. */
+	cohort: () => { members: readonly Uint8Array[]; cohortEpoch: Uint8Array };
+	transport: HandoffTransport;
+}
+
+/** Per-member primary-handoff driver. One instance handles one rotation. */
+export interface MembershipHandoff {
+	/** Step 1+2: recompute under the new epoch, publish this member's inventory, mark hand-offs. */
+	start(): void;
+	/** Step 3: react to a peer's inventory — pull every record now assigned to this member, then ack. */
+	onInventory(inv: PrimaryInventory): Promise<void>;
+	/** Serve a pull from the new primary (this member is the previous holder); stays dual-serving. */
+	onPull(ref: RecordRef): RegistrationRecord | undefined;
+	/** New primary acked receipt: stop dual-serving `ref`. */
+	onAck(ref: RecordRef): void;
+	/** Whether this member should still answer renews for `(topicId, participantId)` right now. */
+	isServing(topicId: Uint8Array, participantId: Uint8Array): boolean;
+}
+
+class StoreMembershipHandoff implements MembershipHandoff {
+	/** Records this member held as primary but no longer is — kept serving until acked. */
+	private readonly dualServing = new Set<string>();
+	/** In-flight pulls, so a duplicate inventory does not pull twice. */
+	private readonly pulling = new Set<string>();
+
+	constructor(private readonly deps: HandoffDeps) {}
+
+	start(): void {
+		const { members, cohortEpoch } = this.deps.cohort();
+		const entries: RecordRef[] = [];
+		for (const rec of this.deps.store.listAll()) {
+			if (!bytesEqual(rec.primary, this.deps.self)) {
+				continue; // only records this member currently holds as primary
+			}
+			entries.push({ topicId: rec.topicId, participantId: rec.participantId });
+			const { primary } = this.deps.slots.assignSlots(rec.participantId, cohortEpoch, members);
+			if (!bytesEqual(primary, this.deps.self)) {
+				// Primary moved away from this member: keep serving until the new primary acks.
+				this.dualServing.add(recordKey(rec.topicId, rec.participantId));
+			}
+		}
+		this.deps.transport.sendInventory({ from: this.deps.self, epoch: cohortEpoch, entries });
+	}
+
+	async onInventory(inv: PrimaryInventory): Promise<void> {
+		if (bytesEqual(inv.from, this.deps.self)) {
+			return; // ignore our own inventory
+		}
+		const { members, cohortEpoch } = this.deps.cohort();
+		for (const ref of inv.entries) {
+			await this.maybePull(inv.from, ref, members, cohortEpoch);
+		}
+	}
+
+	private async maybePull(from: Uint8Array, ref: RecordRef, members: readonly Uint8Array[], cohortEpoch: Uint8Array): Promise<void> {
+		const { primary, backups } = this.deps.slots.assignSlots(ref.participantId, cohortEpoch, members);
+		if (!bytesEqual(primary, this.deps.self)) {
+			return; // not assigned to this member now
+		}
+		if (this.deps.store.getByParticipant(ref.topicId, ref.participantId) !== undefined) {
+			return; // already hold it (no-op handoff)
+		}
+		const key = recordKey(ref.topicId, ref.participantId);
+		if (this.pulling.has(key)) {
+			return;
+		}
+		this.pulling.add(key);
+		try {
+			const rec = await this.deps.transport.pull(from, ref);
+			if (rec !== undefined) {
+				// Re-stamp the assignment so a later rotation's `start()` recognises this member as primary.
+				this.deps.store.put({ ...rec, primary, backups });
+				this.deps.transport.ack(from, ref); // ends dual-serve at the previous holder
+			}
+		} finally {
+			this.pulling.delete(key);
+		}
+	}
+
+	onPull(ref: RecordRef): RegistrationRecord | undefined {
+		// Previous holder serves the record; it remains in dualServing until the ack arrives.
+		return this.deps.store.getByParticipant(ref.topicId, ref.participantId);
+	}
+
+	onAck(ref: RecordRef): void {
+		this.dualServing.delete(recordKey(ref.topicId, ref.participantId));
+	}
+
+	isServing(topicId: Uint8Array, participantId: Uint8Array): boolean {
+		const { members, cohortEpoch } = this.deps.cohort();
+		const { primary } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+		if (bytesEqual(primary, this.deps.self)) {
+			return true;
+		}
+		return this.dualServing.has(recordKey(topicId, participantId));
+	}
+}
+
+/** Build a {@link MembershipHandoff} for one rotation. */
+export function createMembershipHandoff(deps: HandoffDeps): MembershipHandoff {
+	return new StoreMembershipHandoff(deps);
+}

package/src/cohort-topic/registration/index.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./bytes.js";
+export * from "./store.js";
+export * from "./sharding.js";
+export * from "./renewal.js";
+export * from "./handoff.js";