@optimystic/db-core 0.14.1 → 0.16.3

package/src/matchmaking/wire.ts

@@ -29,7 +29,19 @@ import {
 	encodeCohortMessage,
 	DEFAULT_MAX_MESSAGE_BYTES,
 } from "../cohort-topic/wire/codec.js";
-import { CohortWireError } from "../cohort-topic/wire/validate.js";
+import {
+	asObject,
+	b64urlField,
+	failWire as fail,
+	optBool,
+	optFiniteNumber,
+	reqBool,
+	reqFiniteNumber,
+	reqIntInRange,
+	reqString,
+	reqStringArray,
+	requireV1,
+} from "../cohort-topic/wire/primitives.js";
 import type { TopicTrafficV1 } from "../cohort-topic/wire/types.js";
 import { QUERY_LIMIT_MAX } from "./config.js";
 
@@ -167,7 +179,7 @@ export interface AggregateBucketV1 {
 	count: number;
 }
 
-// --- validation helpers (mirror cohort-topic/wire/validate.ts; local to keep matchmaking DRY) ---
+// --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
 
 const utf8Encoder = new TextEncoder();
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
@@ -175,96 +187,6 @@ const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
 /** Ceiling for an opaque app payload (provider/seeker), guarding decode allocation. */
 export const DEFAULT_MAX_APP_PAYLOAD_BYTES = 64 * 1024;
 
-function fail(message: string): never {
-	throw new CohortWireError(message);
-}
-
-function asObject(value: unknown, what: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		fail(`${what}: expected an object`);
-	}
-	return value as Record<string, unknown>;
-}
-
-function requireV1(obj: Record<string, unknown>, what: string): void {
-	if (obj["v"] !== 1) {
-		fail(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
-	}
-}
-
-function reqString(obj: Record<string, unknown>, key: string, what: string): string {
-	const value = obj[key];
-	if (typeof value !== "string") {
-		fail(`${what}: field "${key}" must be a string`);
-	}
-	return value;
-}
-
-function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
-	const value = obj[key];
-	if (typeof value !== "boolean") {
-		fail(`${what}: field "${key}" must be a boolean`);
-	}
-	return value;
-}
-
-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") {
-		fail(`${what}: field "${key}" must be a boolean when present`);
-	}
-	return value;
-}
-
-function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
-	const value = obj[key];
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		fail(`${what}: field "${key}" must be a finite number`);
-	}
-	return value;
-}
-
-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)) {
-		fail(`${what}: field "${key}" must be a finite number when present`);
-	}
-	return value;
-}
-
-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")) {
-		fail(`${what}: field "${key}" must be an array of strings`);
-	}
-	return value as string[];
-}
-
-/** Assert a base64url string decodes cleanly; returns it unchanged. */
-function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		fail(`${what}: field "${key}" is not valid base64url`);
-	}
-	return value;
-}
-
-/** Require an integer `>= min` (and `<= max` when supplied). */
-function reqIntInRange(value: number, key: string, what: string, min: number, max?: number): number {
-	if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
-		const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
-		fail(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
-	}
-	return value;
-}
-
 function validateCapabilityFilter(value: unknown, what: string): CapabilityFilter {
 	const obj = asObject(value, what);
 	const out: CapabilityFilter = {
@@ -273,7 +195,7 @@ function validateCapabilityFilter(value: unknown, what: string): CapabilityFilte
 	};
 	const minBudget = optFiniteNumber(obj, "minBudget", what);
 	if (minBudget !== undefined) {
-		out.minBudget = reqIntInRange(minBudget, "minBudget", what, 0);
+		out.minBudget = reqIntInRange(obj, "minBudget", what, 0);
 	}
 	return out;
 }
