@optimystic/db-core 0.14.1 → 0.16.2

package/src/cohort-topic/wire/primitives.ts

@@ -0,0 +1,188 @@
+/**
+ * Cohort-topic wire substrate — shared structural-validation primitives.
+ *
+ * The generic per-field checks every wire codec across the substrate (cohort-topic, matchmaking,
+ * reactivity) uses to narrow an already-parsed `unknown` (the output of `JSON.parse` on a decoded
+ * frame) into a validated V1 shape. Each helper throws {@link CohortWireError} on a structural defect:
+ * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode as
+ * base64url, or an out-of-range numeric.
+ *
+ * These are the *only* generic primitives — domain-specific narrowing (the `validate*V1` functions, the
+ * cohort-topic `tier` / `treeTier` semantics, matchmaking utf8 coders, reactivity notification shapes)
+ * lives in the modules that own those message shapes. Keeping the primitives in one place means a
+ * hardening tweak to a check (e.g. the fixed-length byte-width guard in {@link b64urlFixedLen}) lands
+ * once and every consumer inherits it.
+ */
+
+import { b64urlToBytes } from "./codec.js";
+
+/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
+export class CohortWireError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CohortWireError";
+	}
+}
+
+/** Throw a {@link CohortWireError} with `message`. */
+export function failWire(message: string): never {
+	throw new CohortWireError(message);
+}
+
+/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
+export function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
+	if (value !== undefined) {
+		obj[key] = value;
+	}
+}
+
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		failWire(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+/** Require `obj.v === 1`. */
+export function requireV1(obj: Record<string, unknown>, what: string): void {
+	if (obj["v"] !== 1) {
+		failWire(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+	}
+}
+
+/** Require `obj[key]` to be a string; returns it. */
+export function reqString(obj: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a string, `undefined` when absent; throw on any other type. */
+export function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a finite number; returns it. */
+export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a finite number, `undefined` when absent; throw on any other type. */
+export function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a boolean; returns it. */
+export function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
+	const value = obj[key];
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a boolean, `undefined` when absent; throw on any other type. */
+export function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean when present`);
+	}
+	return value;
+}
+
+/**
+ * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
+ * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
+ * than a pre-extracted value — this composes with the other `req*` helpers.
+ */
+export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
+	const value = reqFiniteNumber(obj, key, what);
+	if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
+		const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
+		failWire(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be an array of strings; returns it. */
+export function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
+	const value = obj[key];
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		failWire(`${what}: field "${key}" must be an array of strings`);
+	}
+	return value as string[];
+}
+
+/** Return `obj[key]` when it is an array of strings, `undefined` when absent; throw on any other type. */
+export function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
+	if (obj[key] === undefined) {
+		return undefined;
+	}
+	return reqStringArray(obj, key, what);
+}
+
+/** Require `obj[key]` to be one of `allowed`; returns it narrowed to the enum type. */
+export function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
+	const value = obj[key];
+	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+		failWire(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
+	}
+	return value as T;
+}
+
+/**
+ * Assert a base64url string decodes cleanly; returns it unchanged. Used for variable-width fields —
+ * peer ids (multihash-encoded, not 32 raw bytes), signatures, and opaque application payloads.
+ *
+ * NOTE: no max-length bound here. A hostile peer can still bloat one of these variable-width fields
+ * (e.g. `participantCoord`, a signature) into a large map key in the store / rate limiter / replay
+ * guard. Their widths aren't pinned by the spec, so a ceiling would be a chosen policy value rather
+ * than a decode of the format. If a bloated one is ever seen as a map key in practice, add a
+ * `b64urlMaxLen` ceiling here. (Fixed-width hash-derived fields go through `b64urlFixedLen` instead.)
+ */
+export function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
+export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
+	let bytes: Uint8Array;
+	try {
+		bytes = b64urlToBytes(value);
+	} catch {
+		return failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	if (bytes.length !== len) {
+		failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
+	}
+	return value;
+}

package/src/cohort-topic/wire/types.ts

@@ -28,6 +28,20 @@ export interface RegisterV1 {
 	ttl: number;
 	/** True on a root cold-start request. */
 	bootstrap?: boolean;
+	/**
+	 * Follow-on cold-start request: set on the **dedicated re-issue** the participant sends after a
+	 * `Promoted` redirect target answered {@link RegisterResult} `no_state` (the redirect points at a
+	 * tier-`(d+1)` child cohort that does not exist yet). It tells that cold child "I am here because
+	 * your parent redirected me — instantiate", which drives the cold-start gate
+	 * (`shouldInstantiate({ followOn, … })`) exactly as `bootstrap` drives it at the root. Constraints:
+	 * always `treeTier >= 1` (a follow-on is a deeper-than-root growth point, never the root); mutually
+	 * exclusive with {@link bootstrap} and {@link probe} (the walk sets at most one). Because a wire flag is
+	 * participant-forgeable, safety does NOT come from its provenance: a `followOn: true` register is gated
+	 * by the **same** `bootstrapEvidence` policy a `bootstrap: true` cold-root register passes (§Anti-DoS),
+	 * so it carries the identical proof in {@link bootstrapEvidence} and pays the identical anti-abuse cost.
+	 * Covered by `signature` (appended to `registerSigningPayload`) so a MITM cannot strip or flip it.
+	 */
+	followOn?: boolean;
 	/**
 	 * Read-only lookup probe: classify + return the cohort snapshot without admitting (no record, no
 	 * arrival, no promotion trigger, no topic-budget touch, and **never** a cold-start instantiation /
@@ -42,9 +56,11 @@ export interface RegisterV1 {
 	appPayload?: string;
 	/**
 	 * Cold-start bootstrap-evidence envelope, base64url (a `BootstrapEvidenceEnvelopeV1` — see
-	 * `../antidos/bootstrap-evidence-envelope.js`). Present only on a `bootstrap: true` root register;
-	 * carries the tier-dependent proof a cold root demands (proof-of-work / reputation endorsement /
-	 * signed parent reference — §Anti-DoS). This is a **dedicated** field, NOT `appPayload`: the cohort
+	 * `../antidos/bootstrap-evidence-envelope.js`). Present on a `bootstrap: true` root register **or** a
+	 * `followOn: true` deeper-tier re-issue — both are cold-start requests gated by the identical evidence
+	 * policy (§Anti-DoS), so both carry this proof; carries the tier-dependent proof a cold cohort demands
+	 * (proof-of-work / reputation endorsement / signed parent reference — §Anti-DoS). This is a
+	 * **dedicated** field, NOT `appPayload`: the cohort
 	 * copies `appPayload` verbatim into the registration's `appState` and replicates it cluster-wide,
 	 * whereas the bootstrap evidence is parsed-and-checked by the substrate, **covered by `signature`**
 	 * (so a MITM cannot strip or swap it), and never stored as appState. Empty string is treated as
@@ -143,6 +159,53 @@ export interface RenewReplyV1 {
 	cohortEpoch?: string;
 }
 
+/**
+ * Child cohort → parent cohort link: "I am the tier-`d` cohort at {@link childCohortCoord}; record me as
+ * your child." A freshly cold-started deeper forwarder sends this to its tier-`(d − 1)` parent (routed the
+ * same way a participant register is, over `routeAndAct` to the parent coord) so the parent authenticates,
+ * records the child, and acks — replacing the interim plain participant-register the child used to send.
+ */
+export interface ChildLinkV1 {
+	v: 1;
+	/** Topic id, 32 bytes, base64url. */
+	topicId: string;
+	/**
+	 * The child cohort's served coord `coord_d(childParticipantCoord, topicId)`, 32 bytes base64url — the
+	 * coord the parent verifies the threshold signature against (it looks up the child cohort's
+	 * {@link MembershipCertV1} at this coord).
+	 */
+	childCohortCoord: string;
+	/**
+	 * A representative participant coord in the child's prefix-shard (the seed the child engine was
+	 * instantiated at). Lets the parent *deterministically bind the parent-child relationship*: it recomputes
+	 * `coord_childTier(childParticipantCoord, topicId) == childCohortCoord` AND
+	 * `coord_(childTier-1)(childParticipantCoord, topicId) == this parent's served coord`. Any participant
+	 * sharing the child's `d·log₂F`-bit prefix yields the same pair, so it is a representative, not an
+	 * identity. 32 bytes base64url.
+	 */
+	childParticipantCoord: string;
+	/** Child tree tier `d` (always ≥ 1 — the root has no parent to link to). Parent serves `d − 1`. */
+	childTier: number;
+	/** Op capacity tier T0..T3 (stamped so a real parent validates the frame's tier). */
+	tier: number;
+	/** Unix ms; the parent's per-child freshness/ordering key (strictly-newer wins). */
+	effectiveAt: number;
+	/** Child cohort threshold signature over `childLinkSigningPayload`, base64url. Empty in the key-less interim. */
+	thresholdSig: string;
+	/** Signing members' PeerIds, `>= minSigs`, base64url. Empty in the key-less interim. */
+	signers: string[];
+	/** Child cohort epoch, 32 bytes base64url (the epoch the threshold sig was collected under). */
+	cohortEpoch: string;
+}
+
+/** Parent → child ack. `linked` flips the child `awaiting_parent → serving`; `rejected` keeps it awaiting. */
+export interface ChildLinkReplyV1 {
+	v: 1;
+	result: "linked" | "rejected";
+	/** Human-readable, optional. */
+	reason?: string;
+}
+
 /** Threshold-signed promotion notice. */
 export interface PromotionNoticeV1 {
 	v: 1;
@@ -150,6 +213,15 @@ export interface PromotionNoticeV1 {
 	fromTier: number;
 	/** Typically `fromTier + 1`. */
 	toTier: number;
+	/**
+	 * The served coord `coord_d(participantCoord, topicId)` the deciding cohort sits at, 32 bytes, base64url
+	 * — the same value as that cohort's {@link MembershipCertV1.cohortCoord}, which the threshold signature
+	 * verifies against. The receiver routes the notice to the local engine for exactly this coord rather than
+	 * scanning for the first engine matching `(topic, tier)`, so a node serving several sibling cohorts for
+	 * one `(topic, tier)` (possible at `d ≥ 1`, where each cohort has its own served coord) applies the notice
+	 * to the cohort that actually produced it. Covered by the threshold signature — rewriting it breaks verification.
+	 */
+	cohortCoord: string;
 	/** Unix ms. */
 	effectiveAt: number;
 	/** Cohort threshold signature, base64url. */
@@ -166,6 +238,13 @@ export interface DemotionNoticeV1 {
 	tier: number;
 	/** 32 bytes, base64url. */
 	parentCohortCoord: string;
+	/**
+	 * The served coord `coord_d(participantCoord, topicId)` the deciding cohort sits at, 32 bytes, base64url —
+	 * the same served-coord concept as {@link PromotionNoticeV1.cohortCoord}. Distinct from
+	 * {@link parentCohortCoord} (the tier-`(d − 1)` parent this demotion hands off to): `cohortCoord` names the
+	 * *demoting* cohort and is what the receiver routes + verifies by. Covered by the threshold signature.
+	 */
+	cohortCoord: string;
 	effectiveAt: number;
 	thresholdSig: string;
 	signers: string[];
@@ -203,6 +282,33 @@ export interface GossipRecordRefV1 {
 	topicId: string;
 	/** Participant peer id, base64url. */
 	participantId: string;
+	/**
+	 * Unix ms of the evicted record's most-recent ping (mirrors {@link GossipRecordV1.lastPing}). The
+	 * receiver's freshness guard for the delete: a held record newer than this stamp is a re-registration
+	 * that arrived after the eviction was produced, so the stale eviction is ignored rather than deleting
+	 * the fresh record. Required — every real eviction has this on hand from the held record.
+	 */
+	lastPing: number;
+}
+
+/**
+ * A child-cohort link/unlink advertised in cohort gossip, for cross-member convergence of the child set.
+ *
+ * FRET routes a {@link ChildLinkV1} to a **single** parent member, so only that member's child registry
+ * records the child; siblings would read `childCohortCount == 0`. Gossiping the child **set** (a converged
+ * union) closes that gap: a `childLinks` ref replicates a recorded child to every parent member, and a
+ * `childUnlinks` ref replicates a released (demoted) child. Merge is **last-writer-wins by
+ * {@link effectiveAt}** per `(topicId, childCohortCoord)` — a link and a later unlink converge regardless of
+ * arrival order, and re-delivery is idempotent. The child set is keyed by child coord, not the parent's
+ * epoch, so a parent membership rotation never drops it.
+ */
+export interface ChildLinkRefV1 {
+	/** Topic id, 32 bytes, base64url. */
+	topicId: string;
+	/** The child cohort's served coord, 32 bytes, base64url. */
+	childCohortCoord: string;
+	/** Unix ms — the link/unlink effectiveAt; last-writer-wins per `(topicId, childCohortCoord)`. */
+	effectiveAt: number;
 }
 
 /** Intra-cohort gossip: willingness vector, load barometer, exact per-topic summaries, record deltas. */
@@ -217,6 +323,14 @@ export interface CohortGossipV1 {
 	 */
 	coord: string;
 	cohortEpoch: string;
+	/**
+	 * The tree tier `d` the originating cohort sits at (the coord encodes the tier-shard, but a coord is a
+	 * hash and cannot be inverted to recover `d`). Carried so a cold sibling that instantiates its engine
+	 * off a co-member's frame (§Cold-start instantiation) adopts the right tier. Always well-defined: the
+	 * only members that originate a frame already know their `treeTier`, and every member of a coord shares
+	 * one `treeTier` by construction. Covered by {@link signature} so it cannot be spoofed.
+	 */
+	treeTier: number;
 	/** 4 bits T0..T3, hex. */
 	willingnessBits: string;
 	/** 4 entries, 0..7 per tier. */
@@ -232,6 +346,19 @@ export interface CohortGossipV1 {
 	records?: GossipRecordV1[];
 	/** Registrations this member evicted (stale), so all members converge on the active set. */
 	evicted?: GossipRecordRefV1[];
+	/**
+	 * Child cohorts this member freshly recorded (links), replicated so every parent member converges on the
+	 * same child set. Absent when this gossip carries no child-link changes. Merge is last-writer-wins by
+	 * {@link ChildLinkRefV1.effectiveAt} per `(topicId, childCohortCoord)`; a link sets the child linked.
+	 */
+	childLinks?: ChildLinkRefV1[];
+	/**
+	 * Child cohorts this member released (a demoted child unrecorded), replicated so every parent member drops
+	 * it and can shrink in turn. Absent when this gossip carries no child-unlink changes. Same last-writer-wins
+	 * merge as {@link childLinks}; an unlink sets the child unlinked. A link@t1 then unlink@t2 (t2 > t1)
+	 * converges to unlinked regardless of arrival order.
+	 */
+	childUnlinks?: ChildLinkRefV1[];
 	timestamp: number;
 	signature: string;
 }
@@ -257,8 +384,11 @@ export interface CohortTopicSummary {
  * - `rotation` — an epoch hand-off: the endorser attests it was a member of the cohort at the **prior**
  *   epoch carried as `cohortEpoch` (the predecessor cohort threshold-signs the successor cert's payload),
  *   so the gate checks *prior*-epoch membership rather than current. See `cohort-topic-trust-anchor-rotation-production`.
+ * - `childlink` — a child cohort signs a {@link ChildLinkV1} over its **own** served coord at its current
+ *   epoch (identical endorsement shape to `promotion`/`demotion`: share the current cohort + epoch around
+ *   `coord`); the parent verifies it against the child cohort's cert before recording the child.
  */
-export type SignKind = "membership" | "promotion" | "demotion" | "rotation";
+export type SignKind = "membership" | "promotion" | "demotion" | "rotation" | "childlink";
 
 /**
  * Intra-cohort sign request (`/optimystic/cohort-topic/1.0.0/sign`). A member assembling a `k − x`
@@ -334,6 +464,8 @@ export type CohortMessageV1 =
 	| RegisterReplyV1
 	| RenewV1
 	| RenewReplyV1
+	| ChildLinkV1
+	| ChildLinkReplyV1
 	| PromotionNoticeV1
 	| DemotionNoticeV1
 	| CohortGossipV1