@optimystic/db-core 0.13.5 → 0.14.1

package/src/collections/tree/tree.ts

@@ -1,14 +1,33 @@
-import { Collection, type CollectionInitOptions, type CollectionId } from "../../collection/index.js";
+import { Collection, type CollectionInitOptions, type CollectionId, type CollectionSnapshot } from "../../collection/index.js";
 import type { ITransactor, BlockId, BlockStore, IBlock } from "../../index.js";
 import { BTree, type Path, type KeyRange } from "../../btree/index.js";
 import { CollectionTrunk } from "./collection-trunk.js";
 import { TreeHeaderBlockType, type TreeReplaceAction } from "./struct.js";
 
-export class Tree<TKey, TEntry> {
+/**
+ * Read-only surface of a tree: every navigation/lookup method a reader needs, with
+ * none of the mutation (stage/sync) or network-refresh (update) entry points. Both
+ * the live {@link Tree} and the committed view returned by {@link Tree.readView}
+ * structurally satisfy this, so a consumer can read through either uniformly.
+ */
+export interface TreeReadView<TKey, TEntry> {
+	first(): Promise<Path<TKey, TEntry>>;
+	find(key: TKey): Promise<Path<TKey, TEntry>>;
+	get(key: TKey): Promise<TEntry | undefined>;
+	at(path: Path<TKey, TEntry>): TEntry | undefined;
+	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>>;
+	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>>;
+	isValid(path: Path<TKey, TEntry>): boolean;
+}
+
+export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 
 	private constructor(
 		private readonly collection: Collection<TreeReplaceAction<TKey, TEntry>>,
 		private readonly btree: BTree<TKey, TEntry>,
+		/** Captured so {@link readView} can rebuild a BTree over a committed tracker. */
+		private readonly keyFromEntry: (entry: TEntry) => TKey,
+		private readonly compare: (a: TKey, b: TKey) => number,
 	) {
 	}
 
@@ -48,7 +67,7 @@ export class Tree<TKey, TEntry> {
 
 		const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
 		btree = btree ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare);
-		return new Tree<TKey, TEntry>(collection, btree);
+		return new Tree<TKey, TEntry>(collection, btree, keyFromEntry, compare);
 	}
 
 	async replace(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
@@ -56,6 +75,68 @@ export class Tree<TKey, TEntry> {
 			await this.collection.updateAndSync();
 	}
 
+	/** Stage a mutation into the collection's tracker WITHOUT flushing it to the
+	 * transactor. Reads through this same Tree instance see the staged change;
+	 * call {@link sync} to persist it, or {@link snapshot}/{@link restore} to drop it. This
+	 * is the deferred counterpart to {@link replace}, which stages and flushes in
+	 * one step — use {@link stage} when the persist/discard decision belongs to a
+	 * surrounding transaction's commit/rollback. */
+	async stage(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
+			await this.collection.act({ type: "replace", data });
+	}
+
+	/** Flush all staged (and any other pending) changes to the transactor.
+	 * Equivalent to the flush half of {@link replace}. */
+	async sync(): Promise<void> {
+			await this.collection.updateAndSync();
+	}
+
+	/** Capture the current staged state so it can be restored via {@link restore}.
+	 * Take this BEFORE staging a unit of work that may be rolled back. The snapshot
+	 * is opaque; pass the exact value back to {@link restore}. */
+	snapshot(): CollectionSnapshot<TreeReplaceAction<TKey, TEntry>> {
+			return this.collection.snapshotPending();
+	}
+
+	/** Restore the staged state captured by {@link snapshot}, discarding mutations
+	 * staged since. Counterpart to {@link stage} for transaction rollback —
+	 * preserves a never-synced collection's header/root rather than wiping it. */
+	restore(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): void {
+			this.collection.restorePending(snapshot);
+	}
+
+	/** Build a read-only view of this tree as captured by an earlier {@link snapshot}
+	 * — typically the pre-transaction state recorded before any DML was staged. The
+	 * view reads through a FRESH tracker seeded with the snapshot's transforms over
+	 * the SAME committed source cache, so it observes exactly the snapshot's state:
+	 * it never sees mutations staged into the live tree after the snapshot, and it
+	 * does not disturb the live tree (reads are latch-free and tracker-isolated). This
+	 * is how a `committed.*` scan reads the pre-transaction snapshot while the live
+	 * tree still holds this transaction's in-flight inserts.
+	 *
+	 * `snapshot` is the opaque value returned by {@link snapshot}; pass it back
+	 * verbatim. */
+	readView(snapshot: CollectionSnapshot<TreeReplaceAction<TKey, TEntry>>): TreeReadView<TKey, TEntry> {
+			const tracker = this.collection.createReadTracker(snapshot.transforms);
+			return new BTree<TKey, TEntry>(
+				tracker,
+				new CollectionTrunk(tracker, this.collection.id),
+				this.keyFromEntry,
+				this.compare,
+			);
+	}
+
+	/** The underlying {@link Collection} this tree stages mutations into.
+	 *
+	 * Exposed (package-internal intent) so a transaction coordinator can register
+	 * and read the very tracker this tree mutates: session-mode commit reads
+	 * `collection.tracker.transforms` directly, so the coordinator's collection
+	 * map must hold the same instance the tree stages into. Prefer this accessor
+	 * over reaching through `tree['collection']`. */
+	getCollection(): Collection<TreeReplaceAction<TKey, TEntry>> {
+			return this.collection;
+	}
+
 	/**
 	 * Update the local state from the network.
 	 * Call this before reading to ensure you have the latest data.

package/src/index.ts

@@ -2,10 +2,13 @@ export * from "./blocks/index.js";
 export * from "./btree/index.js";
 export * from "./chain/index.js";
 export * from "./cluster/index.js";
+export * from "./cohort-topic/index.js";
 export * from "./collection/index.js";
 export * from "./collections/index.js";
 export * from "./log/index.js";
+export * from "./matchmaking/index.js";
 export * from "./network/index.js";
+export * from "./reactivity/index.js";
 export * from "./transaction/index.js";
 export * from "./transactor/index.js";
 export * from "./transform/index.js";

package/src/log/log.ts

@@ -1,9 +1,9 @@
 import { sha256 } from 'multiformats/hashes/sha2'
 import { Chain, entryAt } from "../index.js";
 import { nameof } from "../utility/nameof.js";
-import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore } from "../index.js";
+import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore, ReadDependency } from "../index.js";
 import type { ChainDataNode } from '../chain/chain-nodes.js';
-import type { LogEntry, ActionEntry } from "./index.js";
+import type { LogEntry, ActionEntry, DisputeResolutionProof, InvalidationEntry, RevertedBlock } from "./index.js";
 import { LogDataBlockType, LogHeaderBlockType } from "./index.js";
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import type { GetFromResult } from './struct.js';
@@ -41,9 +41,19 @@ export class Log<TAction> {
 		}));
 	}
 
-	/** Adds a new entry to the log. */
-	async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], collectionIds: CollectionId[] = [], timestamp: number = Date.now()) {
-		const entry = { timestamp, rev, action: { actionId, actions, blockIds: [], collectionIds } } as LogEntry<TAction>;
+	/**
+	 * Adds a new action entry to the log.
+	 *
+	 * `reads` is the transaction's `(blockId, revision)` read set, persisted on the entry so the
+	 * invalidation cascade can later discover this action's read-dependents (see
+	 * {@link ActionEntry.reads}). Omit it (or pass `undefined`) on the low-level direct-commit path
+	 * that carries no `Transaction`; the cascade then treats the entry as an unknown dependency.
+	 */
+	async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], collectionIds: CollectionId[] = [], reads?: ReadDependency[], timestamp: number = Date.now()) {
+		const action = reads !== undefined
+			? { actionId, actions, blockIds: [], collectionIds, reads }
+			: { actionId, actions, blockIds: [], collectionIds };
+		const entry = { timestamp, rev, action } as LogEntry<TAction>;
 		const tailPath = await this.chain.add(entry);
 		const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
 		this.chain.updateAt(tailPath, entryWithBlockIds);
@@ -57,6 +67,70 @@ export class Log<TAction> {
 		return { entry, tailPath };
 	}
 
+	/**
+	 * Appends a compensating invalidation entry that reverses a previously-committed action proven
+	 * invalid by dispute. The committed history is never rewritten — this is a new, append-only,
+	 * prior-hash-linked entry, recoverable on sync exactly like a commit. The caller has already
+	 * verified `resolution` is a challenger-wins certificate and computed the per-block `reverted`
+	 * targets (the new revisions restoring the as-if-`T_inv`-absent content).
+	 */
+	async addInvalidation(
+		invalidatedActionId: ActionId,
+		invalidatedRev: number,
+		resolution: DisputeResolutionProof,
+		reverted: ReadonlyArray<RevertedBlock>,
+		rev: number,
+		cascadeRoot?: ActionId,
+		timestamp: number = Date.now()
+	) {
+		const invalidation: InvalidationEntry = cascadeRoot !== undefined
+			? { invalidatedActionId, invalidatedRev, resolution, reverted, cascadeRoot }
+			: { invalidatedActionId, invalidatedRev, resolution, reverted };
+		const entry = { timestamp, rev, invalidation } as LogEntry<TAction>;
+		const tailPath = await this.chain.add(entry);
+		return { entry, tailPath };
+	}
+
+	/**
+	 * Finds the most recent invalidation entry that reverses the given committed action, if any.
+	 * This is the durable source of truth for `committed-invalidated` status — once the entry has
+	 * landed in the log, the reversal is recoverable on sync independent of any in-memory cache.
+	 * Scans newest→oldest (O(n) over the chain, matching {@link getFrom}); returns the first match.
+	 */
+	async findInvalidation(invalidatedActionId: ActionId): Promise<InvalidationEntry | undefined> {
+		for await (const path of this.chain.select(undefined, false)) {
+			const invalidation = entryAt<LogEntry<TAction>>(path)!.invalidation;
+			if (invalidation && invalidation.invalidatedActionId === invalidatedActionId) {
+				return invalidation;
+			}
+		}
+		return undefined;
+	}
+
+	/**
+	 * Returns the invalidation entries appended after `startRev` (exclusive), newest-first. Used by
+	 * {@link import("../collection/collection.js").Collection} on `update` to discover reversals that
+	 * landed since the client last synced: a client holding a result derived from now-reverted content
+	 * drops it and replays against the reverted base — the same "your base moved, re-sync and retry"
+	 * path a stale read triggers (`docs/right-is-right.md` §Client notification). Unlike {@link getFrom}
+	 * (which skips invalidation entries — they are not pending/committed actions), this surfaces exactly
+	 * the invalidations. Scans newest→oldest and stops once at/below `startRev` (revs are monotonic), so
+	 * the walk is bounded to the unsynced tail.
+	 */
+	async getInvalidationsFrom(startRev: number | undefined): Promise<InvalidationEntry[]> {
+		const invalidations: InvalidationEntry[] = [];
+		for await (const path of this.chain.select(undefined, false)) {
+			const entry = entryAt<LogEntry<TAction>>(path)!;
+			if (startRev !== undefined && entry.rev <= startRev) {
+				break;
+			}
+			if (entry.invalidation) {
+				invalidations.push(entry.invalidation);
+			}
+		}
+		return invalidations;
+	}
+
 	/** Gets the action context of the log. */
 	async getActionContext(): Promise<ActionContext | undefined> {
 		const tailPath = await this.chain.getTail();
@@ -90,9 +164,14 @@ export class Log<TAction> {
 				pendings.unshift(...entry.checkpoint.pendings);
 				break;
 			}
-			pendings.unshift({ actionId: entry.action!.actionId, rev: entry.rev });
+			// Invalidation entries take a rev slot but are not pending actions — skip them in
+			// the committed/pending set (the reversal is surfaced via findInvalidation instead).
+			if (!entry.action) {
+				continue;
+			}
+			pendings.unshift({ actionId: entry.action.actionId, rev: entry.rev });
 			if (startRev !== undefined && entry.rev > startRev) {
-				entries.unshift(entry.action!);
+				entries.unshift(entry.action);
 			}	// Can't stop at rev, because we need to collect all pending actions for the context
 		}
 		// Continue stepping past the checkpoint until the given rev is reached

package/src/log/struct.ts

@@ -1,6 +1,6 @@
-import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev } from "../index.js";
+import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
 
