@optimystic/db-core 0.21.0 → 0.24.0

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

@@ -1,2 +1,2 @@
-export * from "./payloads.js";
-export * from "./threshold.js";
+export * from "./payloads.js";
+export * from "./threshold.js";

package/src/cohort-topic/sig/payloads.ts

@@ -1,59 +1,59 @@
-/**
- * Cohort-topic substrate — canonical threshold-signature payloads.
- *
- * A threshold signature is only verifiable if signer and verifier agree on the exact bytes signed.
- * These builders produce that deterministic byte image for each threshold-signed message
- * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`, `ChildLinkV1`), covering exactly the
- * semantic fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
- *
- * Determinism comes from encoding an explicitly-ordered JSON array (array order is stable, unlike
- * object key order) as UTF-8. The publisher signs this image; the verifier recomputes and checks it.
- *
- * The notice images carry `cohortCoord` (the served coord the deciding cohort sits at) so the coord the
- * receiver routes by is bound into the signed bytes — rewriting it to hijack a sibling cohort breaks
- * verification. It is inserted **just before the trailing `cohortEpoch`**, deliberately keeping `cohortEpoch`
- * the LAST element: the `/sign` endorser (`handleSignRequest`) reads a notice's embedded epoch positionally
- * as `image[image.length - 1]`, so `cohortEpoch` must stay last. This is a hard, coordinated change to the
- * canonical signed bytes, acceptable pre-release (no deployed nodes speak this protocol, so there is no
- * version to negotiate).
- */
-
-import type { ChildLinkV1, DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
-
-const utf8 = new TextEncoder();
-
-/** Fields of a `MembershipCertV1` covered by its threshold signature (doc: cohortCoord, cohortEpoch, members, stabilizedAt). */
-export type MembershipCertSignable = Pick<MembershipCertV1, "cohortCoord" | "cohortEpoch" | "members" | "stabilizedAt">;
-
-/** Canonical signed byte image of a membership certificate. */
-export function membershipCertSigningPayload(cert: MembershipCertSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["MembershipCertV1", cert.cohortCoord, cert.cohortEpoch, cert.members, cert.stabilizedAt]));
-}
-
-/** Fields of a `PromotionNoticeV1` covered by its threshold signature. */
-export type PromotionSignable = Pick<PromotionNoticeV1, "topicId" | "fromTier" | "toTier" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
-
-/** Canonical signed byte image of a promotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
-export function promotionNoticeSigningPayload(n: PromotionSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
-}
-
-/** Fields of a `DemotionNoticeV1` covered by its threshold signature. */
-export type DemotionSignable = Pick<DemotionNoticeV1, "topicId" | "tier" | "parentCohortCoord" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
-
-/** Canonical signed byte image of a demotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
-export function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
-}
-
-/** Fields of a `ChildLinkV1` covered by the child cohort's threshold signature. */
-export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch">;
-
-/**
- * Canonical signed byte image of a child-link frame. `cohortEpoch` stays **last** so the `/sign` endorser
- * (`handleSignRequest`) reads the embedded epoch positionally as `image[image.length - 1]`, exactly as it
- * does for a promotion / demotion notice.
- */
-export function childLinkSigningPayload(n: ChildLinkSignable): Uint8Array {
-	return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, n.cohortEpoch]));
-}
+/**
+ * Cohort-topic substrate — canonical threshold-signature payloads.
+ *
+ * A threshold signature is only verifiable if signer and verifier agree on the exact bytes signed.
+ * These builders produce that deterministic byte image for each threshold-signed message
+ * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`, `ChildLinkV1`), covering exactly the
+ * semantic fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
+ *
+ * Determinism comes from encoding an explicitly-ordered JSON array (array order is stable, unlike
+ * object key order) as UTF-8. The publisher signs this image; the verifier recomputes and checks it.
+ *
+ * The notice images carry `cohortCoord` (the served coord the deciding cohort sits at) so the coord the
+ * receiver routes by is bound into the signed bytes — rewriting it to hijack a sibling cohort breaks
+ * verification. It is inserted **just before the trailing `cohortEpoch`**, deliberately keeping `cohortEpoch`
+ * the LAST element: the `/sign` endorser (`handleSignRequest`) reads a notice's embedded epoch positionally
+ * as `image[image.length - 1]`, so `cohortEpoch` must stay last. This is a hard, coordinated change to the
+ * canonical signed bytes, acceptable pre-release (no deployed nodes speak this protocol, so there is no
+ * version to negotiate).
+ */
+
+import type { ChildLinkV1, DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
+
+const utf8 = new TextEncoder();
+
+/** Fields of a `MembershipCertV1` covered by its threshold signature (doc: cohortCoord, cohortEpoch, members, stabilizedAt). */
+export type MembershipCertSignable = Pick<MembershipCertV1, "cohortCoord" | "cohortEpoch" | "members" | "stabilizedAt">;
+
+/** Canonical signed byte image of a membership certificate. */
+export function membershipCertSigningPayload(cert: MembershipCertSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["MembershipCertV1", cert.cohortCoord, cert.cohortEpoch, cert.members, cert.stabilizedAt]));
+}
+
+/** Fields of a `PromotionNoticeV1` covered by its threshold signature. */
+export type PromotionSignable = Pick<PromotionNoticeV1, "topicId" | "fromTier" | "toTier" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
+
+/** Canonical signed byte image of a promotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
+export function promotionNoticeSigningPayload(n: PromotionSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
+}
+
+/** Fields of a `DemotionNoticeV1` covered by its threshold signature. */
+export type DemotionSignable = Pick<DemotionNoticeV1, "topicId" | "tier" | "parentCohortCoord" | "effectiveAt" | "cohortEpoch" | "cohortCoord">;
+
+/** Canonical signed byte image of a demotion notice. `cohortEpoch` stays last (the `/sign` endorser reads it positionally). */
+export function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortCoord, n.cohortEpoch]));
+}
+
+/** Fields of a `ChildLinkV1` covered by the child cohort's threshold signature. */
+export type ChildLinkSignable = Pick<ChildLinkV1, "topicId" | "childCohortCoord" | "childParticipantCoord" | "childTier" | "tier" | "effectiveAt" | "cohortEpoch">;
+
+/**
+ * Canonical signed byte image of a child-link frame. `cohortEpoch` stays **last** so the `/sign` endorser
+ * (`handleSignRequest`) reads the embedded epoch positionally as `image[image.length - 1]`, exactly as it
+ * does for a promotion / demotion notice.
+ */
+export function childLinkSigningPayload(n: ChildLinkSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["ChildLinkV1", n.topicId, n.childCohortCoord, n.childParticipantCoord, n.childTier, n.tier, n.effectiveAt, n.cohortEpoch]));
+}

