@optimystic/db-core 0.13.5 → 0.14.1

package/dist/src/log/struct.d.ts

@@ -1,5 +1,5 @@
-import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev } from "../index.js";
-/** A log entry - either an action or a checkpoint */
+import type { BlockId, CollectionId, ActionContext, ActionId, ActionRev, ReadDependency } from "../index.js";
+/** A log entry - an action, a checkpoint, or an invalidation */
 export type LogEntry<TAction> = {
     /** Linux timestamp of the entry */
     readonly timestamp: number;
@@ -7,6 +7,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 */
 export type ActionEntry<TAction> = {
@@ -18,6 +20,124 @@ export type ActionEntry<TAction> = {
     blockIds: BlockId[];
     /** 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 */
 export type CheckpointEntry = {

package/dist/src/log/struct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"struct.d.ts","sourceRoot":"","sources":["../../../src/log/struct.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7F,qDAAqD;AACrD,MAAM,MAAM,QAAQ,CAAC,OAAO,IAAI;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACtC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI;IAClC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,gIAAgI;IAChI,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;CACxC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG;IAC7B;;;qEAGiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AACtC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,MAAM,MAAM,aAAa,CAAC,OAAO,IAAI;IACpC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CAChC,CAAC"}
+{"version":3,"file":"struct.d.ts","sourceRoot":"","sources":["../../../src/log/struct.ts"],"names":[],"mappings":"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"}

package/dist/src/log/struct.js.map

@@ -1 +1 @@
-{"version":3,"file":"struct.js","sourceRoot":"","sources":["../../../src/log/struct.ts"],"names":[],"mappings":"AAiCA,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC"}
+{"version":3,"file":"struct.js","sourceRoot":"","sources":["../../../src/log/struct.ts"],"names":[],"mappings":"AA6JA,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC"}

package/dist/src/matchmaking/capability-filter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function matchesFilter(p: FilterableProvider, f: CapabilityFilter | undefined): boolean;
+//# sourceMappingURL=capability-filter.d.ts.map

package/dist/src/matchmaking/capability-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-filter.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/capability-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAmB7F"}

package/dist/src/matchmaking/capability-filter.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/** True iff `p` satisfies `f` (`must` ⊆ caps, `mustNot` ∩ caps = ∅, `capacityBudget >= minBudget`). */
+export function matchesFilter(p, f) {
+    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;
+}
+//# sourceMappingURL=capability-filter.js.map

package/dist/src/matchmaking/capability-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-filter.js","sourceRoot":"","sources":["../../../src/matchmaking/capability-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,uGAAuG;AACvG,MAAM,UAAU,aAAa,CAAC,CAAqB,EAAE,CAA+B;IACnF,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IACD,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;QACjE,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/src/matchmaking/config.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 declare const PROVIDER_TTL_CORE_MS = 90000;
+/** Provider registration TTL on an Edge node (ms). */
+export declare const PROVIDER_TTL_EDGE_MS = 60000;
+/** Seeker registration TTL (ms) — short, since seekers normally don't wait long. */
+export declare const SEEKER_TTL_MS = 10000;
+/** Documented seeker-TTL range (ms); `SEEKER_TTL_MS` sits inside it. */
+export declare const SEEKER_TTL_MIN_MS = 5000;
+export declare const SEEKER_TTL_MAX_MS = 15000;
+/** Max entries returned in a single `QueryV1` reply. */
+export declare const QUERY_LIMIT_MAX = 256;
+/** Grace window a seeker may keep querying after its TTL expires (ms). */
+export declare const SEEKER_RENEW_GRACE_MS = 5000;
+/** Root cohorts produce aggregate counts only when tree depth ≥ this. */
+export declare const AGGREGATE_COUNT_MINIMUM_TIER = 1;
+/** Fallback `patienceMs` when a caller does not specify it per-task (ms). */
+export declare const PATIENCE_DEFAULT_MS = 10000;
+/** Fraction of remaining patience spent at one tier before considering escalation (1.0 = spend it all here). */
+export declare const PATIENCE_PER_TIER_FRACTION = 1;
+/** Starting estimate for `filterAcceptRatio`, refined per walk from observed query yields. */
+export declare const FILTER_ACCEPT_RATIO_INITIAL = 1;
+/** Upper bound on the contention multiplier in the hang-out decision (simulator-validated global scalar). */
+export declare const CONTENTION_FACTOR_CAP = 4;
+/** Mean `wantCount` assumed for competing seekers in the contention estimate (small constant; simulator value). */
+export declare const MEAN_WANT_COUNT_DEFAULT = 3;
+/** How often a hanging-out seeker re-issues `QueryV1` on the non-push (poll) path (ms). */
+export declare const REQUERY_INTERVAL_MS = 1000;
+/** Window the seeker's primary batches fresh matchable arrivals before flushing one push (ms; arrival-push path). */
+export declare const PUSH_COALESCE_MS = 250;
+/** Sparse fallback `QueryV1` cadence for a push-aware hanging-out seeker (ms; arrival-push path). */
+export declare const PUSH_SAFETY_POLL_MS = 5000;
+/**
+ * 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 declare const DEFAULT_HANG_OUT_CONFIG: HangOutConfig;
+/** 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 declare const DEFAULT_MATCHMAKING_CONFIG: MatchmakingConfig;
+/**
+ * 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 declare function providerTtlForProfile(profile: NodeProfile, config?: MatchmakingConfig): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/matchmaking/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,wDAAwD;AACxD,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAI9C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,gHAAgH;AAChH,eAAO,MAAM,0BAA0B,IAAM,CAAC;AAC9C,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,IAAM,CAAC;AAC/C,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,IAAM,CAAC;AACzC,mHAAmH;AACnH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,qHAAqH;AACrH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,aAGrC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC3C;AAED,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,EAAE,iBAOxC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,iBAA8C,GAAG,MAAM,CAE1H"}

package/dist/src/matchmaking/config.js

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+/** 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 default hang-out decision config (simulator-validated). */
+export const DEFAULT_HANG_OUT_CONFIG = {
+    contentionFactorCap: CONTENTION_FACTOR_CAP,
+    requeryIntervalMs: REQUERY_INTERVAL_MS,
+};
+/** The default matchmaking config (this ticket's slice). */
+export const DEFAULT_MATCHMAKING_CONFIG = {
+    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, config = DEFAULT_MATCHMAKING_CONFIG) {
+    return profile.kind === "edge" ? config.providerTtlEdgeMs : config.providerTtlCoreMs;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/matchmaking/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/matchmaking/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,qDAAqD;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,wDAAwD;AACxD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AACnC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAC3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,kGAAkG;AAElG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,gHAAgH;AAChH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAC9C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,6GAA6G;AAC7G,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,mHAAmH;AACnH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,qHAAqH;AACrH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qGAAqG;AACrG,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAczC,kEAAkE;AAClE,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACrD,mBAAmB,EAAE,qBAAqB;IAC1C,iBAAiB,EAAE,mBAAmB;CACtC,CAAC;AAYF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC5D,iBAAiB,EAAE,oBAAoB;IACvC,iBAAiB,EAAE,oBAAoB;IACvC,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,qBAAqB;IACzC,yBAAyB,EAAE,4BAA4B;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB,EAAE,SAA4B,0BAA0B;IACjH,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;AACtF,CAAC"}

package/dist/src/matchmaking/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/matchmaking/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}

package/dist/src/matchmaking/index.js

@@ -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";
+//# sourceMappingURL=index.js.map

package/dist/src/matchmaking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchmaking/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}

package/dist/src/matchmaking/multi-cohort-seeker.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Matchmaking — multi-cohort sweep (db-core, pure orchestration of the hot-topic representative sample).
+ *
+ * Per `docs/matchmaking.md` §Multi-cohort sweep. When a topic is hot enough that its providers live
+ * across many tier-`d >= 1` cohorts, a seeker that wants a *representative* cross-ring sample (rather
+ * than the prefix-biased single-cohort slice) does:
+ *
+ *  1. Registers at its natural tier as usual (the single-cohort {@link import("./seeker-walk.js").decide}
+ *     walk — not this module).
+ *  2. Queries the **root** cohort, which returns an {@link AggregateCountV1}: log-bucketed provider counts
+ *     per tier-1 prefix shard, **threshold-signed**. A cold root that fell through to `NoState` produces
+ *     no aggregate (the producer gates on tree depth — see `db-p2p/matchmaking/aggregate-counts.ts`).
+ *  3. Selects the high-population tier-1 shards ({@link selectShards}) and queries them directly, unioning
+ *     the returned providers into a deduped, re-validated set.
+ *
+ * This module is **pure**: the root-aggregate fetch, the per-shard query, and the optional threshold-sig
+ * verification are injected as a {@link MultiCohortSweepPorts} port (db-p2p binds them to the matchmaking
+ * query RPCs), exactly like the single-cohort walk splits pure `decide` (here) from the db-p2p walk
+ * client. The advisory trust model is preserved end-to-end: every shard entry is re-validated with
+ * {@link verifyProviderEntry} before it counts, so a lying shard primary buys nothing.
+ *
+ * The sweep costs more RPCs than the single-cohort sample and is reserved for representativeness-over-
+ * latency use cases (voting quorums, capability fairness audits); db-p2p binds it to the voting
+ * `QuorumDiscovery.sweep` port.
+ */
+import { type AggregateCountV1, type CapabilityFilter, type EntrySigVerifier, type ProviderEntryV1 } from "./wire.js";
+/** The tier whose prefix shards the sweep ranges over (`docs/matchmaking.md` §Wire formats — typically 1). */
+export declare const DEFAULT_SWEEP_TARGET_TIER = 1;
+/** Fan-out ceiling: never query more than this many shards in one sweep (bounds RPC cost). */
+export declare const DEFAULT_SWEEP_MAX_SHARDS = 16;
+/**
+ * Multiplier on `wantCount` when accumulating bucketed shard populations. `1` because {@link logBucketCount}
+ * already rounds counts *down* — the true population is `>=` the reported sum, so the selection already
+ * over-provisions without an extra factor.
+ */
+export declare const DEFAULT_SWEEP_OVERPROVISION = 1;
+/** One tier-1 prefix shard the sweep elected to query, with its (bucketed) reported population. */
+export interface ShardSelection {
+    /** Prefix slot `0..F-1` identifying the tier-1 cohort. */
+    readonly prefixSlot: number;
+    /** The tier whose shard this is (typically 1). */
+    readonly targetTier: number;
+    /** The shard's log-bucketed reported provider count (rounds down — see {@link logBucketCount}). */
+    readonly bucketedCount: number;
+}
+/** Inputs to {@link selectShards}. */
+export interface SelectShardsOptions {
+    /** Providers the seeker needs (drives how many shards are unioned). */
+    readonly wantCount: number;
+    /** Which `targetTier` buckets to consider. Default {@link DEFAULT_SWEEP_TARGET_TIER}. */
+    readonly targetTier?: number;
+    /** Fan-out ceiling. Default {@link DEFAULT_SWEEP_MAX_SHARDS}. */
+    readonly maxShards?: number;
+    /** Multiplier on `wantCount`. Default {@link DEFAULT_SWEEP_OVERPROVISION}. */
+    readonly overprovision?: number;
+}
+/**
+ * Choose which tier-1 shards to query from an {@link AggregateCountV1}: the highest-population shards
+ * first (ties broken by ascending `prefixSlot` for determinism), accumulating bucketed counts until they
+ * cover `wantCount * overprovision`, capped at `maxShards`. Empty shards (`count === 0`) are skipped.
+ * Pure and deterministic.
+ */
+export declare function selectShards(aggregate: AggregateCountV1, opts: SelectShardsOptions): ShardSelection[];
+/** Identifies one tier shard to query directly (db-p2p resolves it to `coord_d` and dials the cohort). */
+export interface SweepShardQuery {
+    readonly prefixSlot: number;
+    readonly targetTier: number;
+}
+/**
+ * The transport seam the sweep drives, injected by db-p2p. `fetchAggregate` queries the root cohort
+ * (resolving `undefined` when the root is cold / unpromoted and returns no {@link AggregateCountV1});
+ * `queryShard` queries one elected tier-1 cohort; `verifyAggregate` (optional) threshold-verifies the
+ * aggregate before its counts are trusted.
+ */
+export interface MultiCohortSweepPorts {
+    /** Query the root cohort for the aggregate; `undefined` when the root produced none (cold / unpromoted). */
+    fetchAggregate(): Promise<AggregateCountV1 | undefined>;
+    /** Threshold-verify the aggregate (db-p2p binds the cohort crypto). Omitted → trusted unconditionally. */
+    verifyAggregate?(aggregate: AggregateCountV1): boolean;
+    /** Query one elected shard; returns its advisory provider entries (the sweep re-validates each). */
+    queryShard(shard: SweepShardQuery): Promise<readonly ProviderEntryV1[]>;
+}
+/** Inputs to {@link runMultiCohortSweep}. */
+export interface MultiCohortSweepOptions {
+    /** The matchmaking topic id (used to re-validate each forwarded entry's `registrationSig`). */
+    readonly topicId: Uint8Array;
+    /** Providers the seeker needs (drives shard selection). */
+    readonly wantCount: number;
+    /** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+    readonly verifyEntry: EntrySigVerifier;
+    /** Optional capability filter, re-applied over every shard's returned set. */
+    readonly filter?: CapabilityFilter;
+    /** Which `targetTier` shards to range over. Default {@link DEFAULT_SWEEP_TARGET_TIER}. */
+    readonly targetTier?: number;
+    /** Fan-out ceiling. Default {@link DEFAULT_SWEEP_MAX_SHARDS}. */
+    readonly maxShards?: number;
+    /** Multiplier on `wantCount`. Default {@link DEFAULT_SWEEP_OVERPROVISION}. */
+    readonly overprovision?: number;
+    /**
+     * Patience budget (ms) for the whole sweep; drains across the shard fan-out. Omitted ⇒ unbounded
+     * (query every selected shard, today's behaviour). Mirrors the walk leg's budget.
+     */
+    readonly patienceMs?: number;
+    /** Wall clock (unix ms); injectable for tests. Default `Date.now`. Only consulted when `patienceMs` set. */
+    readonly clock?: () => number;
+}
+/** The assembled result of a multi-cohort sweep. */
+export interface MultiCohortSweepResult {
+    /** The unioned, filtered, `registrationSig`-re-validated providers, deduped by `participantId`. */
+    readonly providers: ProviderEntryV1[];
+    /** The shards selected from the aggregate (empty when no aggregate / untrusted). */
+    readonly selectedShards: ShardSelection[];
+    /** How many shards were actually queried (== `selectedShards.length` on success). */
+    readonly shardsQueried: number;
+    /** Whether the root produced an aggregate at all (`false` for a cold / unpromoted root). */
+    readonly aggregateAvailable: boolean;
+    /** Whether the aggregate's threshold signature verified (`false` when absent or invalid). */
+    readonly aggregateTrusted: boolean;
+}
+/**
+ * Run the multi-cohort sweep (`docs/matchmaking.md` §Multi-cohort sweep): fetch the root aggregate,
+ * threshold-verify it, select high-population shards, query each, and union the deduped + re-validated
+ * providers. A cold root (no aggregate) or an aggregate that fails verification yields an empty set so
+ * the caller falls back to the single-cohort sample. Each shard entry is filtered and
+ * `registrationSig`-re-validated before it counts — the cohort vouches only for "the set I held".
+ *
+ * When `opts.patienceMs` is supplied, a wall-clock deadline is fixed at entry and the shard fan-out
+ * stops as soon as the budget drains — mirroring the walk leg's patience model. This is
+ * "stop starting new shard queries": an in-flight `queryShard` call is not cancelled mid-flight.
+ * When `opts.patienceMs` is absent, every elected shard is queried (today's behaviour).
+ */
+export declare function runMultiCohortSweep(ports: MultiCohortSweepPorts, opts: MultiCohortSweepOptions): Promise<MultiCohortSweepResult>;
+//# sourceMappingURL=multi-cohort-seeker.d.ts.map

package/dist/src/matchmaking/multi-cohort-seeker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-cohort-seeker.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/multi-cohort-seeker.ts"],"names":[],"mappings":"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"}