@@ -290,7 +212,7 @@ export function validateProviderAppPayloadV1(value: unknown): ProviderAppPayload
 	const out: ProviderAppPayloadV1 = {
 		kind: "match-provider",
 		capabilities: reqStringArray(obj, "capabilities", what),
-		capacityBudget: reqIntInRange(reqFiniteNumber(obj, "capacityBudget", what), "capacityBudget", what, 0),
+		capacityBudget: reqIntInRange(obj, "capacityBudget", what, 0),
 		contactHint: reqString(obj, "contactHint", what),
 		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
 	};
@@ -310,7 +232,7 @@ export function validateSeekerAppPayloadV1(value: unknown): SeekerAppPayloadV1 {
 	}
 	const out: SeekerAppPayloadV1 = {
 		kind: "match-seeker",
-		wantCount: reqIntInRange(reqFiniteNumber(obj, "wantCount", what), "wantCount", what, 1),
+		wantCount: reqIntInRange(obj, "wantCount", what, 1),
 		contactHint: reqString(obj, "contactHint", what),
 		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
 	};
@@ -350,7 +272,8 @@ export type MatchAppPayloadV1 = ProviderAppPayloadV1 | SeekerAppPayloadV1;
 /**
  * Decode an opaque `RegisterV1.appPayload` to whichever matchmaking payload it carries, dispatched on
  * `kind` (parsed once — no exception-as-control-flow). The cohort query handler uses this to classify a
- * registration record into a provider vs. seeker entry. Throws {@link CohortWireError} on an unknown
+ * registration record into a provider vs. seeker entry. Throws
+ * {@link import("../cohort-topic/wire/primitives.js").CohortWireError} on an unknown
  * `kind` or a malformed payload.
  */
 export function decodeMatchAppPayload(bytes: Uint8Array, maxBytes: number = DEFAULT_MAX_APP_PAYLOAD_BYTES): MatchAppPayloadV1 {
@@ -395,7 +318,7 @@ export function validateQueryV1(value: unknown): QueryV1 {
 		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
 		includeProviders: reqBool(obj, "includeProviders", what),
 		includeSeekers: reqBool(obj, "includeSeekers", what),
-		limit: reqIntInRange(reqFiniteNumber(obj, "limit", what), "limit", what, 1, QUERY_LIMIT_MAX),
+		limit: reqIntInRange(obj, "limit", what, 1, QUERY_LIMIT_MAX),
 		requesterId: reqString(obj, "requesterId", what),
 		timestamp: reqFiniteNumber(obj, "timestamp", what),
 		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
@@ -423,7 +346,7 @@ function validateProviderEntryV1(value: unknown): ProviderEntryV1 {
 	return {
 		participantId: reqString(obj, "participantId", what),
 		capabilities: reqStringArray(obj, "capabilities", what),
-		capacityBudget: reqIntInRange(reqFiniteNumber(obj, "capacityBudget", what), "capacityBudget", what, 0),
+		capacityBudget: reqIntInRange(obj, "capacityBudget", what, 0),
 		contactHint: reqString(obj, "contactHint", what),
 		attachedAt: reqFiniteNumber(obj, "attachedAt", what),
 		registrationSig: b64urlField(reqString(obj, "registrationSig", what), "registrationSig", what),
@@ -435,7 +358,7 @@ function validateSeekerEntryV1(value: unknown): SeekerEntryV1 {
 	const obj = asObject(value, what);
 	return {
 		participantId: reqString(obj, "participantId", what),
-		wantCount: reqIntInRange(reqFiniteNumber(obj, "wantCount", what), "wantCount", what, 1),
+		wantCount: reqIntInRange(obj, "wantCount", what, 1),
 		contactHint: reqString(obj, "contactHint", what),
 		attachedAt: reqFiniteNumber(obj, "attachedAt", what),
 		registrationSig: b64urlField(reqString(obj, "registrationSig", what), "registrationSig", what),
@@ -473,9 +396,9 @@ function validateAggregateBucketV1(value: unknown): AggregateBucketV1 {
 	const what = "AggregateBucketV1";
 	const obj = asObject(value, what);
 	return {
-		targetTier: reqIntInRange(reqFiniteNumber(obj, "targetTier", what), "targetTier", what, 0),
-		prefixSlot: reqIntInRange(reqFiniteNumber(obj, "prefixSlot", what), "prefixSlot", what, 0),
-		count: reqIntInRange(reqFiniteNumber(obj, "count", what), "count", what, 0),
+		targetTier: reqIntInRange(obj, "targetTier", what, 0),
+		prefixSlot: reqIntInRange(obj, "prefixSlot", what, 0),
+		count: reqIntInRange(obj, "count", what, 0),
 	};
 }
 

package/src/network/i-key-network.ts

@@ -21,4 +21,14 @@ export type IKeyNetwork = {
 	 * @returns Promise resolving to the peers in the cluster
 	 */
 	findCluster(key: Uint8Array): Promise<ClusterPeers>;
+
+	/**
+	 * Optionally cache a resolved coordinator for a key, so a follow-up operation
+	 * (e.g. commit after pend) reuses the same peer. Implementations that don't
+	 * cache coordinators simply omit this. `ttlMs` bounds how long the hint lives.
+	 * @param key The key the coordinator was resolved for
+	 * @param peerId The coordinating peer
+	 * @param ttlMs Optional time-to-live for the cached hint, in ms
+	 */
+	recordCoordinator?(key: Uint8Array, peerId: PeerId, ttlMs?: number): void;
 }

package/src/network/i-repo.ts

@@ -13,6 +13,14 @@ export type MessageOptions = {
 	 * impose a separate dial cap; the overall budget is the cap".
 	 */
 	dialTimeoutMs?: number;
+	/**
+	 * Blocks this coordinator is responsible for driving through consensus. Threaded
+	 * from {@link NetworkTransactor.pend}'s batch (which consolidates several blocks
+	 * onto one coordinating peer) into {@link CoordinatorRepo.pend}, which uses it to
+	 * pick the cluster anchor. Absent on bare per-block paths, which fall back to the
+	 * transforms' own block ids.
+	 */
+	coordinatingBlockIds?: BlockId[];
 }
 
 export type RepoCommitRequest = {

package/src/network/struct.ts

@@ -39,6 +39,16 @@ export type PendRequest = ActionTransforms & {
 	operationsHash?: string;
 	/** For multi-collection transactions: supercluster nominees for consensus */
 	superclusterNominees?: PeerId[];
+	/**
+	 * Aged, advisory retry priority for the *single-collection* pend path (default 0 when absent).
+	 * The multi-collection path instead carries priority on {@link PendRequest.transaction}
+	 * ({@link Transaction.priority}); this top-level field is the carrier for a `Collection.sync`
+	 * pend, which has no `transaction`. A cluster member reads whichever is present as the first
+	 * `resolveRace` tiebreak. FAIRNESS-ONLY: it rides inside the signed cluster `message` (so it is
+	 * integrity-protected in transit) but MUST NOT affect the operations hash, stale-read checks, or
+	 * validity — a stale pend is still rejected regardless of priority.
+	 */
+	priority?: number;
 };
 
 export type BlockActionStatus = ActionBlocks & {

package/src/reactivity/push-state.ts

@@ -18,7 +18,7 @@
  */
 
 import { bytesToB64url, b64urlToBytes, decodeCohortMessage, encodeCohortMessage, DEFAULT_MAX_MESSAGE_BYTES } from "../cohort-topic/wire/codec.js";
-import { CohortWireError } from "../cohort-topic/wire/validate.js";
+import { asObject, b64urlField, failWire as fail, reqFiniteNumber, reqString } from "../cohort-topic/wire/primitives.js";
 import { DEDUPE_WINDOW_DEFAULT, QUEUE_MAX_DEFAULT, W_DEFAULT } from "./config.js";
 import { createSubscriberBackpressure, type SubscriberBackpressure, type SubscriberEnqueueResult } from "./backpressure.js";
 import { RollingCheckpoint, type CheckpointSummary, type DeltaCoalesce, type DigestFold } from "./checkpoint.js";
@@ -204,33 +204,9 @@ export class PushState {
 }
 
 // --- gossip codec (length-framed JSON, mirroring cohort-topic conventions) ---
-
-function fail(message: string): never {
-	throw new CohortWireError(message);
-}
-
-function asObject(value: unknown, what: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		fail(`${what}: expected an object`);
-	}
-	return value as Record<string, unknown>;
-}
-
-function reqString(obj: Record<string, unknown>, key: string, what: string): string {
-	const value = obj[key];
-	if (typeof value !== "string") {
-		fail(`${what}: field "${key}" must be a string`);
-	}
-	return value;
-}
-
-function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
-	const value = obj[key];
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		fail(`${what}: field "${key}" must be a finite number`);
-	}
-	return value;
-}
+// Generic structural primitives (fail/asObject/reqString/reqFiniteNumber/b64urlField) are imported from
+// cohort-topic/wire/primitives.js; only `reqInt` stays local — it is a range-free integer check (no
+// lower bound), unlike the shared `reqIntInRange`, so folding it in would change behavior.
 
 function reqInt(value: number, key: string, what: string): number {
 	if (!Number.isInteger(value)) {
@@ -239,15 +215,6 @@ function reqInt(value: number, key: string, what: string): number {
 	return value;
 }
 
-function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		fail(`${what}: field "${key}" is not valid base64url`);
-	}
-	return value;
-}
-
 function validateCohortRef(value: unknown, what: string): CohortRef {
 	const obj = asObject(value, what);
 	const coord = b64urlField(reqString(obj, "coord", what), "coord", what);

package/src/reactivity/wire-validate.ts

@@ -2,86 +2,12 @@
  * Reactivity — shared wire-validation primitives.
  *
  * The reactivity message codecs ({@link import("./wire.js")}, {@link import("./push-state.js")},
- * {@link import("./backfill.js")}, {@link import("./resume.js")}) all decode untrusted JSON into
- * validated V1 shapes with the same structural checks. Those primitives live here so each codec module
- * narrows fields the same way (DRY) — every helper throws {@link CohortWireError} on a defect, matching
- * the cohort-topic wire conventions (base64url byte fields, finite/integer numbers, `v: 1`).
+ * {@link import("./backfill.js")}, {@link import("./resume.js")}, plus checkpoint / rotation / recover)
+ * decode untrusted JSON into validated V1 shapes with the same structural checks the rest of the
+ * substrate uses. Those generic primitives now live in one place —
+ * {@link import("../cohort-topic/wire/primitives.js")} — so a hardening tweak lands once; this module is
+ * a thin re-export kept so the reactivity codecs import from a sibling path. Every helper throws
+ * {@link CohortWireError} on a defect (base64url byte fields, finite/integer numbers, `v: 1`).
  */
 
-import { b64urlToBytes } from "../cohort-topic/wire/codec.js";
-import { CohortWireError } from "../cohort-topic/wire/validate.js";
-
-/** Throw a {@link CohortWireError} with `message`. */
-export function failWire(message: string): never {
-	throw new CohortWireError(message);
-}
-
-/** 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;
-}
-
-/** Require `obj[key]` to be a boolean; returns it. */
-export function reqBoolean(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;
-}
-
-/** 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;
-}
-
-/** Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. */
-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;
-}
-
-/** Assert a base64url string decodes cleanly; returns it unchanged. */
-export function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		failWire(`${what}: field "${key}" is not valid base64url`);
-	}
-	return value;
-}
-
-/** Require `value` to be an array of strings; returns it (callers map each element through {@link b64urlField}). */
-export function reqStringArray(value: unknown, key: string, what: string): string[] {
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
-		failWire(`${what}: field "${key}" must be an array of strings`);
-	}
-	return value as string[];
-}
+export * from "../cohort-topic/wire/primitives.js";

package/src/reactivity/wire.ts

@@ -31,7 +31,7 @@ import {
 	asObject,
 	b64urlField,
 	failWire as fail,
-	reqBoolean,
+	reqBool,
 	reqFiniteNumber,
 	reqIntInRange,
 	reqString,
@@ -179,7 +179,7 @@ export function validateNotificationV1(value: unknown): NotificationV1 {
 	const what = "NotificationV1";
 	const obj = asObject(value, what);
 	requireV1(obj, what);
-	const signers = reqStringArray(obj["signers"], "signers", what);
+	const signers = reqStringArray(obj, "signers", what);
 	const out: NotificationV1 = {
 		v: 1,
 		collectionId: b64urlField(reqString(obj, "collectionId", what), "collectionId", what),
@@ -197,7 +197,7 @@ export function validateNotificationV1(value: unknown): NotificationV1 {
 		out.rotationHint = validateRotationHint(obj["rotationHint"], `${what}.rotationHint`);
 	}
 	if (obj["invalidation"] !== undefined) {
-		out.invalidation = reqBoolean(obj, "invalidation", what);
+		out.invalidation = reqBool(obj, "invalidation", what);
 	}
 	if (obj["invalidatedActionId"] !== undefined) {
 		out.invalidatedActionId = reqString(obj, "invalidatedActionId", what);

package/src/testing/async-wait.ts

@@ -0,0 +1,65 @@
+export interface WaitForOptions {
+	// NOTE: default is tuned for in-process settles; integration callers over real libp2p
+	// pass explicit 10k–90k bounds. A new caller that omits timeoutMs gets 2s — fine for
+	// fast local conditions, but if a slow CI machine flakes on a legitimately-slow wait,
+	// give that call site an explicit timeoutMs rather than raising this default.
+	/** Upper bound before the poll gives up. Default 2_000. */
+	timeoutMs?: number;
+	/** Poll cadence. Default 10. */
+	intervalMs?: number;
+	/** Included in the thrown message so a failure says WHAT never became true. */
+	description?: string;
+}
+
+/** Real-time sleep. Retain ONLY for residual cases a condition poll cannot cover. */
+export const delay = (ms: number): Promise<void> =>
+	new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Poll `predicate` until it returns true or `timeoutMs` elapses; throws on timeout.
+ * `predicate` may be sync or async; a thrown/rejected predicate propagates immediately.
+ * `undefined` is treated as `false` (not ready yet).
+ */
+export async function waitFor(
+	predicate: () => boolean | Promise<boolean>,
+	opts?: WaitForOptions,
+): Promise<void> {
+	const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (await predicate()) return;
+		if (Date.now() >= deadline) {
+			throw new Error(
+				description
+					? `waitFor timed out after ${timeoutMs}ms: ${description}`
+					: `waitFor timed out after ${timeoutMs}ms`,
+			);
+		}
+		await delay(intervalMs);
+	}
+}
+
+/**
+ * Poll `fn` until it returns a non-undefined value or `timeoutMs` elapses; throws on timeout.
+ * `undefined` means "not ready yet" — callers needing to wait for an actual `undefined`
+ * should use `waitFor` on a separate flag.
+ */
+export async function waitForValue<T>(
+	fn: () => T | undefined | Promise<T | undefined>,
+	opts?: WaitForOptions,
+): Promise<T> {
+	const { timeoutMs = 2_000, intervalMs = 10, description } = opts ?? {};
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const value = await fn();
+		if (value !== undefined) return value;
+		if (Date.now() >= deadline) {
+			throw new Error(
+				description
+					? `waitForValue timed out after ${timeoutMs}ms: ${description}`
+					: `waitForValue timed out after ${timeoutMs}ms`,
+			);
+		}
+		await delay(intervalMs);
+	}
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export * from './test-transactor.js';
+export * from './async-wait.js';