package/src/cohort-topic/sig/threshold.ts

@@ -1,64 +1,64 @@
-/**
- * Cohort-topic substrate — `k − x` threshold signing and verification.
- *
- * Per `docs/cohort-topic.md` §FRET integration (L659) and §Membership snapshots: the cohort
- * threshold-signs `PromotionNoticeV1` / `DemotionNoticeV1` / `MembershipCertV1` with `minSigs`
- * (= `k − x`, default 14) signers. This module is db-core logic over the {@link ICohortThresholdCrypto}
- * port; db-p2p binds the port to FRET's `minSigs` cohort-signature assembly — db-core never imports
- * FRET, and the underlying scheme is reused unchanged.
- *
- * {@link CohortSigner.verifyThreshold} layers the membership check db-core owns on top of the raw
- * crypto: the `signers` must be a distinct `≥ minSigs` subset of the certificate's `members`, *and*
- * the signature must verify against the payload. Either failure → not verified.
- */
-
-import type { ICohortThresholdCrypto } from "../ports.js";
-import { bytesToB64url } from "../wire/codec.js";
-import type { MembershipCertV1 } from "../wire/types.js";
-
-/** Default cohort-signature threshold, `k − x` (see §Configuration). */
-export const DEFAULT_MIN_SIGS = 14;
-
-/** Threshold signer/verifier over the injected cohort crypto. Peer ids are raw bytes. */
-export interface CohortSigner {
-	/** Assemble a cohort threshold signature over `payload` (collects `minSigs` signers). */
-	thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
-	/**
-	 * Verify a threshold-signed message: `signers` are a distinct `≥ minSigs` subset of
-	 * `cert.members` and `sig` is a valid cohort signature over `payload`.
-	 */
-	verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean;
-}
-
-class CryptoCohortSigner implements CohortSigner {
-	constructor(private readonly crypto: ICohortThresholdCrypto, private readonly minSigs: number) {}
-
-	thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
-		return this.crypto.assemble(payload, this.minSigs);
-	}
-
-	verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean {
-		if (signers.length < minSigs) {
-			return false;
-		}
-		// Members are base64url on the wire; compare signers in that same canonical form.
-		const memberSet = new Set(cert.members);
-		const seen = new Set<string>();
-		for (const signer of signers) {
-			const key = bytesToB64url(signer);
-			if (seen.has(key)) {
-				return false; // a duplicated signer cannot pad the count toward minSigs
-			}
-			seen.add(key);
-			if (!memberSet.has(key)) {
-				return false; // signer is not a member of the attested cohort
-			}
-		}
-		return this.crypto.verify(payload, sig, signers);
-	}
-}
-
-/** Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. */
-export function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs: number = DEFAULT_MIN_SIGS): CohortSigner {
-	return new CryptoCohortSigner(crypto, minSigs);
-}
+/**
+ * Cohort-topic substrate — `k − x` threshold signing and verification.
+ *
+ * Per `docs/cohort-topic.md` §FRET integration (L659) and §Membership snapshots: the cohort
+ * threshold-signs `PromotionNoticeV1` / `DemotionNoticeV1` / `MembershipCertV1` with `minSigs`
+ * (= `k − x`, default 14) signers. This module is db-core logic over the {@link ICohortThresholdCrypto}
+ * port; db-p2p binds the port to FRET's `minSigs` cohort-signature assembly — db-core never imports
+ * FRET, and the underlying scheme is reused unchanged.
+ *
+ * {@link CohortSigner.verifyThreshold} layers the membership check db-core owns on top of the raw
+ * crypto: the `signers` must be a distinct `≥ minSigs` subset of the certificate's `members`, *and*
+ * the signature must verify against the payload. Either failure → not verified.
+ */
+
+import type { ICohortThresholdCrypto } from "../ports.js";
+import { bytesToB64url } from "../wire/codec.js";
+import type { MembershipCertV1 } from "../wire/types.js";
+
+/** Default cohort-signature threshold, `k − x` (see §Configuration). */
+export const DEFAULT_MIN_SIGS = 14;
+
+/** Threshold signer/verifier over the injected cohort crypto. Peer ids are raw bytes. */
+export interface CohortSigner {
+	/** Assemble a cohort threshold signature over `payload` (collects `minSigs` signers). */
+	thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
+	/**
+	 * Verify a threshold-signed message: `signers` are a distinct `≥ minSigs` subset of
+	 * `cert.members` and `sig` is a valid cohort signature over `payload`.
+	 */
+	verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean;
+}
+
+class CryptoCohortSigner implements CohortSigner {
+	constructor(private readonly crypto: ICohortThresholdCrypto, private readonly minSigs: number) {}
+
+	thresholdSign(payload: Uint8Array): Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }> {
+		return this.crypto.assemble(payload, this.minSigs);
+	}
+
+	verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean {
+		if (signers.length < minSigs) {
+			return false;
+		}
+		// Members are base64url on the wire; compare signers in that same canonical form.
+		const memberSet = new Set(cert.members);
+		const seen = new Set<string>();
+		for (const signer of signers) {
+			const key = bytesToB64url(signer);
+			if (seen.has(key)) {
+				return false; // a duplicated signer cannot pad the count toward minSigs
+			}
+			seen.add(key);
+			if (!memberSet.has(key)) {
+				return false; // signer is not a member of the attested cohort
+			}
+		}
+		return this.crypto.verify(payload, sig, signers);
+	}
+}
+
+/** Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. */
+export function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs: number = DEFAULT_MIN_SIGS): CohortSigner {
+	return new CryptoCohortSigner(crypto, minSigs);
+}

