@optimystic/db-p2p 0.13.4 → 0.14.0

package/dist/src/matchmaking/seeker-walk-client.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Matchmaking — seeker walk client (db-p2p, drives the hang-out-vs-continue walk over the substrate).
+ *
+ * `docs/matchmaking.md` §Hang-out vs. continue. This is the RPC orchestration on top of the pure
+ * db-core {@link decide} engine: starting at `d_max`, it registers the seeker, issues `QueryV1`,
+ * re-validates and dedupes returned providers, and on each `Accepted` reply asks {@link decide} whether
+ * to finish, hang out (renew + requery on the `requery_interval_ms` poll cadence), or escalate (withdraw
+ * + re-register one tier toward the root). At `d = 0` there is nowhere left to walk, so it hangs out for
+ * the remaining patience and returns whatever matched (possibly `< wantCount`).
+ *
+ * Patience is a single budget that **drains across hops** (`docs/matchmaking.md` §Patience budgeting):
+ * a wall-clock deadline is fixed at the start, so every walked tier and every hang-out poll consumes
+ * the same `patienceMs` — escalation makes the next tier's hang-out progressively less attractive, which
+ * is correct since the root is terminal.
+ *
+ * The transport, clock, sleep, and per-entry verifier are all injected, so the walk unit-tests without a
+ * live libp2p stack (mock-tier e2e is a documented follow-on). This client implements the **poll path**
+ * only; the arrival-push path (`pushOnArrival`) is a separate slice.
+ *
+ * Edge cases encoded here (`docs/matchmaking.md` §Edge cases — the rest live in {@link decide}):
+ * - **`topicTraffic` absent (case 1):** the cohort is treated as zero-rate; the seeker issues one query
+ *   (immediate-match) and walks one tier toward the root **without** hanging out.
+ * - **Stale `arrivalsPerMin = 0` after an epoch change (case 2):** never withdraw on a single zero
+ *   reading — the immediate `QueryV1` runs first; a cohort that actually holds `>= wantCount` providers
+ *   resolves to `done`, and only a query that also yields below threshold escalates.
+ * - **`UnwillingCohort`/`UnwillingMember` (case 3):** the hang-out decision is never entered (no
+ *   `Accepted`); the walk terminates with whatever matched and standard substrate back-off applies.
+ */
+import { type CapabilityFilter, type EntrySigVerifier, type HangOutConfig, type ProviderEntryV1, type QueryReplyV1 } from "@optimystic/db-core";
+/** A seeker register/probe reply at a tree tier (the matchmaking-relevant subset of `RegisterReplyV1`). */
+export interface SeekerProbeReply {
+    readonly result: "accepted" | "no_state" | "promoted" | "unwilling_member" | "unwilling_cohort";
+    /** Present on `accepted` and `promoted` (the substrate's barometer); absent triggers edge case 1. */
+    readonly topicTraffic?: QueryReplyV1["topicTraffic"];
+    /** Present on `promoted` — the tier to descend to. */
+    readonly targetTier?: number;
+}
+/** The substrate seam the walk drives: register/query/renew/withdraw against a tree tier. */
+export interface SeekerWalkTransport {
+    /** Register (or re-register) the seeker at tree tier `treeTier`; resolves the probe reply. */
+    register(treeTier: number): Promise<SeekerProbeReply>;
+    /** Issue a `QueryV1` against the cohort the seeker is currently registered with. */
+    query(treeTier: number): Promise<QueryReplyV1>;
+    /** Renew the live seeker registration (hang-out keep-alive via TTL renewal). */
+    renew(): Promise<void>;
+    /** Withdraw the seeker registration before escalating (polite `RenewV1` TTL = 0; optional). */
+    withdraw(): Promise<void>;
+}
+/** Construction inputs for {@link SeekerWalkClient}. */
+export interface SeekerWalkClientDeps {
+    readonly transport: SeekerWalkTransport;
+    /** The matchmaking topic id (used to re-validate each forwarded entry's `registrationSig`). */
+    readonly topicId: Uint8Array;
+    /** Providers the seeker needs. */
+    readonly wantCount: number;
+    /** The starting tree tier `d_max`. */
+    readonly dMax: number;
+    /** Total patience budget (ms); drains across hops + hang-out. */
+    readonly patienceMs: number;
+    /** Optional capability filter (re-applied seeker-side over the returned set). */
+    readonly filter?: CapabilityFilter;
+    /** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+    readonly verifyEntry: EntrySigVerifier;
+    /** Hang-out decision config. Default {@link DEFAULT_HANG_OUT_CONFIG}. */
+    readonly config?: HangOutConfig;
+    /** Assumed competing-seeker mean `wantCount`. Default {@link DEFAULT_MEAN_WANT_COUNT}. */
+    readonly meanWantCount?: number;
+    /** Starting `filterAcceptRatio` (refined per walk). Default {@link FILTER_ACCEPT_RATIO_INITIAL}. */
+    readonly filterAcceptRatioInitial?: number;
+    /** Wall clock (unix ms); injectable for tests. Default `Date.now`. */
+    readonly clock?: () => number;
+    /** Sleep for the requery cadence; injectable for tests. Default a real timer. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** The result of a completed walk. */
+export interface SeekerWalkResult {
+    /** Matched, re-validated, deduped providers (up to whatever accumulated; may be `< wantCount`). */
+    readonly providers: ProviderEntryV1[];
+    /** Whether `wantCount` was met. */
+    readonly metWantCount: boolean;
+    /** The tier the walk terminated at. */
+    readonly terminalTier: number;
+    /** Total register hops issued (probes + escalations + descends). */
+    readonly hops: number;
+    /**
+     * Max `topicTraffic.childCohortCount` observed across every `Accepted` reply this walk saw. `> 0`
+     * means the topic has promoted (it is hot), so the single-cohort sample is unrepresentative — the
+     * public seeker session / voting `QuorumDiscovery` binding uses this to decide whether to escalate to
+     * the multi-cohort sweep (`docs/matchmaking.md` §Multi-cohort sweep).
+     */
+    readonly maxChildCohortCount: number;
+}
+/** Drives the seeker hang-out-vs-continue walk for one matchmaking topic. See the module header. */
+export declare class SeekerWalkClient {
+    private readonly transport;
+    private readonly topicId;
+    private readonly wantCount;
+    private readonly dMax;
+    private readonly patienceMs;
+    private readonly filter?;
+    private readonly verifyEntry;
+    private readonly config;
+    private readonly meanWantCount;
+    private readonly filterAcceptRatioInitial;
+    private readonly clock;
+    private readonly sleep;
+    /** Matched providers, deduped by `participantId` (a provider seen via two queries counts once). */
+    private readonly matched;
+    private ratioState;
+    private deadline;
+    private hops;
+    /** Max `childCohortCount` seen across `Accepted` replies — the hot-topic / sweep-escalation signal. */
+    private maxChildCohortCount;
+    constructor(deps: SeekerWalkClientDeps);
+    /** Run the walk from `d_max` toward the root; resolves the matched providers + termination info. */
+    run(): Promise<SeekerWalkResult>;
+    /** Remaining patience (ms); the wall-clock deadline drains uniformly across hops + hang-out. */
+    private remaining;
+    /** Filter, re-validate (`registrationSig`), and dedupe a query reply's providers into {@link matched}. */
+    private collect;
+    /** Evaluate one `Accepted` tier: immediate query, then {@link decide} → done / hangOut / escalate. */
+    private handleAccepted;
+    /** Keep the registration alive and re-query on the poll cadence until `wantCount` met or patience drains. */
+    private hangOut;
+    private finish;
+}
+//# sourceMappingURL=seeker-walk-client.d.ts.map

package/dist/src/matchmaking/seeker-walk-client.d.ts.map

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

package/dist/src/matchmaking/seeker-walk-client.js

@@ -0,0 +1,189 @@
+/**
+ * Matchmaking — seeker walk client (db-p2p, drives the hang-out-vs-continue walk over the substrate).
+ *
+ * `docs/matchmaking.md` §Hang-out vs. continue. This is the RPC orchestration on top of the pure
+ * db-core {@link decide} engine: starting at `d_max`, it registers the seeker, issues `QueryV1`,
+ * re-validates and dedupes returned providers, and on each `Accepted` reply asks {@link decide} whether
+ * to finish, hang out (renew + requery on the `requery_interval_ms` poll cadence), or escalate (withdraw
+ * + re-register one tier toward the root). At `d = 0` there is nowhere left to walk, so it hangs out for
+ * the remaining patience and returns whatever matched (possibly `< wantCount`).
+ *
+ * Patience is a single budget that **drains across hops** (`docs/matchmaking.md` §Patience budgeting):
+ * a wall-clock deadline is fixed at the start, so every walked tier and every hang-out poll consumes
+ * the same `patienceMs` — escalation makes the next tier's hang-out progressively less attractive, which
+ * is correct since the root is terminal.
+ *
+ * The transport, clock, sleep, and per-entry verifier are all injected, so the walk unit-tests without a
+ * live libp2p stack (mock-tier e2e is a documented follow-on). This client implements the **poll path**
+ * only; the arrival-push path (`pushOnArrival`) is a separate slice.
+ *
+ * Edge cases encoded here (`docs/matchmaking.md` §Edge cases — the rest live in {@link decide}):
+ * - **`topicTraffic` absent (case 1):** the cohort is treated as zero-rate; the seeker issues one query
+ *   (immediate-match) and walks one tier toward the root **without** hanging out.
+ * - **Stale `arrivalsPerMin = 0` after an epoch change (case 2):** never withdraw on a single zero
+ *   reading — the immediate `QueryV1` runs first; a cohort that actually holds `>= wantCount` providers
+ *   resolves to `done`, and only a query that also yields below threshold escalates.
+ * - **`UnwillingCohort`/`UnwillingMember` (case 3):** the hang-out decision is never entered (no
+ *   `Accepted`); the walk terminates with whatever matched and standard substrate back-off applies.
+ */
+import { decide, filterAcceptRatio, matchesFilter, newFilterAcceptRatioState, observeYield, verifyProviderEntry, DEFAULT_HANG_OUT_CONFIG, DEFAULT_MEAN_WANT_COUNT, FILTER_ACCEPT_RATIO_INITIAL, } from "@optimystic/db-core";
+/** Drives the seeker hang-out-vs-continue walk for one matchmaking topic. See the module header. */
+export class SeekerWalkClient {
+    transport;
+    topicId;
+    wantCount;
+    dMax;
+    patienceMs;
+    filter;
+    verifyEntry;
+    config;
+    meanWantCount;
+    filterAcceptRatioInitial;
+    clock;
+    sleep;
+    /** Matched providers, deduped by `participantId` (a provider seen via two queries counts once). */
+    matched = new Map();
+    ratioState = newFilterAcceptRatioState();
+    deadline = 0;
+    hops = 0;
+    /** Max `childCohortCount` seen across `Accepted` replies — the hot-topic / sweep-escalation signal. */
+    maxChildCohortCount = 0;
+    constructor(deps) {
+        this.transport = deps.transport;
+        this.topicId = deps.topicId;
+        this.wantCount = deps.wantCount;
+        this.dMax = deps.dMax;
+        this.patienceMs = deps.patienceMs;
+        this.filter = deps.filter;
+        this.verifyEntry = deps.verifyEntry;
+        this.config = deps.config ?? DEFAULT_HANG_OUT_CONFIG;
+        this.meanWantCount = deps.meanWantCount ?? DEFAULT_MEAN_WANT_COUNT;
+        this.filterAcceptRatioInitial = deps.filterAcceptRatioInitial ?? FILTER_ACCEPT_RATIO_INITIAL;
+        this.clock = deps.clock ?? (() => Date.now());
+        this.sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /** Run the walk from `d_max` toward the root; resolves the matched providers + termination info. */
+    async run() {
+        this.deadline = this.clock() + this.patienceMs;
+        let d = this.dMax;
+        while (true) {
+            this.hops++;
+            const reply = await this.transport.register(d);
+            switch (reply.result) {
+                case "no_state": {
+                    if (d <= 0) {
+                        return this.finish(d);
+                    }
+                    d -= 1;
+                    continue;
+                }
+                case "unwilling_member":
+                case "unwilling_cohort": {
+                    // Substrate-level refusal — never received Accepted, so hang-out is not entered (case 3).
+                    return this.finish(d);
+                }
+                case "promoted": {
+                    const target = reply.targetTier ?? d + 1;
+                    if (target <= d) {
+                        return this.finish(d);
+                    }
+                    d = target;
+                    continue;
+                }
+                case "accepted": {
+                    const outcome = await this.handleAccepted(d, reply.topicTraffic);
+                    if (outcome === "done" || outcome === "terminal") {
+                        return this.finish(d);
+                    }
+                    await this.transport.withdraw();
+                    d -= 1;
+                    continue;
+                }
+            }
+        }
+    }
+    /** Remaining patience (ms); the wall-clock deadline drains uniformly across hops + hang-out. */
+    remaining() {
+        return Math.max(0, this.deadline - this.clock());
+    }
+    /** Filter, re-validate (`registrationSig`), and dedupe a query reply's providers into {@link matched}. */
+    collect(reply) {
+        const returned = reply.providers ?? [];
+        let matchedThisQuery = 0;
+        for (const entry of returned) {
+            if (!matchesFilter(entry, this.filter)) {
+                continue;
+            }
+            if (!verifyProviderEntry(this.topicId, entry, this.verifyEntry)) {
+                continue;
+            }
+            matchedThisQuery++;
+            this.matched.set(entry.participantId, entry);
+        }
+        this.ratioState = observeYield(this.ratioState, matchedThisQuery, returned.length);
+    }
+    /** Evaluate one `Accepted` tier: immediate query, then {@link decide} → done / hangOut / escalate. */
+    async handleAccepted(d, traffic) {
+        // Record the hottest tier seen as soon as this Accepted reply's traffic is available — *before* the
+        // immediate-match/done short-circuit below, so the single-cohort-vs-sweep decision (public session /
+        // voting QuorumDiscovery binding) still sees a hot topic even when one cohort's query already met
+        // wantCount. Folding it only on the `decide` path would drop the signal for a small quorum that a
+        // single hot cohort satisfies, leaving the assembler with a prefix-biased sample it should sweep.
+        if (traffic !== undefined) {
+            this.maxChildCohortCount = Math.max(this.maxChildCohortCount, traffic.childCohortCount);
+        }
+        // Immediate-match check runs in every case — also satisfies edge case 2 (a stale arrivalsPerMin=0
+        // cohort that actually holds enough providers resolves here rather than escalating spuriously).
+        this.collect(await this.transport.query(d));
+        if (this.matched.size >= this.wantCount) {
+            return "done";
+        }
+        // Edge case 1: a reply without topicTraffic is treated as zero-rate — walk one tier toward the
+        // root without hanging out (no estimation against absent inputs).
+        if (traffic === undefined) {
+            return d <= 0 ? "terminal" : "escalate";
+        }
+        const decision = decide({
+            currentMatches: this.matched.size,
+            directParticipants: traffic.directParticipants,
+            arrivalsPerMin: traffic.arrivalsPerMin,
+            queriesPerMin: traffic.queriesPerMin,
+            childCohortCount: traffic.childCohortCount,
+            wantCount: this.wantCount,
+            patienceMsRemaining: this.remaining(),
+            filterAcceptRatio: filterAcceptRatio(this.ratioState, this.filterAcceptRatioInitial),
+            meanWantCount: this.meanWantCount,
+        }, this.config);
+        if (decision.action === "hangOut") {
+            await this.hangOut(d, decision.requeryIntervalMs);
+            if (this.matched.size >= this.wantCount) {
+                return "done";
+            }
+            return d <= 0 ? "terminal" : "escalate";
+        }
+        // escalate — but at the root there is nowhere to walk: hang out the remaining patience, then end.
+        if (d <= 0) {
+            await this.hangOut(d, this.config.requeryIntervalMs);
+            return "terminal";
+        }
+        return "escalate";
+    }
+    /** Keep the registration alive and re-query on the poll cadence until `wantCount` met or patience drains. */
+    async hangOut(d, requeryIntervalMs) {
+        while (this.remaining() > 0 && this.matched.size < this.wantCount) {
+            await this.sleep(Math.min(requeryIntervalMs, this.remaining()));
+            await this.transport.renew();
+            this.collect(await this.transport.query(d));
+        }
+    }
+    finish(terminalTier) {
+        return {
+            providers: [...this.matched.values()],
+            metWantCount: this.matched.size >= this.wantCount,
+            terminalTier,
+            hops: this.hops,
+            maxChildCohortCount: this.maxChildCohortCount,
+        };
+    }
+}
+//# sourceMappingURL=seeker-walk-client.js.map

package/dist/src/matchmaking/seeker-walk-client.js.map

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

package/dist/src/matchmaking/traffic-validation.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Matchmaking — seeker-side adversarial traffic-reporting bounds + reputation cross-check hooks (db-p2p).
+ *
+ * `docs/matchmaking.md` §Adversarial cohort traffic reporting. A `QueryReplyV1.topicTraffic` (and the
+ * registration reply's traffic) is signed by the cohort **primary's single member key, not a threshold
+ * signature**, because the response is advisory — so a malicious primary can over- or under-report. The
+ * doc proves the harm is bounded either way; this module makes those bounds explicit for the seeker walk
+ * and emits the cross-check signals the reputation subsystem consumes.
+ *
+ *  - **Over-reporting** (fake *hot* tier ⇒ seeker hangs out): bounded by the seeker's `patienceMs`. The
+ *    worst case is wasted patience plus the one `register → walk` hop after timeout — there is **no
+ *    spatial flood**, because the decision rule only ever walks *toward the root*, never speculatively
+ *    outward. {@link boundReportedTraffic} therefore caps any hang-out to the seeker's remaining
+ *    wall-clock patience ({@link TrafficBoundResult.capPatienceMs}).
+ *  - **Under-reporting** (fake *cold* tier ⇒ seeker escalates): bounded to **one extra hop per affected
+ *    tier**, terminating at the root where aggregated truth is hardest to fake
+ *    ({@link TrafficBoundResult.escalateAfterTiers}).
+ *  - **Cross-check via cohort gossip → reputation.** Other cohort members can detect a primary whose
+ *    reported rate diverges from the gossip-derived view. Detection *routing* is the reputation
+ *    subsystem's job (out of scope to implement); this module provides the **emission points**
+ *    ({@link TrafficCrossCheckSignal}) and a thin bridge ({@link reportTrafficCrossCheck}) into the
+ *    existing {@link IPeerReputation}. It scores nothing itself — the reputation subsystem owns the
+ *    aggregation/decay policy that turns a stream of advisory signals into an actual penalty.
+ *
+ * **GROUNDING (matchmaking.md §Adversarial traffic reporting):** no threshold signature is added per
+ * `QueryReplyV1` — the single-member signature stands; the bounded worst-case here does not justify the
+ * per-reply threshold cost. This module enforces the bounds purely seeker-side instead.
+ */
+import { type QueryReplyV1 } from "@optimystic/db-core";
+import { type IPeerReputation } from "../reputation/index.js";
+/**
+ * The seeker's running walk state at the moment a reply lands — enough to bound the reply's reported
+ * traffic and attribute a cross-check signal. The seeker walk client (or the public seeker session)
+ * supplies it per reply.
+ */
+export interface SeekerWalkState {
+    /** Tree tier `d` the reply came from. */
+    readonly currentTier: number;
+    /** Starting tier `d_max` (the walk only descends from here toward `0`). */
+    readonly dMax: number;
+    /** Register hops issued so far (probes + escalations). Bounded by `d_max + 1` — the walk never loops. */
+    readonly tiersWalked: number;
+    /** Total patience budget for the task (ms). */
+    readonly patienceMs: number;
+    /** Patience left on the wall-clock deadline (ms) — the hang-out cap. */
+    readonly patienceRemainingMs: number;
+    /** Filter-matched providers the seeker's *own* immediate `QueryV1` at this tier actually returned. */
+    readonly observedMatches: number;
+    /** The reply's cohort primary peer id, for reputation attribution (absent → no attribution). */
+    readonly primaryId?: string;
+}
+/** Tunables for {@link boundReportedTraffic}. */
+export interface TrafficBoundConfig {
+    /**
+     * Upper bound on extra register hops a single under-reported tier may cost. The doc fixes this at
+     * **1** ("one extra hop per affected tier"); exposed for tests / future policy, not meant to change.
+     */
+    readonly maxExtraHopsPerTier: number;
+    /**
+     * Over-report plausibility ratio. When a reply claims `directParticipants` more than this multiple of
+     * the seeker's *own* query yield, the over-report is flagged *suspect* (a cross-check signal — never a
+     * hard reject; the patience cap already bounds the harm).
+     */
+    readonly overReportSuspectRatio: number;
+}
+/** The documented defaults (`maxExtraHopsPerTier = 1`; suspect ratio chosen to tolerate normal churn). */
+export declare const DEFAULT_TRAFFIC_BOUND_CONFIG: TrafficBoundConfig;
+/** The kind of divergence a {@link TrafficCrossCheckSignal} reports. */
+export type TrafficCrossCheckKind = "over-report-suspected" | "under-report-suspected";
+/**
+ * One advisory cross-check observation about a cohort primary's reported traffic. Emitted by
+ * {@link boundReportedTraffic}; consumed by the reputation subsystem (via {@link reportTrafficCrossCheck}
+ * or a custom sink). Carries the raw discrepancy so the reputation policy — not this module — decides
+ * whether it warrants a penalty.
+ */
+export interface TrafficCrossCheckSignal {
+    readonly kind: TrafficCrossCheckKind;
+    /** The cohort primary peer id (the subject), if the walk state attributed one. */
+    readonly subjectId?: string;
+    /** The tier the reply came from. */
+    readonly tier: number;
+    /** `topicTraffic.directParticipants` as reported. */
+    readonly reportedDirectParticipants: number;
+    /** `topicTraffic.arrivalsPerMin` as reported. */
+    readonly reportedArrivalsPerMin: number;
+    /** The seeker's own immediate-query yield, which the report is cross-checked against. */
+    readonly observedMatches: number;
+}
+/** The outcome of {@link boundReportedTraffic}. */
+export interface TrafficBoundResult {
+    /** Whether the reported traffic is within plausible bounds (advisory; a flag, not an admission). */
+    readonly trusted: boolean;
+    /**
+     * Over-report bound: never hang out at this tier beyond the seeker's remaining wall-clock patience.
+     * Equals `max(0, patienceRemainingMs)` — so a fabricated hot tier wastes at most that, then the walk
+     * proceeds with its one register hop.
+     */
+    readonly capPatienceMs: number;
+    /** Under-report bound: at most this many extra register hops attributable to one tier (== config). */
+    readonly escalateAfterTiers: number;
+    /** Cross-check emission points (possibly empty). Forward to the reputation subsystem if desired. */
+    readonly reputationSignals: TrafficCrossCheckSignal[];
+}
+/**
+ * Bound the harm of a (possibly adversarial) `topicTraffic` report and emit cross-check signals. Pure —
+ * no I/O, no clock, no reputation scoring. The seeker walk consults `capPatienceMs` before hanging out
+ * and treats `escalateAfterTiers` as the per-tier hop ceiling; the bounds it returns hold *by
+ * construction* of the toward-root-only walk, so this function documents + asserts them rather than
+ * changing the walk topology.
+ */
+export declare function boundReportedTraffic(reply: QueryReplyV1, walkState: SeekerWalkState, cfg?: TrafficBoundConfig): TrafficBoundResult;
+/**
+ * The total hop budget the toward-root-only walk can consume under any sequence of (honest or
+ * adversarial) traffic reports: at most `maxExtraHopsPerTier` per tier from `d_max` down to the root,
+ * plus the terminal hop — i.e. `(dMax + 1) * maxExtraHopsPerTier`. Exposed so the walk and its tests can
+ * assert the under-report bound holds (the walk never exceeds it, because escalation is monotone toward
+ * `d = 0`).
+ */
+export declare function maxWalkHops(dMax: number, cfg?: TrafficBoundConfig): number;
+/**
+ * Integration hook: forward cross-check signals into the reputation subsystem. This is the **emission
+ * point only** — it records a `ProtocolViolation` against the reporting primary; the reputation
+ * subsystem's own weighting, decay, and deprioritize/ban thresholds (`PeerReputationService`) decide
+ * whether an accumulation of these advisory signals actually penalizes the peer. Signals without an
+ * attributed `subjectId` are skipped.
+ */
+export declare function reportTrafficCrossCheck(reputation: IPeerReputation, signals: readonly TrafficCrossCheckSignal[]): void;
+//# sourceMappingURL=traffic-validation.d.ts.map

package/dist/src/matchmaking/traffic-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traffic-validation.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/traffic-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yGAAyG;IACzG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,sGAAsG;IACtG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACxC;AAED,0GAA0G;AAC1G,eAAO,MAAM,4BAA4B,EAAE,kBAG1C,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,GAAG,wBAAwB,CAAC;AAEvF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,iDAAiD;IACjD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IAClC,oGAAoG;IACpG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sGAAsG;IACtG,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,oGAAoG;IACpG,QAAQ,CAAC,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,eAAe,EAC1B,GAAG,GAAE,kBAAiD,GACpD,kBAAkB,CA4BpB;AAgBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,kBAAiD,GAAG,MAAM,CAExG;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,uBAAuB,EAAE,GAAG,IAAI,CAOtH"}

package/dist/src/matchmaking/traffic-validation.js

@@ -0,0 +1,105 @@
+/**
+ * Matchmaking — seeker-side adversarial traffic-reporting bounds + reputation cross-check hooks (db-p2p).
+ *
+ * `docs/matchmaking.md` §Adversarial cohort traffic reporting. A `QueryReplyV1.topicTraffic` (and the
+ * registration reply's traffic) is signed by the cohort **primary's single member key, not a threshold
+ * signature**, because the response is advisory — so a malicious primary can over- or under-report. The
+ * doc proves the harm is bounded either way; this module makes those bounds explicit for the seeker walk
+ * and emits the cross-check signals the reputation subsystem consumes.
+ *
+ *  - **Over-reporting** (fake *hot* tier ⇒ seeker hangs out): bounded by the seeker's `patienceMs`. The
+ *    worst case is wasted patience plus the one `register → walk` hop after timeout — there is **no
+ *    spatial flood**, because the decision rule only ever walks *toward the root*, never speculatively
+ *    outward. {@link boundReportedTraffic} therefore caps any hang-out to the seeker's remaining
+ *    wall-clock patience ({@link TrafficBoundResult.capPatienceMs}).
+ *  - **Under-reporting** (fake *cold* tier ⇒ seeker escalates): bounded to **one extra hop per affected
+ *    tier**, terminating at the root where aggregated truth is hardest to fake
+ *    ({@link TrafficBoundResult.escalateAfterTiers}).
+ *  - **Cross-check via cohort gossip → reputation.** Other cohort members can detect a primary whose
+ *    reported rate diverges from the gossip-derived view. Detection *routing* is the reputation
+ *    subsystem's job (out of scope to implement); this module provides the **emission points**
+ *    ({@link TrafficCrossCheckSignal}) and a thin bridge ({@link reportTrafficCrossCheck}) into the
+ *    existing {@link IPeerReputation}. It scores nothing itself — the reputation subsystem owns the
+ *    aggregation/decay policy that turns a stream of advisory signals into an actual penalty.
+ *
+ * **GROUNDING (matchmaking.md §Adversarial traffic reporting):** no threshold signature is added per
+ * `QueryReplyV1` — the single-member signature stands; the bounded worst-case here does not justify the
+ * per-reply threshold cost. This module enforces the bounds purely seeker-side instead.
+ */
+import { PenaltyReason } from "../reputation/index.js";
+/** The documented defaults (`maxExtraHopsPerTier = 1`; suspect ratio chosen to tolerate normal churn). */
+export const DEFAULT_TRAFFIC_BOUND_CONFIG = {
+    maxExtraHopsPerTier: 1,
+    overReportSuspectRatio: 8,
+};
+/**
+ * Bound the harm of a (possibly adversarial) `topicTraffic` report and emit cross-check signals. Pure —
+ * no I/O, no clock, no reputation scoring. The seeker walk consults `capPatienceMs` before hanging out
+ * and treats `escalateAfterTiers` as the per-tier hop ceiling; the bounds it returns hold *by
+ * construction* of the toward-root-only walk, so this function documents + asserts them rather than
+ * changing the walk topology.
+ */
+export function boundReportedTraffic(reply, walkState, cfg = DEFAULT_TRAFFIC_BOUND_CONFIG) {
+    const traffic = reply.topicTraffic;
+    const signals = [];
+    // Over-report: a primary advertising a hot tier (many directParticipants) whose own query yields far
+    // fewer matches is suspect. Harm is bounded regardless — the patience cap below means a fabricated hot
+    // tier can only waste the seeker's remaining patience before it walks on (no spatial flood, since the
+    // walk only steps toward the root).
+    const overReportSuspect = traffic.directParticipants > cfg.overReportSuspectRatio * Math.max(walkState.observedMatches, 1);
+    if (overReportSuspect) {
+        signals.push(crossCheckSignal("over-report-suspected", traffic, walkState));
+    }
+    // Under-report: a primary claiming a cold tier (zero arrivals) while the seeker's own query yields
+    // matches is suspect. Either way the escalation costs at most one extra hop for this tier and
+    // terminates at the root.
+    const underReportSuspect = traffic.arrivalsPerMin === 0 && walkState.observedMatches > 0;
+    if (underReportSuspect) {
+        signals.push(crossCheckSignal("under-report-suspected", traffic, walkState));
+    }
+    return {
+        trusted: !overReportSuspect && !underReportSuspect,
+        capPatienceMs: Math.max(0, walkState.patienceRemainingMs),
+        escalateAfterTiers: cfg.maxExtraHopsPerTier,
+        reputationSignals: signals,
+    };
+}
+function crossCheckSignal(kind, traffic, walkState) {
+    const signal = {
+        kind,
+        tier: walkState.currentTier,
+        reportedDirectParticipants: traffic.directParticipants,
+        reportedArrivalsPerMin: traffic.arrivalsPerMin,
+        observedMatches: walkState.observedMatches,
+    };
+    if (walkState.primaryId !== undefined) {
+        signal.subjectId = walkState.primaryId;
+    }
+    return signal;
+}
+/**
+ * The total hop budget the toward-root-only walk can consume under any sequence of (honest or
+ * adversarial) traffic reports: at most `maxExtraHopsPerTier` per tier from `d_max` down to the root,
+ * plus the terminal hop — i.e. `(dMax + 1) * maxExtraHopsPerTier`. Exposed so the walk and its tests can
+ * assert the under-report bound holds (the walk never exceeds it, because escalation is monotone toward
+ * `d = 0`).
+ */
+export function maxWalkHops(dMax, cfg = DEFAULT_TRAFFIC_BOUND_CONFIG) {
+    return Math.max(0, dMax + 1) * cfg.maxExtraHopsPerTier;
+}
+/**
+ * Integration hook: forward cross-check signals into the reputation subsystem. This is the **emission
+ * point only** — it records a `ProtocolViolation` against the reporting primary; the reputation
+ * subsystem's own weighting, decay, and deprioritize/ban thresholds (`PeerReputationService`) decide
+ * whether an accumulation of these advisory signals actually penalizes the peer. Signals without an
+ * attributed `subjectId` are skipped.
+ */
+export function reportTrafficCrossCheck(reputation, signals) {
+    for (const signal of signals) {
+        if (signal.subjectId === undefined) {
+            continue;
+        }
+        reputation.reportPeer(signal.subjectId, PenaltyReason.ProtocolViolation, `matchmaking:${signal.kind}`);
+    }
+}
+//# sourceMappingURL=traffic-validation.js.map

package/dist/src/matchmaking/traffic-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traffic-validation.js","sourceRoot":"","sources":["../../../src/matchmaking/traffic-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,aAAa,EAAwB,MAAM,wBAAwB,CAAC;AAuC7E,0GAA0G;AAC1G,MAAM,CAAC,MAAM,4BAA4B,GAAuB;IAC/D,mBAAmB,EAAE,CAAC;IACtB,sBAAsB,EAAE,CAAC;CACzB,CAAC;AAyCF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CACnC,KAAmB,EACnB,SAA0B,EAC1B,MAA0B,4BAA4B;IAEtD,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC;IACnC,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,qGAAqG;IACrG,uGAAuG;IACvG,sGAAsG;IACtG,oCAAoC;IACpC,MAAM,iBAAiB,GACtB,OAAO,CAAC,kBAAkB,GAAG,GAAG,CAAC,sBAAsB,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;IAClG,IAAI,iBAAiB,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,uBAAuB,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,mGAAmG;IACnG,8FAA8F;IAC9F,0BAA0B;IAC1B,MAAM,kBAAkB,GAAG,OAAO,CAAC,cAAc,KAAK,CAAC,IAAI,SAAS,CAAC,eAAe,GAAG,CAAC,CAAC;IACzF,IAAI,kBAAkB,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,wBAAwB,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACN,OAAO,EAAE,CAAC,iBAAiB,IAAI,CAAC,kBAAkB;QAClD,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,mBAAmB,CAAC;QACzD,kBAAkB,EAAE,GAAG,CAAC,mBAAmB;QAC3C,iBAAiB,EAAE,OAAO;KAC1B,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAA2B,EAAE,OAAqC,EAAE,SAA0B;IACvH,MAAM,MAAM,GAA4B;QACvC,IAAI;QACJ,IAAI,EAAE,SAAS,CAAC,WAAW;QAC3B,0BAA0B,EAAE,OAAO,CAAC,kBAAkB;QACtD,sBAAsB,EAAE,OAAO,CAAC,cAAc;QAC9C,eAAe,EAAE,SAAS,CAAC,eAAe;KAC1C,CAAC;IACF,IAAI,SAAS,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACtC,MAAgC,CAAC,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC;IACnE,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAA0B,4BAA4B;IAC/F,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,mBAAmB,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAA2B,EAAE,OAA2C;IAC/G,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACpC,SAAS;QACV,CAAC;QACD,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,iBAAiB,EAAE,eAAe,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACxG,CAAC;AACF,CAAC"}

package/dist/src/network/network-manager-service.d.ts

@@ -59,9 +59,11 @@ export declare class NetworkManagerService implements Startable {
     getRebalanceMonitor(): RebalanceMonitor | undefined;
     /**
      * Initialize the spread-on-churn monitor. Call after libp2p, FRET are available.
-     * Caller provides repo and peerNetwork (not held by NetworkManagerService directly).
+     * Caller provides repo and peerNetwork (not held by NetworkManagerService directly),
+     * plus the node's protocolPrefix (/optimystic/<networkName>) so churn pushes dial the
+     * same block-transfer protocol the node registers its handler under.
      */
-    initSpreadOnChurnMonitor(partitionDetector: PartitionDetector, repo: SpreadOnChurnDeps['repo'], peerNetwork: SpreadOnChurnDeps['peerNetwork'], clusterSize: number, config?: Partial<SpreadOnChurnConfig>): SpreadOnChurnMonitor;
+    initSpreadOnChurnMonitor(partitionDetector: PartitionDetector, repo: SpreadOnChurnDeps['repo'], peerNetwork: SpreadOnChurnDeps['peerNetwork'], clusterSize: number, protocolPrefix: string, config?: Partial<SpreadOnChurnConfig>): SpreadOnChurnMonitor;
     getSpreadOnChurnMonitor(): SpreadOnChurnMonitor | undefined;
     private getLibp2p;
     private getFret;

package/dist/src/network/network-manager-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-manager-service.d.ts","sourceRoot":"","sources":["../../../src/network/network-manager-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"network-manager-service.d.ts","sourceRoot":"","sources":["../../../src/network/network-manager-service.ts"],"names":[],"mappings":"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"}

package/dist/src/network/network-manager-service.js

@@ -54,15 +54,21 @@ export class NetworkManagerService {
     }
     /**
      * Initialize the spread-on-churn monitor. Call after libp2p, FRET are available.
-     * Caller provides repo and peerNetwork (not held by NetworkManagerService directly).
+     * Caller provides repo and peerNetwork (not held by NetworkManagerService directly),
+     * plus the node's protocolPrefix (/optimystic/<networkName>) so churn pushes dial the
+     * same block-transfer protocol the node registers its handler under.
      */
-    initSpreadOnChurnMonitor(partitionDetector, repo, peerNetwork, clusterSize, config) {
+    initSpreadOnChurnMonitor(partitionDetector, repo, peerNetwork, clusterSize, protocolPrefix, config) {
         const libp2p = this.getLibp2p();
         const fret = this.getFret();
         if (!libp2p || !fret) {
             throw new Error('Cannot init SpreadOnChurnMonitor: libp2p or FRET not available');
         }
-        this.spreadOnChurnMonitor = new SpreadOnChurnMonitor({ libp2p, fret, partitionDetector, repo, peerNetwork, clusterSize }, config);
+        // protocolPrefix MUST flow into SpreadOnChurnDeps: performSpread builds its
+        // BlockTransferClient with it, and the receiving node registers the block-transfer
+        // handler under /optimystic/<networkName>. A missing/empty prefix dials the wrong
+        // protocol and every churn push fails to connect.
+        this.spreadOnChurnMonitor = new SpreadOnChurnMonitor({ libp2p, fret, partitionDetector, repo, peerNetwork, clusterSize, protocolPrefix }, config);
         return this.spreadOnChurnMonitor;
     }
     getSpreadOnChurnMonitor() {