@gibs/quotes 1.13.0

package/dist/search/waves.d.ts

@@ -0,0 +1,481 @@
+import { type GasCostFor, type HopEdge, type HopFloor, type RoutePlan } from '@gibs/bridge-sdk/routing';
+export { isRateLimitedCarrier } from '@gibs/bridge-sdk/routing';
+/**
+ * PHASE 2 — ROUNDS. Turns the plans `enumerate.ts` finds into priced,
+ * ranked plans, asking real providers for only the hops that genuinely need
+ * asking. "Local steps are exact now": `enumerate.ts` already runs every
+ * carrier that exposes `Carrier.exact` synchronously, against the reader's
+ * own real amount, so a hop carried by the omnibridge crossing, a PulseX
+ * swap, or any other free local read arrives here ALREADY a binding
+ * `'quote'` — this module never asks one. What still needs asking is the
+ * AGGREGATOR hops (LI.FI, Relay, NEAR Intents), which `enumerate.ts` can only
+ * ever estimate (a provider model, or a bare price-feed guess).
+ *
+ * TWO ROUNDS, NOT THREE WAVES. Round A asks each path's FIRST aggregator hop,
+ * one parallel flight, capped per provider. Round B asks each path's SECOND
+ * aggregator hop (when it has one) at Round A's own guaranteed minimum,
+ * capped tighter still. There is no confirmation pass: a local hop needs no
+ * confirming (it was exact from the start), and a third aggregator hop in one
+ * plan is rare enough (at most 3 signatures total, and every plan needs at
+ * least one non-aggregator action to reach a bridgeable pair in practice)
+ * that this module accepts it staying an estimate rather than adding a third
+ * round to chase it — see `README`/design doc's "Rounds" section for the
+ * owner's own model: "estimates choose what gets quoted but never win."
+ *
+ * PURE ORCHESTRATION, NO FETCHING OF ITS OWN — unchanged from the previous
+ * wave-based design. This module never calls `fetch` and knows nothing about
+ * LI.FI, Relay or NEAR Intents by name; it is handed an {@link AskEdge}
+ * function and a {@link WaveClock}, and a {@link GasCostFor} for what a
+ * signature really costs. Everything else belongs to the interface adapter
+ * that supplies them (`packages/ui/src/lib/state/route-search-quotes.ts`).
+ *
+ * WHY A SEPARATE CONCURRENCY LIMITER FROM `packages/ui/.../quoteLimiter.ts`,
+ * RATHER THAN ONE SHARED MODULE. `bridge-sdk`/`@gibs/quotes` cannot depend on
+ * `packages/ui`, so this module enforces its own per-provider budget
+ * internally, over calls to the caller-supplied `askEdge` — the same reason
+ * the previous wave-based design gave for keeping its limiter internal.
+ */
+/**
+ * One request this module hands to the caller-supplied {@link AskEdge}
+ * function: "what does this edge deliver for this input?"
+ */
+export type AskEdgeRequest = {
+    /** The edge being asked. */
+    readonly edge: HopEdge;
+    /** The amount flowing INTO the edge, in `edge.from`'s base units. */
+    readonly inputAmount: bigint;
+};
+/**
+ * Why an edge answered with a refusal rather than a deliverable amount.
+ *
+ * A BROADER VOCABULARY THAN `quote-refusals.ts`'s `QuoteRefusalKind`, AND
+ * DELIBERATELY NOT THE SAME TYPE. `QuoteRefusalKind` (`packages/ui/.../quote-refusals.ts`)
+ * names why an AGGREGATOR declined — the three kinds measured against LI.FI
+ * and Relay. An edge here can also be a bridge entry call refused for
+ * falling outside `minPerTx`/`maxAvailablePerTx` (`../../bridge-limits.js`),
+ * which is neither a "no quote" nor a "could not ask" in the aggregator
+ * sense — it is a bound this module's own local read enforces. `bridge-sdk`
+ * cannot import the user-interface package's type to extend it, so this is
+ * its own union; `'no-quote'`, `'could-not-ask'` and `'cannot-carry'` share
+ * their spelling with `QuoteRefusalKind`'s members on purpose, so the
+ * interface adapter's translation from one to the other (`route-search-quotes.ts`)
+ * is a one-to-one rename, not a judgement call.
+ */
+export type EdgeRefusalKind = 'no-quote' | 'could-not-ask' | 'cannot-carry' | 'below-minimum' | 'above-available';
+/** Why an edge refused, with its reason and any minimum this module can learn from. */
+export type EdgeRefusal = {
+    readonly kind: EdgeRefusalKind;
+    /** The provider's own words for why, or null when none was given. */
+    readonly reason: string | null;
+    /**
+     * A minimum amount this refusal names, in `edge.from`'s base units, or
+     * null when the refusal names no such figure (`'no-quote'`,
+     * `'could-not-ask'`, `'cannot-carry'` usually carry none). When present,
+     * this feeds the {@link FloorsCache} so a later ask of the SAME edge below
+     * this amount is pruned without a request.
+     */
+    readonly minimumAmount: bigint | null;
+};
+/** What answering one {@link AskEdgeRequest} produces: a deliverable amount, or a refusal. */
+export type AskEdgeAnswer = {
+    readonly ok: true;
+    /** What the edge delivers for the asked input, in `edge.to`'s base units. */
+    readonly deliveredAmount: bigint;
+    /**
+     * The GUARANTEED delivered amount after slippage, when the provider
+     * states one; null when it does not. Round B re-asks a later
+     * aggregator hop at the PREVIOUS aggregator hop's minimum, falling
+     * back to `deliveredAmount` when null.
+     */
+    readonly minimumDeliveredAmount: bigint | null;
+    /** The carrier's own claimed execution duration in seconds, or null. */
+    readonly claimedDurationSeconds: number | null;
+} | {
+    readonly ok: false;
+    readonly refusal: EdgeRefusal;
+};
+/**
+ * Asks one edge, at one amount, for what it delivers. Supplied by the
+ * interface adapter (`route-search-quotes.ts`); never implemented in this
+ * module. See this module's own doc for why.
+ */
+export type AskEdge = (request: AskEdgeRequest) => Promise<AskEdgeAnswer>;
+/**
+ * The two facts about time this module needs, injected so a test can drive
+ * a round's budget without waiting in real time.
+ */
+export type WaveClock = {
+    /** The current time in milliseconds — used only to bucket and expire cache entries. */
+    readonly now: () => number;
+    /**
+     * Resolves after `milliseconds`. This is what a round races its
+     * outstanding asks against: real code resolves it with a timer, a test
+     * resolves it however it likes (immediately, to force a budget cutoff;
+     * never, to prove the budget is not consulted when nothing needs it).
+     */
+    readonly after: (milliseconds: number) => Promise<void>;
+};
+/** The real clock: `Date.now()` and a real `setTimeout`. What production code uses. */
+export declare const realWaveClock: WaveClock;
+/** Round A's time budget: every selected first-aggregator-hop ask, given six seconds to answer, one parallel flight. */
+export declare const ROUND_A_TIME_BUDGET_MS = 6000;
+/** Round B's time budget. */
+export declare const ROUND_B_TIME_BUDGET_MS = 4000;
+/** {@link confirmCandidate}'s own time budget for its single ask. */
+export declare const CONFIRM_CANDIDATE_TIME_BUDGET_MS = 4000;
+/** The most paths Round A asks per provider — LI.FI and Relay's own share of the owner's caps. */
+export declare const DEFAULT_PROVIDER_CONCURRENCY_LIMIT = 4;
+/**
+ * NEAR Intents' own, lower Round A cap. Measured: 40 concurrent requests
+ * against these providers fail about 80% of the time, while 40 in sequence
+ * pass — see `packages/ui/.../quoteLimiter.ts`'s own doc for the same
+ * measurement applied to the interface's query layer. NEAR Intents is capped
+ * more tightly than the other two because every one of its requests reserves
+ * state on the far side even when asked `dry`.
+ */
+export declare const NEAR_INTENTS_CONCURRENCY_LIMIT = 3;
+/** The most paths Round B asks per provider — a tighter follow-up pass than Round A. */
+export declare const ROUND_B_MAX_REQUESTS_PER_PROVIDER = 2;
+/** The most next-best, still-unconfirmed plans {@link searchRouteWaves} returns as `estimatedCandidates`. */
+export declare const MAX_ESTIMATED_CANDIDATES = 5;
+/**
+ * How far a live answer must diverge from its own pre-round estimate, as a
+ * fraction of the estimate, before {@link searchRouteWaves} reports it to
+ * {@link SearchRouteWavesOptions.onCalibrationDivergence}.
+ */
+export declare const CALIBRATION_DIVERGENCE_RATIO_THRESHOLD = 0.01;
+/** How long one cached edge answer is trusted before it is asked again. */
+export declare const EDGE_ANSWER_CACHE_TTL_MS = 30000;
+/**
+ * Rounds a positive base-unit amount to two significant figures, always by
+ * bigint arithmetic — never through a float, which would misround a large
+ * amount long before the two figures this needs. `123,456,789n` buckets to
+ * `120,000,000n`; `7n` buckets to `7n` (already two-or-fewer digits).
+ *
+ * WHY TWO SIGNIFICANT FIGURES. Caching lets "typing reuse" an answer — a
+ * reader adjusting the fourth digit of an amount should not re-ask every
+ * provider, but a reader who has typed a materially different amount should.
+ * Two significant figures is coarse enough to absorb a keystroke and fine
+ * enough that a doubled or halved amount still buckets differently.
+ *
+ * @param amount - the amount to bucket, in base units
+ * @returns the bucketed amount; zero and negative inputs bucket to zero
+ */
+export declare const twoSignificantFigureAmountBucket: (amount: bigint) => bigint;
+/** One entry recorded in an {@link EdgeAnswerCache}. */
+type EdgeAnswerCacheEntry = {
+    /** The EXACT amount this answer was asked at (never the bucket) — see `recomposePath`. */
+    readonly askedAmount: bigint;
+    readonly answer: AskEdgeAnswer;
+    readonly recordedAtMs: number;
+};
+/**
+ * One edge answer, reusable for 30 seconds by any ask that lands in the same
+ * two-significant-figure amount bucket. Injectable so a caller can share one
+ * cache across the several calls a reader's typing makes to the exported
+ * search function, and so a test can supply a fresh, isolated one per case.
+ */
+export type EdgeAnswerCache = {
+    /**
+     * Reads a cached answer for `edge` at `askedAmount`'s bucket, or null when
+     * there is none or it has aged past {@link EDGE_ANSWER_CACHE_TTL_MS}.
+     */
+    readonly get: (edge: HopEdge, askedAmount: bigint) => EdgeAnswerCacheEntry | null;
+    /** Records an answer for `edge` at `askedAmount`'s bucket. */
+    readonly set: (edge: HopEdge, askedAmount: bigint, answer: AskEdgeAnswer) => void;
+};
+/**
+ * Builds a fresh, empty {@link EdgeAnswerCache}.
+ *
+ * @param clock - supplies `now()` for recording and expiring entries;
+ *   defaults to {@link realWaveClock}
+ * @returns the cache
+ */
+export declare const createEdgeAnswerCache: (clock?: Pick<WaveClock, "now">) => EdgeAnswerCache;
+/**
+ * Every floor a round search has learned so far, readable in the exact shape
+ * `enumerate.ts`'s `EnumerateRoutesOptions.knownFloors` expects — so the
+ * caller can feed the SAME cache straight back into the next call to
+ * `enumerateRoutes` and have it prune edges this search already learned are
+ * too small.
+ */
+export type FloorsCache = {
+    /** Records a learned floor for one edge. Keeps only the LARGEST minimum seen for that edge. */
+    readonly record: (edge: Pick<HopEdge, 'carrier' | 'from' | 'to'>, floor: HopFloor) => void;
+    /** Reads the floors known for one edge — the shape `enumerate.ts` consumes directly. */
+    readonly read: (edge: Pick<HopEdge, 'carrier' | 'from' | 'to'>) => readonly HopFloor[];
+};
+/**
+ * Builds a fresh, empty {@link FloorsCache}.
+ *
+ * @returns the cache
+ */
+export declare const createFloorsCache: () => FloorsCache;
+/**
+ * The plan as its fused first hop's signature really delivers it: the hop
+ * hands the next one `entryTarget` instead of its guaranteed minimum.
+ *
+ * WHY. {@link recomposePath} hands the hop after a fused one exactly the
+ * guaranteed minimum, because the pre-quote's floor is the entry call's first
+ * target. That pre-quote never paid for the entry call. When the provider's
+ * exact-output answer prices the call past the typed amount, the host shrinks
+ * the target until the spend fits (`fitEntryTarget` in the interface), so the
+ * cost comes out of the output. A plan that still composed from the minimum
+ * would show the reader more than the signature can deliver, and the press
+ * would report a price move that was never a move.
+ *
+ * Every later hop keeps its own rate — what it delivered for what it was
+ * handed — applied to the smaller amount, the same way a hop whose upstream
+ * amount moved is composed everywhere else in this module. The first hop's
+ * own outcome is untouched: it still names the minimum the entry call was
+ * first built for, which is what the signer checks the target against.
+ *
+ * @param plan - a plan whose first hop fuses with the next
+ * @param entryTarget - the entry amount the signature embeds, in the first
+ *   hop's `to` node's base units
+ * @returns the plan itself when `entryTarget` is the minimum, the plan
+ *   composed from `entryTarget` when it is smaller, or null when the first
+ *   hop is not a fused quote with a minimum, or `entryTarget` is not positive
+ *   or is above that minimum
+ */
+export declare const planWithEntryTarget: (plan: RoutePlan, entryTarget: bigint) => RoutePlan | null;
+/**
+ * One live answer that diverged from its own pre-round estimate by more than
+ * {@link CALIBRATION_DIVERGENCE_RATIO_THRESHOLD} — handed to
+ * {@link SearchRouteWavesOptions.onCalibrationDivergence} so a host can feed
+ * its carriers' own calibration store (`route-search-quotes.ts` onward).
+ * Compares RATES, not raw amounts, because a live ask and its own estimate
+ * are rarely taken at the exact same input amount.
+ */
+export type CalibrationDivergenceRecord = {
+    /** The edge whose live answer diverged. */
+    readonly edge: HopEdge;
+    /** The amount this live answer was asked at. */
+    readonly askedAmount: bigint;
+    /** What the live ask actually delivered, at `askedAmount`. */
+    readonly liveDeliveredAmount: bigint;
+    /** What this edge's pre-round estimate said it would deliver, at `estimatedInputAmount`. */
+    readonly estimatedDeliveredAmount: bigint;
+    /** The input amount the pre-round estimate was computed against. */
+    readonly estimatedInputAmount: bigint;
+    /**
+     * `(liveRate − estimatedRate) / estimatedRate`, where each rate is that
+     * side's own `deliveredAmount / inputAmount`. Positive when the live
+     * answer delivered MORE than estimated, negative when it delivered less.
+     */
+    readonly divergenceRatio: number;
+};
+/** One refusal this search collected, for the caller to surface or feed a floors cache. */
+export type CollectedRefusal = {
+    readonly edge: HopEdge;
+    readonly askedAmount: bigint;
+    readonly refusal: EdgeRefusal;
+};
+/**
+ * How far above its own figure an estimated hop may still turn out to land,
+ * in parts per million, charged once for every `'estimate'` hop in a plan.
+ * The same 1% {@link CALIBRATION_DIVERGENCE_RATIO_THRESHOLD} names as the
+ * point where a live answer counts as having moved away from its estimate:
+ * inside it, the estimate was right; past it, the carrier's own model is
+ * corrected. So 1% per estimated hop is the widest honest "best case" the
+ * engine can state from what it knows before asking.
+ */
+export declare const ESTIMATE_ALLOWANCE_PPM_PER_ESTIMATED_HOP = 10000n;
+/**
+ * The most a plan could still deliver, net of every signature's gas, in its
+ * destination token's base units — or null when the plan has no figure a
+ * ranking may trust (`planIsRankable` false), which is a plan the engine can
+ * neither bound nor show.
+ *
+ * AN UPPER BOUND, BUILT ONLY FROM WHAT IS KNOWN AHEAD OF TIME. Each hop's
+ * figure already carries that carrier's own known fee (a local carrier's
+ * exact read, an aggregator's provider model, or the price catalogue), and
+ * {@link gasAdjustedDeliveredAmount} subtracts the real gas of EVERY
+ * signature. The only optimism added is
+ * {@link ESTIMATE_ALLOWANCE_PPM_PER_ESTIMATED_HOP} per hop that is still an
+ * estimate. A confirmed plan gets no allowance: its figure is what it is.
+ *
+ * @param plan - the plan to bound
+ * @param gasCostFor - the real cost of one signature
+ * @returns the plan's best-case net delivery, or null when it is not rankable
+ */
+export declare const planBestCaseNetDelivery: (plan: RoutePlan, gasCostFor: GasCostFor) => bigint | null;
+/**
+ * The best net delivery among `plans`' CONFIRMED plans — delivered minus the
+ * gas of every signature — or null when none of them is confirmed yet.
+ *
+ * @param plans - any plans; unconfirmed ones are ignored
+ * @param gasCostFor - the real cost of one signature
+ * @returns the best confirmed net delivery, or null
+ */
+export declare const bestConfirmedNetDelivery: (plans: readonly RoutePlan[], gasCostFor: GasCostFor) => bigint | null;
+/**
+ * Whether an unconfirmed plan's best case still beats `bestConfirmed`. An
+ * unrankable plan never does: with no figure there is nothing to compare,
+ * and the owner's rule is that such a path is never shown. With nothing
+ * confirmed yet, every rankable plan is still in the running.
+ *
+ * GENERIC AND COST-BASED. Nothing here reads a chain, a carrier or a token.
+ * A path that leaves a chain and comes back is dropped for the same reason
+ * any other path is: each extra signature costs at least its gas, and each
+ * crossing costs at least its known fee, so its best case falls short.
+ *
+ * @param plan - the unconfirmed plan
+ * @param bestConfirmed - the best confirmed net delivery, or null when none exists
+ * @param gasCostFor - the real cost of one signature
+ * @returns true when the plan could still win
+ */
+export declare const estimateCanStillWin: (plan: RoutePlan, bestConfirmed: bigint | null, gasCostFor: GasCostFor) => boolean;
+/**
+ * Drops every unconfirmed, RANKABLE path whose best case cannot beat the best
+ * path already confirmed by a local exact read — BEFORE any provider is
+ * asked, so a path that cannot win never spends a live quote.
+ *
+ * An unrankable path is kept here, on purpose: it has no figure to bound, so
+ * nothing proves it loses, and a live answer is the only way it can ever get
+ * one. It is still never SHOWN as an estimate — see
+ * {@link splitConfirmedAndEstimated}.
+ *
+ * @param paths - every enumerated path
+ * @param gasCostFor - the real cost of one signature
+ * @returns the paths still worth asking about
+ */
+export declare const prunePathsThatCannotWin: (paths: readonly RoutePlan[], gasCostFor: GasCostFor) => readonly RoutePlan[];
+/**
+ * Folds one plan that {@link SearchRouteWavesResult.confirmCandidate} just
+ * re-priced back into a finished search result — WITHOUT which a confirmed
+ * estimate had nowhere to go. `confirmCandidate` only writes the live answer
+ * into the search's own caches; the result a host renders is plain data and
+ * never changes on its own, so the estimate row stayed an estimate forever.
+ *
+ * The plan replaces the entry with its own `pathKey` wherever it sat. A plan
+ * that is now confirmed joins `plans`; one that is not stays an estimate
+ * only while it still carries a figure and could still win. Both lists are
+ * re-sorted and re-pruned, because a newly confirmed plan can raise the bar
+ * every remaining estimate must clear.
+ *
+ * @param result - the search result to update
+ * @param plan - the plan `confirmCandidate` returned
+ * @param options - the SAME comparator and gas model the search ranked with
+ * @returns a new result; `result` itself is never changed
+ */
+export declare const applyConfirmedCandidate: (result: SearchRouteWavesResult, plan: RoutePlan, options: {
+    readonly compareRoutePlans: (a: RoutePlan, b: RoutePlan) => number;
+    readonly gasCostFor: GasCostFor;
+}) => SearchRouteWavesResult;
+/** What one call to {@link searchRouteWaves} needs. */
+export type SearchRouteWavesOptions = {
+    /** The plans `enumerate.ts` found — local-exact hops already `'quote'`, aggregator hops still `'estimate'`. */
+    readonly paths: readonly RoutePlan[];
+    /** The reader's real amount entering the FIRST hop of every path. */
+    readonly amount: bigint;
+    /** Asks one edge for what it delivers. Never implemented here — see {@link AskEdge}. */
+    readonly askEdge: AskEdge;
+    /**
+     * Supplies the real cost of one signature — see
+     * `@gibs/bridge-sdk/routing`'s `GasCostFor`. Defaults to `zeroGasCostFor`
+     * (charges nothing), which is NOT a production model — a caller with real
+     * gas-price and native-price feeds should always supply its own.
+     */
+    readonly gasCostFor?: GasCostFor;
+    /**
+     * How to rank two finished plans, best first. Defaults to
+     * {@link compareRoutePlansByGasAdjustedDeliveredAmount} applied to
+     * `gasCostFor` — rankable beats unrankable, and within that a plan's REAL
+     * gas-adjusted delivered amount wins, never a flat per-signature guess.
+     */
+    readonly compareRoutePlans?: (a: RoutePlan, b: RoutePlan) => number;
+    /** The clock driving every round's time budget. Defaults to {@link realWaveClock}. */
+    readonly clock?: WaveClock;
+    /** The edge answer cache to read from and write into. Defaults to a fresh, empty one. */
+    readonly edgeAnswerCache?: EdgeAnswerCache;
+    /** The floors cache to read from and write into. Defaults to a fresh, empty one. */
+    readonly floorsCache?: FloorsCache;
+    /**
+     * Called once after each round settles, with the plans ranked so far —
+     * lets a caller stream results to a reader instead of waiting for both
+     * rounds.
+     */
+    readonly onWaveSettled?: (result: {
+        readonly round: 'A' | 'B';
+        readonly plans: readonly RoutePlan[];
+    }) => void;
+    /**
+     * Called whenever a fresh live answer diverges from its own pre-round
+     * estimate by more than {@link CALIBRATION_DIVERGENCE_RATIO_THRESHOLD} — a
+     * host wires this to its carriers' own calibration store. Omitted entirely
+     * (the default) records nothing.
+     */
+    readonly onCalibrationDivergence?: (record: CalibrationDivergenceRecord) => void;
+};
+/** What {@link searchRouteWaves} returns. */
+export type SearchRouteWavesResult = {
+    /**
+     * The CONFIRMED plans (`planIsConfirmed` true on every hop), ranked by the
+     * search's own `compareRoutePlans`. These are the real, ask-backed
+     * candidates a reader may act on.
+     */
+    readonly plans: readonly RoutePlan[];
+    /**
+     * The next-best plans that never landed a live answer for every hop —
+     * still ranked, up to {@link MAX_ESTIMATED_CANDIDATES}, and only those that
+     * carry an estimate and could still beat the best confirmed plan
+     * ({@link estimateCanStillWin}) — for a caller to
+     * list below `plans`, marked as estimates, and confirm on demand with
+     * {@link confirmCandidate}. An estimate never appears in `plans` itself,
+     * however large its estimated figure: see the owner's own model,
+     * "estimates choose what gets quoted but never win."
+     */
+    readonly estimatedCandidates: readonly RoutePlan[];
+    /** Every refusal this search collected, across both rounds. */
+    readonly refusals: readonly CollectedRefusal[];
+    /**
+     * Asks a SINGLE path's still-unasked aggregator hops, in hop order, each
+     * at what the hop before it really delivers — stopping early only at a
+     * refusal or an ask that does not answer in time — and returns that path
+     * recomposed with the fresh answers, or null when
+     * `pathKey` names no path this search found. Touches only `pathKey`'s own
+     * hops; every other path's own state (cache entries, floors) is read, never
+     * written to, beyond what the single ask itself records. Reuses this
+     * search's own edge answer cache, floors cache and provider concurrency
+     * limiter, so an edge `confirmCandidate` asks that a later `plans`/
+     * `estimatedCandidates` recompute also needs is free the second time.
+     *
+     * @param pathKey - the candidate plan's own `RoutePlan.pathKey`
+     */
+    readonly confirmCandidate: (pathKey: string) => Promise<RoutePlan | null>;
+};
+/**
+ * The Round-A/Round-B route search: prices every plan `enumerate.ts` found
+ * against real aggregators, asking only the hops that are not already exact,
+ * in two bounded, budgeted rounds, re-ranking after each one.
+ *
+ * - **Round A** asks each path's first aggregator hop — see {@link buildRoundAAsks}
+ *   — within {@link ROUND_A_TIME_BUDGET_MS}, one parallel flight.
+ * - **Round B** asks each ranked path's second aggregator hop, at Round A's
+ *   own guaranteed minimum — see {@link buildRoundBAsks} — within
+ *   {@link ROUND_B_TIME_BUDGET_MS}.
+ *
+ * Every hop without a fresh answer — a local-exact hop (never asked, on
+ * purpose), or an aggregator hop this search's caps left unasked — keeps
+ * composing from its own last-known figure, so a partial result is always a
+ * complete, ranked list of plans, never a list with holes in it.
+ *
+ * PRUNED FIRST: {@link prunePathsThatCannotWin} drops every path whose best
+ * case cannot beat a plan a local exact read already confirmed, before any
+ * provider is asked.
+ *
+ * THE FINAL SPLIT: `plans` (confirmed) VERSUS `estimatedCandidates`
+ * (unconfirmed plans that carry an estimate and could still win, capped at
+ * {@link MAX_ESTIMATED_CANDIDATES}) —
+ * {@link partitionConfirmedFirst} orders every plan confirmed-first exactly as
+ * before; this function then SLICES that ordering into the two output
+ * fields, rather than returning one merged list, per the owner's own model:
+ * an estimate is listed separately, never blended into the ranked winners.
+ *
+ * @param options - see {@link SearchRouteWavesOptions}
+ * @returns the re-priced plans, split into confirmed and estimated
+ *   candidates, every refusal collected, and a way to confirm one candidate
+ *   on demand
+ */
+export declare const searchRouteWaves: (options: SearchRouteWavesOptions) => Promise<SearchRouteWavesResult>;