package/src/cohort-topic/tiers.ts

@@ -1,74 +1,74 @@
-/**
- * Cohort-topic substrate — tier ladder (T0–T3) and node profiles (Edge / Core).
- *
- * Transcribed from `docs/cohort-topic.md` §Tier ladder. This module encodes only the **static**
- * tier classes, the Edge/Core profiles, and the per-node override surface. The decline-policy
- * *behavior* (T0 never declined while serving, T3 declined freely) and the Edge runtime overrides
- * (`ttl = 60s`, `ping_interval = 20s`, sticky-cached backups) are willingness/TTL concerns owned by
- * later tickets — only the profile *flags* (which tiers a node is willing to forward) live here.
- */
-
-/**
- * System-wide capacity tier, in priority order (T0 essential … T3 luxury).
- *
- * Modeled as a frozen const-object + value-union type rather than a TS `enum`: db-core's test
- * runner uses Node's native type-stripping, which rejects `enum` (non-erasable syntax). The object
- * carries the named members (`Tier.T0`), the type alias carries the value union (`0 | 1 | 2 | 3`).
- *
- * - **T0 — essential**: transaction commit, block production, threshold-sig contribution.
- * - **T1 — correctness-supporting**: chain serving, replay-window storage, partition heal.
- * - **T2 — functional**: matchmaking/voting directories, capability discovery, capacity gossip.
- * - **T3 — luxury**: reactivity push forwarding, anticipatory warm-up, optional delta payloads.
- */
-export const Tier = { T0: 0, T1: 1, T2: 2, T3: 3 } as const;
-export type Tier = (typeof Tier)[keyof typeof Tier];
-
-/** All four tiers, ascending — useful for iteration and override validation. */
-export const ALL_TIERS: readonly Tier[] = [Tier.T0, Tier.T1, Tier.T2, Tier.T3];
-
-/**
- * A node's static tier classification. `willingTiers` is the set of tiers this node will take on
- * *forwarder* roles for; cohort assembly under FRET is tier-blind, so this is the per-node gate the
- * willingness check consults. Edge: `{T0, T1}`; Core: `{T0, T1, T2, T3}` (operator-narrowable).
- */
-export interface NodeProfile {
-	readonly kind: "edge" | "core";
-	readonly willingTiers: ReadonlySet<Tier>;
-}
-
-/** Per-node operator override surface. Currently the willing-tier set; widened by later tickets. */
-export interface NodeProfileOverrides {
-	/**
-	 * Restrict the willing-tier set. Tiers outside the profile's base set are ignored (Edge can never
-	 * be widened to T2/T3 via override — that is a hardware/policy class, not a knob).
-	 */
-	willingTiers?: Iterable<Tier>;
-}
-
-const EDGE_BASE_TIERS: readonly Tier[] = [Tier.T0, Tier.T1];
-const CORE_BASE_TIERS: readonly Tier[] = ALL_TIERS;
-
-/** Intersect a requested override set with the profile's base tiers (override can only narrow). */
-function resolveWillingTiers(base: readonly Tier[], overrides?: NodeProfileOverrides): ReadonlySet<Tier> {
-	if (!overrides?.willingTiers) {
-		return new Set(base);
-	}
-	const requested = new Set(overrides.willingTiers);
-	return new Set(base.filter((t) => requested.has(t)));
-}
-
-/**
- * Edge profile (mobile / browser / IoT): forwards T0 + T1 only. T2/T3 willingness is permanently
- * off and an operator override cannot turn it on. An override may further narrow (e.g. to `{T0}`).
- */
-export function edgeProfile(overrides?: NodeProfileOverrides): NodeProfile {
-	return { kind: "edge", willingTiers: resolveWillingTiers(EDGE_BASE_TIERS, overrides) };
-}
-
-/**
- * Core profile (servers / fixed infrastructure): forwards T0–T3 by default. An operator override may
- * restrict it to a subset (e.g. `{T0, T1, T2}` to shed reactivity-push duty).
- */
-export function coreProfile(overrides?: NodeProfileOverrides): NodeProfile {
-	return { kind: "core", willingTiers: resolveWillingTiers(CORE_BASE_TIERS, overrides) };
-}
+/**
+ * Cohort-topic substrate — tier ladder (T0–T3) and node profiles (Edge / Core).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tier ladder. This module encodes only the **static**
+ * tier classes, the Edge/Core profiles, and the per-node override surface. The decline-policy
+ * *behavior* (T0 never declined while serving, T3 declined freely) and the Edge runtime overrides
+ * (`ttl = 60s`, `ping_interval = 20s`, sticky-cached backups) are willingness/TTL concerns owned by
+ * later tickets — only the profile *flags* (which tiers a node is willing to forward) live here.
+ */
+
+/**
+ * System-wide capacity tier, in priority order (T0 essential … T3 luxury).
+ *
+ * Modeled as a frozen const-object + value-union type rather than a TS `enum`: db-core's test
+ * runner uses Node's native type-stripping, which rejects `enum` (non-erasable syntax). The object
+ * carries the named members (`Tier.T0`), the type alias carries the value union (`0 | 1 | 2 | 3`).
+ *
+ * - **T0 — essential**: transaction commit, block production, threshold-sig contribution.
+ * - **T1 — correctness-supporting**: chain serving, replay-window storage, partition heal.
+ * - **T2 — functional**: matchmaking/voting directories, capability discovery, capacity gossip.
+ * - **T3 — luxury**: reactivity push forwarding, anticipatory warm-up, optional delta payloads.
+ */
+export const Tier = { T0: 0, T1: 1, T2: 2, T3: 3 } as const;
+export type Tier = (typeof Tier)[keyof typeof Tier];
+
+/** All four tiers, ascending — useful for iteration and override validation. */
+export const ALL_TIERS: readonly Tier[] = [Tier.T0, Tier.T1, Tier.T2, Tier.T3];
+
+/**
+ * A node's static tier classification. `willingTiers` is the set of tiers this node will take on
+ * *forwarder* roles for; cohort assembly under FRET is tier-blind, so this is the per-node gate the
+ * willingness check consults. Edge: `{T0, T1}`; Core: `{T0, T1, T2, T3}` (operator-narrowable).
+ */
+export interface NodeProfile {
+	readonly kind: "edge" | "core";
+	readonly willingTiers: ReadonlySet<Tier>;
+}
+
+/** Per-node operator override surface. Currently the willing-tier set; widened by later tickets. */
+export interface NodeProfileOverrides {
+	/**
+	 * Restrict the willing-tier set. Tiers outside the profile's base set are ignored (Edge can never
+	 * be widened to T2/T3 via override — that is a hardware/policy class, not a knob).
+	 */
+	willingTiers?: Iterable<Tier>;
+}
+
+const EDGE_BASE_TIERS: readonly Tier[] = [Tier.T0, Tier.T1];
+const CORE_BASE_TIERS: readonly Tier[] = ALL_TIERS;
+
+/** Intersect a requested override set with the profile's base tiers (override can only narrow). */
+function resolveWillingTiers(base: readonly Tier[], overrides?: NodeProfileOverrides): ReadonlySet<Tier> {
+	if (!overrides?.willingTiers) {
+		return new Set(base);
+	}
+	const requested = new Set(overrides.willingTiers);
+	return new Set(base.filter((t) => requested.has(t)));
+}
+
+/**
+ * Edge profile (mobile / browser / IoT): forwards T0 + T1 only. T2/T3 willingness is permanently
+ * off and an operator override cannot turn it on. An override may further narrow (e.g. to `{T0}`).
+ */
+export function edgeProfile(overrides?: NodeProfileOverrides): NodeProfile {
+	return { kind: "edge", willingTiers: resolveWillingTiers(EDGE_BASE_TIERS, overrides) };
+}
+
+/**
+ * Core profile (servers / fixed infrastructure): forwards T0–T3 by default. An operator override may
+ * restrict it to a subset (e.g. `{T0, T1, T2}` to shed reactivity-push duty).
+ */
+export function coreProfile(overrides?: NodeProfileOverrides): NodeProfile {
+	return { kind: "core", willingTiers: resolveWillingTiers(CORE_BASE_TIERS, overrides) };
+}