-/** A log entry - either an action or a checkpoint */
+/** A log entry - an action, a checkpoint, or an invalidation */
 export type LogEntry<TAction> = {
 	/** Linux timestamp of the entry */
 	readonly timestamp: number;
@@ -8,6 +8,8 @@ export type LogEntry<TAction> = {
 	readonly rev: number;
 	readonly action?: ActionEntry<TAction>;
 	readonly checkpoint?: CheckpointEntry;
+	/** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
+	readonly invalidation?: InvalidationEntry;
 };
 
 /** An action entry represents a unit of work that is atomic */
@@ -20,6 +22,128 @@ export type ActionEntry<TAction> = {
 	blockIds: BlockId[]; // NOTE: this is updated after being generated to include the log-related block transforms
 	/** Other collection ids affected by the action - this action is conditional on successful commit in all of these collections */
 	readonly collectionIds?: CollectionId[];
+	/**
+	 * The `(blockId, revision)` reads this transaction observed during execution — the same
+	 * read set the {@link Transaction} carried in its PEND request (see `Transaction.reads`).
+	 *
+	 * Persisted so a later invalidation cascade can discover this action's read-dependents:
+	 * a committed action is a read-dependent of an invalidated one iff its read set contains a
+	 * `(blockId, revision)` that the invalidated action produced.
+	 *
+	 * **Format / back-compat:** added by the invalidation-cascade work (ActionEntry v2). An entry
+	 * written before this field existed (or by a path that does not carry a `Transaction`, e.g. the
+	 * low-level `Collection.sync` direct-commit) has `reads === undefined` — treated by the cascade
+	 * as an *unknown dependency* (conservatively re-evaluated, never silently assumed independent).
+	 * `reads === []` is distinct: a transaction that genuinely read nothing.
+	 */
+	readonly reads?: ReadDependency[];
+};
+
+/**
+ * One arbitrator's signed verdict — the minimal subset of a dispute vote needed to re-verify
+ * it independently. The Ed25519 public key that verifies {@link signature} is embedded in
+ * {@link arbitratorPeerId} (a libp2p Ed25519 peer id).
+ *
+ * The signed payload is **target- and arbitrator-set-bound** (v3):
+ * `utf8(`v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`)`, where
+ *  - `targetHash = hashString(`${messageHash}|${invalidatedActionId}|${sortedBlockIds.join(',')}`)`
+ *    commits the vote to the *specific* transaction being reversed (#2), and
+ *  - `setHash = hashString(sortedArbitratorSet.join(','))` commits it to the *legitimately-selected
+ *    arbitrator set* (#1) carried on {@link DisputeResolutionProof.arbitratorSet}.
+ *
+ * A verifier recomputes both digests from the proof plus the apply-path target, so a genuine vote can
+ * neither be replayed against an unrelated transaction nor presented under a swapped cohort. v1/v2
+ * (un-set-bound) votes are rejected, not accepted-by-default; the {@link version} marker is required.
+ */
+export type ArbitrationVoteProof = {
+	/** Wire-format version of the signed payload. Only `'v3'` is accepted; absent/unrecognized → rejected. */
+	readonly version: 'v3';
+	/** Peer id of the arbitrator; its embedded Ed25519 public key verifies {@link signature}. */
+	readonly arbitratorPeerId: string;
+	/** The arbitrator's verdict. */
+	readonly vote: 'agree-with-challenger' | 'agree-with-majority' | 'inconclusive';
+	/** The operations hash the arbitrator computed (part of the signed payload). */
+	readonly computedHash: string;
+	/** Base64url-encoded Ed25519 signature over `v3:${disputeId}:${vote}:${computedHash}:${targetHash}:${setHash}`. */
+	readonly signature: string;
+};
+
+/**
+ * The authoritative, independently-verifiable subset of a dispute resolution that proves a
+ * committed transaction invalid. Carried inside an {@link InvalidationEntry}.
+ *
+ * Defined in db-core (the log layer) deliberately: the log must not import db-p2p, so the dispute
+ * layer's richer `DisputeResolution` maps *onto* this proof rather than this proof importing it.
+ * A member treats the proof as a reversal certificate — `outcome === 'challenger-wins'` with a
+ * 2/3 super-majority of decisive votes agreeing with the challenger (each signature verifiable
+ * against its arbitrator's embedded key, each vote target-bound, drawn from the legitimately-selected
+ * {@link arbitratorSet}, and counted at most once per arbitrator).
+ *
+ * **Unforgeability.** Votes are bound to the reversed transaction (`targetHash`, #2), counted at most
+ * once per arbitrator (#3), and bound to the legitimately-selected arbitrator set (#1):
+ * {@link arbitratorSet} carries the K peer-ids the challenger selected, every counted vote must be a
+ * member of it, and {@link arbitratorSetSignature} — the challenger's Ed25519 signature (verified
+ * against {@link challengerPeerId}) over `(disputeId, target, arbitratorSet)` — binds the set to the
+ * originator so a third-party relay cannot swap in its own sybils. A verifying member additionally
+ * re-derives the eligible set from its own topology when it can (an injected recompute capability),
+ * closing even a fully-malicious challenger; when it cannot (late-joiner / churned DHT view) it accepts
+ * on the challenger-bound set + membership + dedup and *logs* the residual topology-anchoring gap rather
+ * than silently accepting — a gap closed in full by the cohort-topic membership-cert trust-anchor chain
+ * (`tickets/plan/cohort-topic-membership-cert-trust-anchoring.md`). Net: a compromised peer can withhold
+ * an invalidation but cannot forge one.
+ */
+export type DisputeResolutionProof = {
+	/** Identifies the dispute these votes resolved. */
+	readonly disputeId: string;
+	/** messageHash of the original (now-invalid) committed transaction. */
+	readonly messageHash: string;
+	/** Resolution outcome; only `challenger-wins` authorizes an invalidation. */
+	readonly outcome: 'challenger-wins' | 'majority-wins' | 'inconclusive';
+	/**
+	 * Peer-id of the challenger (dissent coordinator) that selected the arbitrator set and produced
+	 * {@link arbitratorSetSignature}; its embedded Ed25519 key verifies that signature.
+	 */
+	readonly challengerPeerId: string;
+	/**
+	 * The legitimately-selected arbitrator set — the K peer-ids the challenger computed via
+	 * `selectArbitrators` (the next K peers beyond the original cluster by XOR distance to the disputed
+	 * block). Every counted vote's `arbitratorPeerId` must be a member; the set is bound to the originator
+	 * by {@link arbitratorSetSignature} and, when feasible, re-derived from the verifying member's topology.
+	 */
+	readonly arbitratorSet: ReadonlyArray<string>;
+	/**
+	 * The challenger's base64url Ed25519 signature (verified against {@link challengerPeerId}'s embedded
+	 * key) over `utf8(`v3set:${disputeId}:${targetHash}:${setHash}`)` — binds `(disputeId, target,
+	 * arbitratorSet)` to the originator so a relay cannot substitute its own cohort. Tampering with
+	 * {@link arbitratorSet} (e.g. adding sybils) invalidates this signature.
+	 */
+	readonly arbitratorSetSignature: string;
+	/** Signed arbitrator votes. */
+	readonly votes: ReadonlyArray<ArbitrationVoteProof>;
+};
+
+/** Per-block compensating result an invalidation produced. */
+export type RevertedBlock = {
+	/** Block whose tip was reverted. */
+	readonly blockId: BlockId;
+	/** Revision the block was at before this invalidation (the tip that was reverted). */
+	readonly fromRev: number;
+	/** Content hash of the new revision restoring the as-if-`T_inv`-absent content. */
+	readonly restoredContentHash: string;
+};
+
+/** A compensating entry that reverses a previously-committed action proven invalid by dispute. */
+export type InvalidationEntry = {
+	/** actionId of the committed {@link ActionEntry} being reversed. */
+	readonly invalidatedActionId: ActionId;
+	/** rev of the invalidated entry — pins which block revisions to roll back. */
+	readonly invalidatedRev: number;
+	/** Authoritative proof: a challenger-wins resolution carrying the signed arbitrator votes. */
+	readonly resolution: DisputeResolutionProof;
+	/** Per-block compensating result this entry produced (new monotonic revision restoring pre-`T_inv` content). */
+	readonly reverted: ReadonlyArray<RevertedBlock>;
+	/** When this invalidation is a cascade step, the root invalidation that triggered it (unused this ticket; see cascade ticket). */
+	readonly cascadeRoot?: ActionId;
 };
 
 /** A checkpoint entry restates the currently uncheckpointed actions */

package/src/matchmaking/capability-filter.ts

@@ -0,0 +1,45 @@
+/**
+ * Matchmaking — cohort-side capability-filter evaluation (db-core, pure).
+ *
+ * Per `docs/matchmaking.md` §Capability filter: the filter is evaluated **locally at the cohort** and
+ * is **advisory only** — it biases which providers the cohort returns but is never admission. The
+ * seeker re-validates the returned set (`registrationSig`) and escalates if the filter matches too
+ * little (§Edge cases 4). A pathological filter that matches almost nothing is therefore acceptable.
+ *
+ * Semantics (`docs/matchmaking.md` §Capability filter / §Wire formats):
+ * - `must`    — every tag must be present in the provider's `capabilities`.
+ * - `mustNot` — no tag may be present in the provider's `capabilities`.
+ * - `minBudget` — when set, the provider's `capacityBudget` must be `>= minBudget`.
+ *
+ * An absent filter matches every provider.
+ */
+
+import type { CapabilityFilter } from "./wire.js";
+
+/** The provider attributes a {@link CapabilityFilter} is evaluated against. */
+export interface FilterableProvider {
+	readonly capabilities: readonly string[];
+	readonly capacityBudget: number;
+}
+
+/** True iff `p` satisfies `f` (`must` ⊆ caps, `mustNot` ∩ caps = ∅, `capacityBudget >= minBudget`). */
+export function matchesFilter(p: FilterableProvider, f: CapabilityFilter | undefined): boolean {
+	if (f === undefined) {
+		return true;
+	}
+	const caps = new Set(p.capabilities);
+	for (const tag of f.must) {
+		if (!caps.has(tag)) {
+			return false;
+		}
+	}
+	for (const tag of f.mustNot) {
+		if (caps.has(tag)) {
+			return false;
+		}
+	}
+	if (f.minBudget !== undefined && p.capacityBudget < f.minBudget) {
+		return false;
+	}
+	return true;
+}

package/src/matchmaking/config.ts

@@ -0,0 +1,98 @@
+/**
+ * Matchmaking — configuration defaults.
+ *
+ * Transcribed from `docs/matchmaking.md` §Configuration. This module owns the matchmaking config
+ * surface: the **wire/TTL** constants (provider/seeker TTLs, the query limit, the seeker renew grace,
+ * the aggregate-count minimum tier) AND the seeker **hang-out tuning** rows (`patience_*`,
+ * `filter_accept_ratio_initial`, `contention_factor_cap`, `requery_interval_ms`, `mean_want_count`)
+ * consumed by the {@link import("./seeker-walk.js").decide} engine and the db-p2p seeker-walk client.
+ *
+ * The TTL/limit constants are wire-stable and do **not** depend on simulator findings; the hang-out
+ * rows DO (folded via `fold-simulator-findings-into-design-docs`) — they carry the simulator-validated
+ * defaults (`contention_factor_cap = 4.0`, `mean_want_count = 3`, …; see `docs/matchmaking.md`
+ * §Configuration "Defaults validated by simulator"). The `push_*` rows belong to the arrival-push
+ * path (a separate slice) and are intentionally not modeled here.
+ */
+
+import type { NodeProfile } from "../cohort-topic/tiers.js";
+
+/** Provider registration TTL on a Core node (ms). */
+export const PROVIDER_TTL_CORE_MS = 90_000;
+/** Provider registration TTL on an Edge node (ms). */
+export const PROVIDER_TTL_EDGE_MS = 60_000;
+/** Seeker registration TTL (ms) — short, since seekers normally don't wait long. */
+export const SEEKER_TTL_MS = 10_000;
+/** Documented seeker-TTL range (ms); `SEEKER_TTL_MS` sits inside it. */
+export const SEEKER_TTL_MIN_MS = 5_000;
+export const SEEKER_TTL_MAX_MS = 15_000;
+/** Max entries returned in a single `QueryV1` reply. */
+export const QUERY_LIMIT_MAX = 256;
+/** Grace window a seeker may keep querying after its TTL expires (ms). */
+export const SEEKER_RENEW_GRACE_MS = 5_000;
+/** Root cohorts produce aggregate counts only when tree depth ≥ this. */
+export const AGGREGATE_COUNT_MINIMUM_TIER = 1;
+
+// --- Seeker hang-out tuning (simulator-folded; consumed by seeker-walk.ts + the walk client) ---
+
+/** Fallback `patienceMs` when a caller does not specify it per-task (ms). */
+export const PATIENCE_DEFAULT_MS = 10_000;
+/** Fraction of remaining patience spent at one tier before considering escalation (1.0 = spend it all here). */
+export const PATIENCE_PER_TIER_FRACTION = 1.0;
+/** Starting estimate for `filterAcceptRatio`, refined per walk from observed query yields. */
+export const FILTER_ACCEPT_RATIO_INITIAL = 1.0;
+/** Upper bound on the contention multiplier in the hang-out decision (simulator-validated global scalar). */
+export const CONTENTION_FACTOR_CAP = 4.0;
+/** Mean `wantCount` assumed for competing seekers in the contention estimate (small constant; simulator value). */
+export const MEAN_WANT_COUNT_DEFAULT = 3;
+/** How often a hanging-out seeker re-issues `QueryV1` on the non-push (poll) path (ms). */
+export const REQUERY_INTERVAL_MS = 1_000;
+/** Window the seeker's primary batches fresh matchable arrivals before flushing one push (ms; arrival-push path). */
+export const PUSH_COALESCE_MS = 250;
+/** Sparse fallback `QueryV1` cadence for a push-aware hanging-out seeker (ms; arrival-push path). */
+export const PUSH_SAFETY_POLL_MS = 5_000;
+
+/**
+ * The seeker hang-out decision tuning (`docs/matchmaking.md` §Hang-out vs. continue / §Configuration).
+ * `meanWantCount` lives here because {@link import("./seeker-walk.js").SeekerDecisionInputs} carries it
+ * per-call (it may be learned), but the default is this constant.
+ */
+export interface HangOutConfig {
+	/** Clamp on the contention multiplier; protects against pathological `queriesPerMin / arrivalsPerMin`. */
+	readonly contentionFactorCap: number;
+	/** Hang-out poll cadence on the non-push path. */
+	readonly requeryIntervalMs: number;
+}
+
+/** The default hang-out decision config (simulator-validated). */
+export const DEFAULT_HANG_OUT_CONFIG: HangOutConfig = {
+	contentionFactorCap: CONTENTION_FACTOR_CAP,
+	requeryIntervalMs: REQUERY_INTERVAL_MS,
+};
+
+/** The full matchmaking config, with the documented defaults. */
+export interface MatchmakingConfig {
+	readonly providerTtlCoreMs: number;
+	readonly providerTtlEdgeMs: number;
+	readonly seekerTtlMs: number;
+	readonly queryLimitMax: number;
+	readonly seekerRenewGraceMs: number;
+	readonly aggregateCountMinimumTier: number;
+}
+
+/** The default matchmaking config (this ticket's slice). */
+export const DEFAULT_MATCHMAKING_CONFIG: MatchmakingConfig = {
+	providerTtlCoreMs: PROVIDER_TTL_CORE_MS,
+	providerTtlEdgeMs: PROVIDER_TTL_EDGE_MS,
+	seekerTtlMs: SEEKER_TTL_MS,
+	queryLimitMax: QUERY_LIMIT_MAX,
+	seekerRenewGraceMs: SEEKER_RENEW_GRACE_MS,
+	aggregateCountMinimumTier: AGGREGATE_COUNT_MINIMUM_TIER,
+};
+
+/**
+ * Provider TTL for a node profile: Core nodes hold registrations for `PROVIDER_TTL_CORE_MS`, Edge
+ * nodes for the shorter `PROVIDER_TTL_EDGE_MS` (`docs/matchmaking.md` §Provider registration).
+ */
+export function providerTtlForProfile(profile: NodeProfile, config: MatchmakingConfig = DEFAULT_MATCHMAKING_CONFIG): number {
+	return profile.kind === "edge" ? config.providerTtlEdgeMs : config.providerTtlCoreMs;
+}

package/src/matchmaking/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Matchmaking — the directory application of the cohort-topic substrate.
+ *
+ * See `docs/matchmaking.md`. The db-core layer owns the transport-agnostic pieces: wire codecs +
+ * seeker-side entry re-validation, the stable topic-anchor derivation, configuration, both
+ * registration roles' decision/state (provider attach/renew/self-throttle; seeker short-TTL
+ * registration), the cohort-side capability filter + pure query evaluation, and the seeker
+ * hang-out-vs-continue decision engine. The db-p2p layer wires these to the cohort-topic substrate
+ * (managers, the cohort query handler, the seeker walk client).
+ */
+
+export * from "./config.js";
+export * from "./topic-anchor.js";
+export * from "./wire.js";
+export * from "./provider.js";
+export * from "./seeker.js";
+export * from "./capability-filter.js";
+export * from "./query-eval.js";
+export * from "./seeker-walk.js";
+export * from "./multi-cohort-seeker.js";
+export * from "./voting-quorum.js";