@optimystic/db-core 0.13.4 → 0.14.0

package/dist/src/matchmaking/multi-cohort-seeker.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { matchesFilter } from "./capability-filter.js";
+import { verifyProviderEntry } from "./wire.js";
+/** The tier whose prefix shards the sweep ranges over (`docs/matchmaking.md` §Wire formats — typically 1). */
+export const DEFAULT_SWEEP_TARGET_TIER = 1;
+/** Fan-out ceiling: never query more than this many shards in one sweep (bounds RPC cost). */
+export 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 const DEFAULT_SWEEP_OVERPROVISION = 1;
+/**
+ * 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 function selectShards(aggregate, opts) {
+    const targetTier = opts.targetTier ?? DEFAULT_SWEEP_TARGET_TIER;
+    const maxShards = opts.maxShards ?? DEFAULT_SWEEP_MAX_SHARDS;
+    const overprovision = opts.overprovision ?? DEFAULT_SWEEP_OVERPROVISION;
+    const need = Math.max(1, Math.ceil(opts.wantCount * overprovision));
+    const ranked = aggregate.bucketCounts
+        .filter((b) => b.targetTier === targetTier && b.count > 0)
+        .sort((a, b) => b.count - a.count || a.prefixSlot - b.prefixSlot);
+    const selected = [];
+    let cumulative = 0;
+    for (const bucket of ranked) {
+        if (selected.length >= maxShards) {
+            break;
+        }
+        selected.push({ prefixSlot: bucket.prefixSlot, targetTier: bucket.targetTier, bucketedCount: bucket.count });
+        cumulative += bucket.count;
+        if (cumulative >= need) {
+            break;
+        }
+    }
+    return selected;
+}
+/** An empty result (no aggregate, or an aggregate that failed verification). */
+function emptyResult(aggregateAvailable, aggregateTrusted) {
+    return { providers: [], selectedShards: [], shardsQueried: 0, aggregateAvailable, aggregateTrusted };
+}
+/**
+ * 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 async function runMultiCohortSweep(ports, opts) {
+    // Budget: optional wall-clock deadline mirroring the walk leg. Only consulted when patienceMs is set.
+    const clock = opts.clock ?? (() => Date.now());
+    const deadline = opts.patienceMs !== undefined ? clock() + opts.patienceMs : undefined;
+    const remaining = () => (deadline !== undefined ? Math.max(0, deadline - clock()) : Infinity);
+    // If the budget is already drained on entry, skip even the aggregate RPC — the walk already consumed
+    // all patience and there is no point spending an RPC on an aggregate we have no time to act on.
+    if (deadline !== undefined && remaining() <= 0) {
+        return emptyResult(false, false);
+    }
+    const aggregate = await ports.fetchAggregate();
+    if (aggregate === undefined) {
+        return emptyResult(false, false);
+    }
+    // `aggregateTrusted` is asserted only when a verifier actually ran and passed. With no verifier injected
+    // the sweep still proceeds — every shard entry is `registrationSig`-re-validated below, so a forged
+    // aggregate can at worst mis-steer shard selection (wasted RPCs / a thinner sample), never inject
+    // providers — but the flag stays honest rather than claiming a trust that was never established.
+    const aggregateTrusted = ports.verifyAggregate !== undefined;
+    if (ports.verifyAggregate !== undefined && !ports.verifyAggregate(aggregate)) {
+        return emptyResult(true, false);
+    }
+    const selectShardOpts = { wantCount: opts.wantCount };
+    if (opts.targetTier !== undefined) {
+        selectShardOpts.targetTier = opts.targetTier;
+    }
+    if (opts.maxShards !== undefined) {
+        selectShardOpts.maxShards = opts.maxShards;
+    }
+    if (opts.overprovision !== undefined) {
+        selectShardOpts.overprovision = opts.overprovision;
+    }
+    const selected = selectShards(aggregate, selectShardOpts);
+    const matched = new Map();
+    let shardsQueried = 0;
+    for (const shard of selected) {
+        // Stop starting new shard queries once the budget has drained.
+        if (remaining() <= 0) {
+            break;
+        }
+        const entries = await ports.queryShard({ prefixSlot: shard.prefixSlot, targetTier: shard.targetTier });
+        shardsQueried++;
+        for (const entry of entries) {
+            if (!matchesFilter(entry, opts.filter)) {
+                continue;
+            }
+            if (!verifyProviderEntry(opts.topicId, entry, opts.verifyEntry)) {
+                continue;
+            }
+            matched.set(entry.participantId, entry);
+        }
+    }
+    return {
+        providers: [...matched.values()],
+        selectedShards: selected,
+        shardsQueried,
+        aggregateAvailable: true,
+        aggregateTrusted,
+    };
+}
+//# sourceMappingURL=multi-cohort-seeker.js.map

package/dist/src/matchmaking/multi-cohort-seeker.js.map

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

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

@@ -0,0 +1,70 @@
+/**
+ * Matchmaking — provider decision/state (db-core, transport-agnostic).
+ *
+ * A {@link MatchmakingProvider} owns the live provider state for one topic: its capability tags, its
+ * current `capacityBudget`, and a correlation id (registration identity; not bound into the
+ * matchmaking signature — see {@link providerSigningPayload} option (b)). It builds the
+ * signed {@link ProviderAppPayloadV1} (and the opaque bytes for the cohort-topic
+ * `RegisterV1.appPayload` slot) that the db-p2p `provider-manager` registers at cohort-topic tier
+ * **T2** (`docs/matchmaking.md` §Provider registration).
+ *
+ * It is crypto-free: signing is an injected callback (db-p2p supplies the libp2p peer key), matching
+ * the cohort-topic {@link import("../cohort-topic/service.js").ParticipantSigner} pattern.
+ *
+ * Self-throttling (`docs/matchmaking.md` §Provider self-throttling) is expressed here as state:
+ * - **Signal full** — {@link MatchmakingProvider.signalFull} sets `capacityBudget = 0`; the provider
+ *   stays listed as "available but at capacity". The manager re-registers to push the new payload
+ *   (the cohort-topic `RenewV1` carries no `appPayload`, so a capacity change is a re-register, not a
+ *   ping — see the implement handoff).
+ * - **Withdraw** — {@link MatchmakingProvider.markWithdrawn} records intent; the manager stops
+ *   renewing so the record ages out by TTL. Withdrawal is an **optimization, not a correctness
+ *   requirement** (§Provider self-throttling, GROUNDING resolution): a non-withdrawn registration is
+ *   bounded by TTL eviction.
+ */
+import { type ProviderAppPayloadV1 } from "./wire.js";
+/** Construction inputs for a {@link MatchmakingProvider}. */
+export interface MatchmakingProviderOptions {
+    /** The matchmaking topic this provider serves (from {@link import("./topic-anchor.js").MatchTopicAnchor}). */
+    readonly topicId: Uint8Array;
+    /** Application-defined capability tags. */
+    readonly capabilities: readonly string[];
+    /** Initial concurrent-task budget (integer `>= 0`). */
+    readonly capacityBudget: number;
+    /** Multiaddr or PeerId-based callback. */
+    readonly contactHint: string;
+    /** Optional soft expiry hint (unix ms). */
+    readonly serviceUntil?: number;
+    /** Sign the canonical registration image; resolves the base64url signature. */
+    readonly sign: (payload: Uint8Array) => Promise<string>;
+    /** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
+    readonly correlationId?: Uint8Array;
+    /** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
+    readonly randomBytes?: (n: number) => Uint8Array;
+}
+/** Live provider state + signed-payload builder for one matchmaking topic. */
+export declare class MatchmakingProvider {
+    readonly topicId: Uint8Array;
+    readonly correlationId: Uint8Array;
+    private readonly capabilities;
+    private readonly contactHint;
+    private readonly serviceUntil?;
+    private readonly sign;
+    private capacity;
+    private withdrawnFlag;
+    constructor(options: MatchmakingProviderOptions);
+    /** Current concurrent-task budget; `0` means "listed but full". */
+    get capacityBudget(): number;
+    /** True once {@link markWithdrawn} has been called (the manager should stop renewing). */
+    get withdrawn(): boolean;
+    /** Set the live budget (integer `>= 0`). The next built payload reflects it. */
+    setCapacity(budget: number): void;
+    /** Signal "available but at capacity" by setting `capacityBudget = 0` (§Provider self-throttling). */
+    signalFull(): void;
+    /** Record withdrawal intent; the manager stops renewing so the record TTL-expires (optimization). */
+    markWithdrawn(): void;
+    /** Build the signed {@link ProviderAppPayloadV1} reflecting the current capacity. */
+    buildAppPayload(): Promise<ProviderAppPayloadV1>;
+    /** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
+    appPayloadBytes(): Promise<Uint8Array>;
+}
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAA0B,KAAK,oBAAoB,EAA4B,MAAM,WAAW,CAAC;AAExG,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IAC1C,8GAA8G;IAC9G,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;CACjD;AAED,8EAA8E;AAC9E,qBAAa,mBAAmB;IAC/B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2C;IAChE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAS;gBAElB,OAAO,EAAE,0BAA0B;IAW/C,mEAAmE;IACnE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,0FAA0F;IAC1F,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,gFAAgF;IAChF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIjC,sGAAsG;IACtG,UAAU,IAAI,IAAI;IAIlB,qGAAqG;IACrG,aAAa,IAAI,IAAI;IAIrB,qFAAqF;IAC/E,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAetD,gFAAgF;IAC1E,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;CAG5C"}

package/dist/src/matchmaking/provider.js

@@ -0,0 +1,93 @@
+/**
+ * Matchmaking — provider decision/state (db-core, transport-agnostic).
+ *
+ * A {@link MatchmakingProvider} owns the live provider state for one topic: its capability tags, its
+ * current `capacityBudget`, and a correlation id (registration identity; not bound into the
+ * matchmaking signature — see {@link providerSigningPayload} option (b)). It builds the
+ * signed {@link ProviderAppPayloadV1} (and the opaque bytes for the cohort-topic
+ * `RegisterV1.appPayload` slot) that the db-p2p `provider-manager` registers at cohort-topic tier
+ * **T2** (`docs/matchmaking.md` §Provider registration).
+ *
+ * It is crypto-free: signing is an injected callback (db-p2p supplies the libp2p peer key), matching
+ * the cohort-topic {@link import("../cohort-topic/service.js").ParticipantSigner} pattern.
+ *
+ * Self-throttling (`docs/matchmaking.md` §Provider self-throttling) is expressed here as state:
+ * - **Signal full** — {@link MatchmakingProvider.signalFull} sets `capacityBudget = 0`; the provider
+ *   stays listed as "available but at capacity". The manager re-registers to push the new payload
+ *   (the cohort-topic `RenewV1` carries no `appPayload`, so a capacity change is a re-register, not a
+ *   ping — see the implement handoff).
+ * - **Withdraw** — {@link MatchmakingProvider.markWithdrawn} records intent; the manager stops
+ *   renewing so the record ages out by TTL. Withdrawal is an **optimization, not a correctness
+ *   requirement** (§Provider self-throttling, GROUNDING resolution): a non-withdrawn registration is
+ *   bounded by TTL eviction.
+ */
+import { randomBytes } from "@noble/hashes/utils.js";
+import { providerSigningPayload, encodeProviderAppPayload } from "./wire.js";
+/** Live provider state + signed-payload builder for one matchmaking topic. */
+export class MatchmakingProvider {
+    topicId;
+    correlationId;
+    capabilities;
+    contactHint;
+    serviceUntil;
+    sign;
+    capacity;
+    withdrawnFlag = false;
+    constructor(options) {
+        this.topicId = options.topicId;
+        this.capabilities = [...options.capabilities];
+        this.contactHint = options.contactHint;
+        this.serviceUntil = options.serviceUntil;
+        this.sign = options.sign;
+        this.capacity = requireBudget(options.capacityBudget);
+        const rand = options.randomBytes ?? randomBytes;
+        this.correlationId = options.correlationId ?? rand(16);
+    }
+    /** Current concurrent-task budget; `0` means "listed but full". */
+    get capacityBudget() {
+        return this.capacity;
+    }
+    /** True once {@link markWithdrawn} has been called (the manager should stop renewing). */
+    get withdrawn() {
+        return this.withdrawnFlag;
+    }
+    /** Set the live budget (integer `>= 0`). The next built payload reflects it. */
+    setCapacity(budget) {
+        this.capacity = requireBudget(budget);
+    }
+    /** Signal "available but at capacity" by setting `capacityBudget = 0` (§Provider self-throttling). */
+    signalFull() {
+        this.capacity = 0;
+    }
+    /** Record withdrawal intent; the manager stops renewing so the record TTL-expires (optimization). */
+    markWithdrawn() {
+        this.withdrawnFlag = true;
+    }
+    /** Build the signed {@link ProviderAppPayloadV1} reflecting the current capacity. */
+    async buildAppPayload() {
+        const signature = await this.sign(providerSigningPayload(this.topicId, this.capabilities, this.capacity));
+        const payload = {
+            kind: "match-provider",
+            capabilities: [...this.capabilities],
+            capacityBudget: this.capacity,
+            contactHint: this.contactHint,
+            signature,
+        };
+        if (this.serviceUntil !== undefined) {
+            payload.serviceUntil = this.serviceUntil;
+        }
+        return payload;
+    }
+    /** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
+    async appPayloadBytes() {
+        return encodeProviderAppPayload(await this.buildAppPayload());
+    }
+}
+/** Validate a capacity budget is an integer `>= 0`. */
+function requireBudget(budget) {
+    if (!Number.isInteger(budget) || budget < 0) {
+        throw new RangeError(`matchmaking provider: capacityBudget must be an integer >= 0, got ${budget}`);
+    }
+    return budget;
+}
+//# sourceMappingURL=provider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/matchmaking/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAA6B,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAsBxG,8EAA8E;AAC9E,MAAM,OAAO,mBAAmB;IACtB,OAAO,CAAa;IACpB,aAAa,CAAa;IAClB,YAAY,CAAoB;IAChC,WAAW,CAAS;IACpB,YAAY,CAAU;IACtB,IAAI,CAA2C;IACxD,QAAQ,CAAS;IACjB,aAAa,GAAG,KAAK,CAAC;IAE9B,YAAY,OAAmC;QAC9C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,mEAAmE;IACnE,IAAI,cAAc;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED,0FAA0F;IAC1F,IAAI,SAAS;QACZ,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;IAED,gFAAgF;IAChF,WAAW,CAAC,MAAc;QACzB,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,sGAAsG;IACtG,UAAU;QACT,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,qGAAqG;IACrG,aAAa;QACZ,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,eAAe;QACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1G,MAAM,OAAO,GAAyB;YACrC,IAAI,EAAE,gBAAgB;YACtB,YAAY,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;YACpC,cAAc,EAAE,IAAI,CAAC,QAAQ;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS;SACT,CAAC;QACF,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC1C,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,eAAe;QACpB,OAAO,wBAAwB,CAAC,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IAC/D,CAAC;CACD;AAED,uDAAuD;AACvD,SAAS,aAAa,CAAC,MAAc;IACpC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAAC,qEAAqE,MAAM,EAAE,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/src/matchmaking/query-eval.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Matchmaking — pure `QueryV1` evaluation (db-core, transport-agnostic).
+ *
+ * The cohort-side query handler (`db-p2p/src/matchmaking/query-handler.ts`) decodes its local
+ * registration records into the {@link LocalProviderRegistration} / {@link LocalSeekerRegistration}
+ * shapes below and hands them here; this module performs the *advisory* selection that
+ * `docs/matchmaking.md` §Seeker query / §Capability filter specify:
+ *
+ * - Providers are filtered through {@link matchesFilter} (when `includeProviders`).
+ * - Each included set is truncated to `query.limit` (`<= query_limit_max`, enforced on decode in
+ *   `wire.ts`); {@link QueryEvalResult.truncated} is set when *any* included set had more matches than
+ *   `limit` allowed, so the seeker knows to re-query a sibling cohort.
+ * - The forwarded entries carry the provider/seeker's own `registrationSig` verbatim, so the seeker
+ *   re-validates each one (`verifyProviderEntry`) — the cohort vouches only for the *set it held*.
+ *
+ * Pure: no I/O, no clock, no crypto. The db-p2p handler attaches `topicTraffic` / `cohortEpoch` and
+ * the primary's reply signature.
+ */
+import type { ProviderAppPayloadV1, SeekerAppPayloadV1, ProviderEntryV1, SeekerEntryV1, QueryV1 } from "./wire.js";
+/** A decoded local provider registration held by the cohort, ready for {@link evaluateQuery}. */
+export interface LocalProviderRegistration {
+    /** The provider's peer-id string — the entry's `participantId` AND the `registrationSig` signer. */
+    readonly participantId: string;
+    /** Unix ms the registration first attached (forwarded verbatim for seeker FCFS ordering). */
+    readonly attachedAt: number;
+    /** The decoded, validated provider app payload (capabilities, budget, contact, signature). */
+    readonly payload: ProviderAppPayloadV1;
+}
+/** A decoded local seeker registration held by the cohort (collective-assembly discovery). */
+export interface LocalSeekerRegistration {
+    readonly participantId: string;
+    readonly attachedAt: number;
+    readonly payload: SeekerAppPayloadV1;
+}
+/** The selected entries for a {@link QueryReplyV1} body (the db-p2p handler signs + frames it). */
+export interface QueryEvalResult {
+    readonly providers?: ProviderEntryV1[];
+    readonly seekers?: SeekerEntryV1[];
+    /** `true` when an included set had more matches than `query.limit` allowed (re-query hint). */
+    readonly truncated: boolean;
+}
+/** Build a forwarded {@link ProviderEntryV1} from a local registration (signature forwarded verbatim). */
+export declare function providerEntryOf(reg: LocalProviderRegistration): ProviderEntryV1;
+/** Build a forwarded {@link SeekerEntryV1} from a local registration (signature forwarded verbatim). */
+export declare function seekerEntryOf(reg: LocalSeekerRegistration): SeekerEntryV1;
+/**
+ * Evaluate `query` against the cohort's locally-held registrations: filter providers, optionally include
+ * seekers, truncate each included set to `query.limit`. Inputs are returned in `attachedAt` order
+ * (oldest first) so truncation keeps the longest-waiting registrations — the FCFS bias the arrival-push
+ * fairness rule also uses (`docs/matchmaking.md` §Fairness).
+ */
+export declare function evaluateQuery(query: QueryV1, providers: readonly LocalProviderRegistration[], seekers: readonly LocalSeekerRegistration[]): QueryEvalResult;
+//# sourceMappingURL=query-eval.d.ts.map

package/dist/src/matchmaking/query-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-eval.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/query-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,eAAe,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnH,iGAAiG;AACjG,MAAM,WAAW,yBAAyB;IACzC,oGAAoG;IACpG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACvC;AAED,8FAA8F;AAC9F,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACrC;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IACnC,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC5B;AAED,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,GAAG,EAAE,yBAAyB,GAAG,eAAe,CAS/E;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,GAAG,EAAE,uBAAuB,GAAG,aAAa,CAQzE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,SAAS,yBAAyB,EAAE,EAC/C,OAAO,EAAE,SAAS,uBAAuB,EAAE,GACzC,eAAe,CAwBjB"}

package/dist/src/matchmaking/query-eval.js

@@ -0,0 +1,69 @@
+/**
+ * Matchmaking — pure `QueryV1` evaluation (db-core, transport-agnostic).
+ *
+ * The cohort-side query handler (`db-p2p/src/matchmaking/query-handler.ts`) decodes its local
+ * registration records into the {@link LocalProviderRegistration} / {@link LocalSeekerRegistration}
+ * shapes below and hands them here; this module performs the *advisory* selection that
+ * `docs/matchmaking.md` §Seeker query / §Capability filter specify:
+ *
+ * - Providers are filtered through {@link matchesFilter} (when `includeProviders`).
+ * - Each included set is truncated to `query.limit` (`<= query_limit_max`, enforced on decode in
+ *   `wire.ts`); {@link QueryEvalResult.truncated} is set when *any* included set had more matches than
+ *   `limit` allowed, so the seeker knows to re-query a sibling cohort.
+ * - The forwarded entries carry the provider/seeker's own `registrationSig` verbatim, so the seeker
+ *   re-validates each one (`verifyProviderEntry`) — the cohort vouches only for the *set it held*.
+ *
+ * Pure: no I/O, no clock, no crypto. The db-p2p handler attaches `topicTraffic` / `cohortEpoch` and
+ * the primary's reply signature.
+ */
+import { matchesFilter } from "./capability-filter.js";
+/** Build a forwarded {@link ProviderEntryV1} from a local registration (signature forwarded verbatim). */
+export function providerEntryOf(reg) {
+    return {
+        participantId: reg.participantId,
+        capabilities: [...reg.payload.capabilities],
+        capacityBudget: reg.payload.capacityBudget,
+        contactHint: reg.payload.contactHint,
+        attachedAt: reg.attachedAt,
+        registrationSig: reg.payload.signature,
+    };
+}
+/** Build a forwarded {@link SeekerEntryV1} from a local registration (signature forwarded verbatim). */
+export function seekerEntryOf(reg) {
+    return {
+        participantId: reg.participantId,
+        wantCount: reg.payload.wantCount,
+        contactHint: reg.payload.contactHint,
+        attachedAt: reg.attachedAt,
+        registrationSig: reg.payload.signature,
+    };
+}
+/**
+ * Evaluate `query` against the cohort's locally-held registrations: filter providers, optionally include
+ * seekers, truncate each included set to `query.limit`. Inputs are returned in `attachedAt` order
+ * (oldest first) so truncation keeps the longest-waiting registrations — the FCFS bias the arrival-push
+ * fairness rule also uses (`docs/matchmaking.md` §Fairness).
+ */
+export function evaluateQuery(query, providers, seekers) {
+    let truncated = false;
+    const result = { truncated: false };
+    if (query.includeProviders) {
+        const matched = providers
+            .filter((reg) => matchesFilter(reg.payload, query.filter))
+            .sort((a, b) => a.attachedAt - b.attachedAt);
+        if (matched.length > query.limit) {
+            truncated = true;
+        }
+        result.providers = matched.slice(0, query.limit).map(providerEntryOf);
+    }
+    if (query.includeSeekers) {
+        const ordered = [...seekers].sort((a, b) => a.attachedAt - b.attachedAt);
+        if (ordered.length > query.limit) {
+            truncated = true;
+        }
+        result.seekers = ordered.slice(0, query.limit).map(seekerEntryOf);
+    }
+    result.truncated = truncated;
+    return result;
+}
+//# sourceMappingURL=query-eval.js.map

package/dist/src/matchmaking/query-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-eval.js","sourceRoot":"","sources":["../../../src/matchmaking/query-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA4BvD,0GAA0G;AAC1G,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC7D,OAAO;QACN,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,YAAY,EAAE,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC;QAC3C,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,cAAc;QAC1C,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW;QACpC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS;KACtC,CAAC;AACH,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,GAA4B;IACzD,OAAO;QACN,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS;QAChC,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW;QACpC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS;KACtC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAc,EACd,SAA+C,EAC/C,OAA2C;IAE3C,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,MAAM,MAAM,GAAqF,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAEtH,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,SAAS;aACvB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;aACzD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QACzE,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAClC,SAAS,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,OAAO,MAAM,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,95 @@
+/**
+ * Matchmaking — seeker hang-out-vs-continue decision engine (db-core, pure).
+ *
+ * Per `docs/matchmaking.md` §Hang-out vs. continue. After a seeker registers at a cohort and receives
+ * `Accepted` with `topicTraffic` at tree tier `d`, it must decide: is *this* tier the right place to
+ * wait, or should it walk one tier toward the root? This module is the pure arithmetic of that choice
+ * — no I/O, no clock — so it is unit-testable directly against the doc's worked examples. The db-p2p
+ * `seeker-walk-client` drives the walk (register / query / renew / withdraw) and calls {@link decide}.
+ *
+ * Decision rule (`docs/matchmaking.md` §Decision rule):
+ *
+ * 1. **Immediate-match.** If `currentMatches >= wantCount` → `done`. (The caller has already issued the
+ *    `QueryV1`; `currentMatches` is its filter-matched, re-validated yield. This also covers edge case 2
+ *    — a stale `arrivalsPerMin = 0` after an epoch rotation still gets a real query first, so a quiet
+ *    cohort that actually holds enough providers resolves to `done` rather than a spurious escalate.)
+ * 2. **Hang-out feasibility.**
+ *    ```
+ *    expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)
+ *    contentionFactor   ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)
+ *    hang out  iff  currentMatches + expectedNewMatches ≥ wantCount × contentionFactor
+ *    ```
+ * 3. **Otherwise escalate** (walk one tier toward the root).
+ *
+ * Edge cases the engine encodes (the rest live in the walk client, which owns the walk topology):
+ * - **Filter matches almost nothing (case 4):** a `filterAcceptRatio` decayed toward 0 collapses
+ *   `expectedNewMatches`, so the feasibility test fails at every tier and the seeker walks to the root.
+ * - **Many seekers competing (case 5):** a high `queriesPerMin` inflates `contentionFactor` up to
+ *   `cap`, raising the threshold so more seekers escalate toward aggregation — self-balancing, bounded.
+ */
+import type { HangOutConfig } from "./config.js";
+/** Inputs to {@link decide}: the cohort's `topicTraffic` plus the seeker's running state. */
+export interface SeekerDecisionInputs {
+    /** Filter-matched, re-validated providers from the immediate `QueryV1` at this tier. */
+    readonly currentMatches: number;
+    /** `topicTraffic.directParticipants` — informational (providers known here right now). */
+    readonly directParticipants: number;
+    /** `topicTraffic.arrivalsPerMin` — provider registration + renewal rate. */
+    readonly arrivalsPerMin: number;
+    /** `topicTraffic.queriesPerMin` — competing seeker activity over the same pool. */
+    readonly queriesPerMin: number;
+    /** `topicTraffic.childCohortCount` — `> 0` means this tier has promoted (descend territory). */
+    readonly childCohortCount: number;
+    /** Providers the seeker needs. */
+    readonly wantCount: number;
+    /** Patience budget left at this tier (drains across walked tiers — the client tracks it). */
+    readonly patienceMsRemaining: number;
+    /** Running estimate of the fraction of returned providers that pass the seeker's filter (decays from 1.0). */
+    readonly filterAcceptRatio: number;
+    /** Assumed mean `wantCount` of competing seekers (small constant or learned). */
+    readonly meanWantCount: number;
+}
+/** The outcome of {@link decide}. `hangOut` carries the poll cadence for the requery loop. */
+export type SeekerDecision = {
+    readonly action: "done";
+} | {
+    readonly action: "hangOut";
+    readonly requeryIntervalMs: number;
+} | {
+    readonly action: "escalate";
+};
+/** `expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)`. */
+export declare function expectedNewMatches(inputs: SeekerDecisionInputs): number;
+/** `contentionFactor ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)`. */
+export declare function contentionFactor(inputs: SeekerDecisionInputs, cfg: HangOutConfig): number;
+/** The hang-out feasibility threshold `wantCount × contentionFactor`. */
+export declare function hangOutThreshold(inputs: SeekerDecisionInputs, cfg: HangOutConfig): number;
+/**
+ * Decide whether the seeker is `done` (immediate match), should `hangOut` (feasible to wait here), or
+ * should `escalate` (walk one tier toward the root). Pure — see the module header for the rule.
+ */
+export declare function decide(inputs: SeekerDecisionInputs, cfg: HangOutConfig): SeekerDecision;
+/**
+ * Running yield accumulator for `filterAcceptRatio`. The ratio starts at `filter_accept_ratio_initial`
+ * (1.0, used before any observation) and is refined to the cumulative `matched / returned` over the
+ * walk: after two cohorts that each return ~10% matchable providers it settles near 0.1, collapsing
+ * `expectedNewMatches` for a pathological filter (edge case 4).
+ */
+export interface FilterAcceptRatioState {
+    /** Total filter-matched providers observed across queries so far. */
+    readonly matched: number;
+    /** Total providers returned across queries so far. */
+    readonly returned: number;
+}
+/** A fresh (zero-observation) {@link FilterAcceptRatioState}. */
+export declare function newFilterAcceptRatioState(): FilterAcceptRatioState;
+/** Fold one query's yield (`matched` of `returned`) into the running state. */
+export declare function observeYield(state: FilterAcceptRatioState, matched: number, returned: number): FilterAcceptRatioState;
+/**
+ * The current `filterAcceptRatio`: cumulative `matched / returned`, or `initial` (1.0) before any
+ * providers have been returned (so the first hang-out estimate is optimistic, then refines).
+ */
+export declare function filterAcceptRatio(state: FilterAcceptRatioState, initial?: number): number;
+/** The default assumed competing-seeker `meanWantCount` (re-exported for the walk client). */
+export declare const DEFAULT_MEAN_WANT_COUNT = 3;
+//# sourceMappingURL=seeker-walk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seeker-walk.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/seeker-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB;IACpC,wFAAwF;IACxF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,8GAA8G;IAC9G,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnC,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAGzF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAEzF;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,EAAE,aAAa,GAAG,cAAc,CASvF;AAID;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,iEAAiE;AACjE,wBAAgB,yBAAyB,IAAI,sBAAsB,CAElE;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAErH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,GAAE,MAAoC,GAAG,MAAM,CAEtH;AAED,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,IAA0B,CAAC"}

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

@@ -0,0 +1,75 @@
+/**
+ * Matchmaking — seeker hang-out-vs-continue decision engine (db-core, pure).
+ *
+ * Per `docs/matchmaking.md` §Hang-out vs. continue. After a seeker registers at a cohort and receives
+ * `Accepted` with `topicTraffic` at tree tier `d`, it must decide: is *this* tier the right place to
+ * wait, or should it walk one tier toward the root? This module is the pure arithmetic of that choice
+ * — no I/O, no clock — so it is unit-testable directly against the doc's worked examples. The db-p2p
+ * `seeker-walk-client` drives the walk (register / query / renew / withdraw) and calls {@link decide}.
+ *
+ * Decision rule (`docs/matchmaking.md` §Decision rule):
+ *
+ * 1. **Immediate-match.** If `currentMatches >= wantCount` → `done`. (The caller has already issued the
+ *    `QueryV1`; `currentMatches` is its filter-matched, re-validated yield. This also covers edge case 2
+ *    — a stale `arrivalsPerMin = 0` after an epoch rotation still gets a real query first, so a quiet
+ *    cohort that actually holds enough providers resolves to `done` rather than a spurious escalate.)
+ * 2. **Hang-out feasibility.**
+ *    ```
+ *    expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)
+ *    contentionFactor   ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)
+ *    hang out  iff  currentMatches + expectedNewMatches ≥ wantCount × contentionFactor
+ *    ```
+ * 3. **Otherwise escalate** (walk one tier toward the root).
+ *
+ * Edge cases the engine encodes (the rest live in the walk client, which owns the walk topology):
+ * - **Filter matches almost nothing (case 4):** a `filterAcceptRatio` decayed toward 0 collapses
+ *   `expectedNewMatches`, so the feasibility test fails at every tier and the seeker walks to the root.
+ * - **Many seekers competing (case 5):** a high `queriesPerMin` inflates `contentionFactor` up to
+ *   `cap`, raising the threshold so more seekers escalate toward aggregation — self-balancing, bounded.
+ */
+import { FILTER_ACCEPT_RATIO_INITIAL, MEAN_WANT_COUNT_DEFAULT } from "./config.js";
+/** `expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)`. */
+export function expectedNewMatches(inputs) {
+    return inputs.arrivalsPerMin * inputs.filterAcceptRatio * (inputs.patienceMsRemaining / 60_000);
+}
+/** `contentionFactor ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)`. */
+export function contentionFactor(inputs, cfg) {
+    const raw = 1 + (inputs.queriesPerMin * inputs.meanWantCount) / Math.max(inputs.arrivalsPerMin, 1);
+    return Math.min(raw, cfg.contentionFactorCap);
+}
+/** The hang-out feasibility threshold `wantCount × contentionFactor`. */
+export function hangOutThreshold(inputs, cfg) {
+    return inputs.wantCount * contentionFactor(inputs, cfg);
+}
+/**
+ * Decide whether the seeker is `done` (immediate match), should `hangOut` (feasible to wait here), or
+ * should `escalate` (walk one tier toward the root). Pure — see the module header for the rule.
+ */
+export function decide(inputs, cfg) {
+    if (inputs.currentMatches >= inputs.wantCount) {
+        return { action: "done" };
+    }
+    const projected = inputs.currentMatches + expectedNewMatches(inputs);
+    if (projected >= hangOutThreshold(inputs, cfg)) {
+        return { action: "hangOut", requeryIntervalMs: cfg.requeryIntervalMs };
+    }
+    return { action: "escalate" };
+}
+/** A fresh (zero-observation) {@link FilterAcceptRatioState}. */
+export function newFilterAcceptRatioState() {
+    return { matched: 0, returned: 0 };
+}
+/** Fold one query's yield (`matched` of `returned`) into the running state. */
+export function observeYield(state, matched, returned) {
+    return { matched: state.matched + matched, returned: state.returned + returned };
+}
+/**
+ * The current `filterAcceptRatio`: cumulative `matched / returned`, or `initial` (1.0) before any
+ * providers have been returned (so the first hang-out estimate is optimistic, then refines).
+ */
+export function filterAcceptRatio(state, initial = FILTER_ACCEPT_RATIO_INITIAL) {
+    return state.returned > 0 ? state.matched / state.returned : initial;
+}
+/** The default assumed competing-seeker `meanWantCount` (re-exported for the walk client). */
+export const DEFAULT_MEAN_WANT_COUNT = MEAN_WANT_COUNT_DEFAULT;
+//# sourceMappingURL=seeker-walk.js.map