@gibs/quotes 1.13.0

package/dist/search/waves.js

@@ -0,0 +1,939 @@
+import { assetNodeKey, compareRoutePlansByGasAdjustedDeliveredAmount, composeRouteDelivery, gasAdjustedDeliveredAmount, hopEdgeKey, hopOutputAmount, isRateLimitedCarrier, planIsConfirmed, planIsRankable, zeroGasCostFor, } from '@gibs/bridge-sdk/routing';
+export { isRateLimitedCarrier } from '@gibs/bridge-sdk/routing';
+/** The real clock: `Date.now()` and a real `setTimeout`. What production code uses. */
+export const realWaveClock = {
+    now: () => Date.now(),
+    after: (milliseconds) => new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    }),
+};
+// ---------------------------------------------------------------------------
+// Budgets and caps
+// ---------------------------------------------------------------------------
+/** Round A's time budget: every selected first-aggregator-hop ask, given six seconds to answer, one parallel flight. */
+export const ROUND_A_TIME_BUDGET_MS = 6_000;
+/** Round B's time budget. */
+export const ROUND_B_TIME_BUDGET_MS = 4_000;
+/** {@link confirmCandidate}'s own time budget for its single ask. */
+export const CONFIRM_CANDIDATE_TIME_BUDGET_MS = 4_000;
+/** The most paths Round A asks per provider — LI.FI and Relay's own share of the owner's caps. */
+export 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 const NEAR_INTENTS_CONCURRENCY_LIMIT = 3;
+/** The most paths Round B asks per provider — a tighter follow-up pass than Round A. */
+export const ROUND_B_MAX_REQUESTS_PER_PROVIDER = 2;
+/** The most next-best, still-unconfirmed plans {@link searchRouteWaves} returns as `estimatedCandidates`. */
+export 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 const CALIBRATION_DIVERGENCE_RATIO_THRESHOLD = 0.01;
+/** Provider concurrency caps, by `ProviderId`. Every registered provider defaults to {@link DEFAULT_PROVIDER_CONCURRENCY_LIMIT}. */
+const providerConcurrencyLimit = (providerId) => providerId === 'near-intents' ? NEAR_INTENTS_CONCURRENCY_LIMIT : DEFAULT_PROVIDER_CONCURRENCY_LIMIT;
+/** How long one cached edge answer is trusted before it is asked again. */
+export const EDGE_ANSWER_CACHE_TTL_MS = 30_000;
+// ---------------------------------------------------------------------------
+// The edge answer cache — keyed by edge and a two-significant-figure amount bucket
+// ---------------------------------------------------------------------------
+/**
+ * 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 const twoSignificantFigureAmountBucket = (amount) => {
+    if (amount <= 0n)
+        return 0n;
+    const digitCount = amount.toString().length;
+    if (digitCount <= 2)
+        return amount;
+    const divisor = 10n ** BigInt(digitCount - 2);
+    const flooredBucket = amount / divisor;
+    const remainder = amount % divisor;
+    const roundedBucket = remainder * 2n >= divisor ? flooredBucket + 1n : flooredBucket;
+    return roundedBucket * divisor;
+};
+const edgeAnswerCacheKey = (edge, askedAmount) => `${hopEdgeKey(edge)}#${twoSignificantFigureAmountBucket(askedAmount).toString()}`;
+/**
+ * Builds a fresh, empty {@link EdgeAnswerCache}.
+ *
+ * @param clock - supplies `now()` for recording and expiring entries;
+ *   defaults to {@link realWaveClock}
+ * @returns the cache
+ */
+export const createEdgeAnswerCache = (clock = realWaveClock) => {
+    const entries = new Map();
+    return {
+        get: (edge, askedAmount) => {
+            const key = edgeAnswerCacheKey(edge, askedAmount);
+            const entry = entries.get(key);
+            if (entry === undefined)
+                return null;
+            if (clock.now() - entry.recordedAtMs > EDGE_ANSWER_CACHE_TTL_MS) {
+                entries.delete(key);
+                return null;
+            }
+            return entry;
+        },
+        set: (edge, askedAmount, answer) => {
+            entries.set(edgeAnswerCacheKey(edge, askedAmount), { askedAmount, answer, recordedAtMs: clock.now() });
+        },
+    };
+};
+const floorsCacheKey = (edge) => [edge.carrier, assetNodeKey(edge.from), assetNodeKey(edge.to)].join('|');
+/**
+ * Builds a fresh, empty {@link FloorsCache}.
+ *
+ * @returns the cache
+ */
+export const createFloorsCache = () => {
+    const floorsByEdge = new Map();
+    return {
+        record: (edge, floor) => {
+            const key = floorsCacheKey(edge);
+            const existing = floorsByEdge.get(key);
+            // Keep the LARGEST known floor. A provider's own minimum only ever
+            // narrows the workable range from below; a smaller figure learned
+            // later (a different, unrelated decline) must never overwrite a
+            // larger one already proven true.
+            if (existing !== undefined && existing.minimumAmount >= floor.minimumAmount)
+                return;
+            floorsByEdge.set(key, floor);
+        },
+        read: (edge) => {
+            const floor = floorsByEdge.get(floorsCacheKey(edge));
+            return floor === undefined ? [] : [floor];
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// The per-provider concurrency limiter
+// ---------------------------------------------------------------------------
+/**
+ * A minimal keyed semaphore: at most `limit` tasks registered under the same
+ * key run at once; the rest queue in the order they arrived. Internal to
+ * this module — see the module doc for why it is not shared with
+ * `packages/ui/.../quoteLimiter.ts`.
+ */
+class KeyedConcurrencyLimiter {
+    activeCountByKey = new Map();
+    queueByKey = new Map();
+    /**
+     * Runs `task` once fewer than `limit` tasks are active under `key`,
+     * waiting in a FIFO queue otherwise.
+     *
+     * @param key - the concurrency group, e.g. a provider id
+     * @param limit - the most tasks allowed active under `key` at once
+     * @param task - the work to run once a slot is free
+     * @returns whatever `task` resolves to
+     */
+    async run(key, limit, task) {
+        await this.acquire(key, limit);
+        try {
+            return await task();
+        }
+        finally {
+            this.release(key);
+        }
+    }
+    acquire(key, limit) {
+        const active = this.activeCountByKey.get(key) ?? 0;
+        if (active < limit) {
+            this.activeCountByKey.set(key, active + 1);
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const queue = this.queueByKey.get(key) ?? [];
+            queue.push(() => {
+                this.activeCountByKey.set(key, (this.activeCountByKey.get(key) ?? 0) + 1);
+                resolve();
+            });
+            this.queueByKey.set(key, queue);
+        });
+    }
+    release(key) {
+        const active = this.activeCountByKey.get(key) ?? 0;
+        this.activeCountByKey.set(key, Math.max(0, active - 1));
+        const queue = this.queueByKey.get(key);
+        const next = queue?.shift();
+        if (next !== undefined)
+            next();
+    }
+}
+// ---------------------------------------------------------------------------
+// Composing a path from known answers
+// ---------------------------------------------------------------------------
+/**
+ * One entry in a path's original, enumerate.ts-provided chain: the amount
+ * that ORIGINALLY flowed into hop `index`, and what that hop's own original
+ * outcome said it delivered. Used both as the fallback rate for any hop this
+ * search never got a fresh answer for, and to detect when a hop's own upstream
+ * amount has NOT changed — see {@link recomposePath}.
+ */
+const originalHopInputAmounts = (path, amount) => {
+    const inputs = [];
+    let currentAmount = amount;
+    for (const hop of path.hops) {
+        inputs.push(currentAmount);
+        currentAmount = hop.outcome.deliveredAmount;
+    }
+    return inputs;
+};
+/**
+ * The amount THIS SEARCH WOULD ASK at for each hop of `path`: walk the
+ * chain, preferring a landed hop's GUARANTEED MINIMUM over its expected
+ * figure, falling back to {@link originalHopInputAmounts}'s chain one hop at
+ * a time when nothing fresh is cached for a hop yet.
+ *
+ * BUILT ITERATIVELY, EACH STEP FEEDING THE NEXT — hop `i`'s amount is looked
+ * up in `cache` using hop `i − 1`'s OWN amount from THIS SAME array, so a
+ * cache lookup here always lands on the EXACT bucket a real ask actually
+ * used.
+ *
+ * @param path - the plan to compute asked amounts for
+ * @param amount - the reader's real amount entering the plan's first hop
+ * @param cache - the edge answers gathered so far
+ * @returns one asked amount per hop, in hop order
+ */
+const propagatedHopInputAmounts = (path, amount, cache) => {
+    const original = originalHopInputAmounts(path, amount);
+    const propagated = [amount];
+    for (let index = 0; index < path.hops.length - 1; index += 1) {
+        const askedAmount = propagated[index];
+        const entry = cache.get(path.hops[index].edge, askedAmount);
+        const nextAmount = entry !== null && entry.answer.ok
+            ? (entry.answer.minimumDeliveredAmount ?? entry.answer.deliveredAmount)
+            : (original[index + 1] ?? askedAmount);
+        propagated.push(nextAmount);
+    }
+    return propagated;
+};
+/**
+ * Looks up the freshest known answer for one hop of one path: the cache
+ * entry for `edge` at `askedAmount`'s bucket, or null when nothing is
+ * cached yet.
+ */
+const lookupAnswer = (cache, edge, askedAmount) => cache.get(edge, askedAmount);
+/**
+ * The first hop's GUARANTEED minimum — see `HopOutcome`'s
+ * `minimumDeliveredAmount` — when its live answer was recorded at exactly the
+ * amount this plan asks it at and stated one; null otherwise. Mirrors the
+ * condition under which {@link recomposePath} composes the first hop as a
+ * binding `'quote'`, so a minimum is never attached to an estimate.
+ */
+const firstHopGuaranteedMinimum = (path, askedAmountForHop, originalInputs, startAmount, cache) => {
+    const firstHop = path.hops[0];
+    if (firstHop === undefined)
+        return null;
+    const askedAmount = askedAmountForHop[0] ?? originalInputs[0] ?? startAmount;
+    const entry = lookupAnswer(cache, firstHop.edge, askedAmount);
+    if (entry === null || !entry.answer.ok || entry.askedAmount !== askedAmount)
+        return null;
+    return entry.answer.minimumDeliveredAmount;
+};
+/**
+ * Rebuilds one {@link RoutePlan} from whatever answers are cached so far,
+ * falling back to the plan's ORIGINAL enumerate.ts outcome for any hop with
+ * no fresh answer. The first hop's answer composes as a binding
+ * {@link ComposableHopFigure} `'quote'` ONLY when the cache entry was itself
+ * recorded at THIS hop's exact `askedAmount` — every other hop, and a
+ * first-hop cache hit recorded at a DIFFERENT amount that merely shares its
+ * two-significant-figure bucket, composes as a `'probeRate'` instead.
+ *
+ * A HOP enumerate.ts ALREADY ANSWERED EXACTLY (`carrier.exact`, kind
+ * `'quote'`) STAYS A TRUE QUOTE WHEN NOTHING CHANGED. "Local steps are exact
+ * now": enumerate.ts computes a local hop's `deliveredAmount` against the
+ * REAL amount flowing into it at build time, so a hop with no fresh cache
+ * entry (this module never asks a local carrier) and whose upstream amount
+ * has not moved since enumerate.ts computed it is STILL exactly what it
+ * always was — composing it as a scaled `'probeRate'` estimate would throw
+ * that precision away for no reason. Only when an EARLIER hop's amount has
+ * genuinely changed (a live aggregator answer landed upstream of this local
+ * hop) does this fall back to scaling the hop's own original rate, because
+ * this module has no way to re-run a local carrier's own closed-form math
+ * without asking it — see this branch's own comment, below.
+ *
+ * @param path - the plan to recompose
+ * @param startAmount - the reader's real amount entering the path's first hop
+ * @param askedAmountForHop - what amount each hop of `path` was (or would
+ *   be) asked at, by hop index
+ * @param cache - the edge answers gathered so far
+ * @returns the recomposed plan, with `hops[].outcome` refreshed
+ */
+const recomposePath = (path, startAmount, askedAmountForHop, cache) => {
+    const originalInputs = originalHopInputAmounts(path, startAmount);
+    const refusalReasonByHopIndex = [];
+    const composableHops = path.hops.map((hop, index) => {
+        const askedAmount = askedAmountForHop[index] ?? originalInputs[index] ?? startAmount;
+        const entry = lookupAnswer(cache, hop.edge, askedAmount);
+        if (entry !== null && entry.answer.ok) {
+            refusalReasonByHopIndex.push(null);
+            if (index === 0 && entry.askedAmount === askedAmount) {
+                return { edge: hop.edge, figure: { kind: 'quote', outputAmount: entry.answer.deliveredAmount } };
+            }
+            const rate = { numerator: entry.answer.deliveredAmount, denominator: entry.askedAmount };
+            return { edge: hop.edge, figure: { kind: 'probeRate', rate, basis: 'probe-rate' } };
+        }
+        refusalReasonByHopIndex.push(entry !== null && !entry.answer.ok ? (entry.answer.refusal.reason ?? entry.answer.refusal.kind) : null);
+        const originalInputForThisHop = originalInputs[index] ?? startAmount;
+        // See this function's own "STAYS A TRUE QUOTE" doc: a local hop's own
+        // upstream amount is unchanged, so its original exact figure still
+        // applies verbatim.
+        if (hop.outcome.kind === 'quote' && askedAmount === originalInputForThisHop) {
+            return { edge: hop.edge, figure: { kind: 'quote', outputAmount: hop.outcome.deliveredAmount } };
+        }
+        // No fresh answer, and either this hop is an `'estimate'` awaiting a live
+        // ask, or it is a `'quote'` local hop whose upstream amount has genuinely
+        // moved — the best available figure without a network ask is the hop's
+        // OWN original rate, scaled to the amount actually arriving now.
+        const fallbackBasis = hop.outcome.kind === 'estimate' ? hop.outcome.basis : 'probe-rate';
+        const rate = { numerator: hop.outcome.deliveredAmount, denominator: originalInputForThisHop };
+        return { edge: hop.edge, figure: { kind: 'probeRate', rate, basis: fallbackBasis } };
+    });
+    const composed = composeRouteDelivery(startAmount, composableHops);
+    if (composed.kind === 'refused') {
+        return path;
+    }
+    const firstHopMinimum = firstHopGuaranteedMinimum(path, askedAmountForHop, originalInputs, startAmount, cache);
+    const updatedHops = [];
+    let runningAmount = startAmount;
+    for (let index = 0; index < path.hops.length; index += 1) {
+        const hop = path.hops[index];
+        const figureHop = composableHops[index];
+        const deliveredAmount = hopOutputAmount(figureHop, runningAmount);
+        if (deliveredAmount === null) {
+            return path;
+        }
+        const minimumDeliveredAmount = index === 0 && figureHop.figure.kind === 'quote' ? firstHopMinimum : null;
+        // A FUSED HOP HANDS THE NEXT ONE EXACTLY ITS GUARANTEED MINIMUM. Its
+        // signature is an exact-output request whose target is that minimum (the
+        // entry call embeds the figure), so composing the next hop from the
+        // EXPECTED amount would show the reader more than the signed request can
+        // ever deliver. The difference stays in the reader's wallet unspent.
+        runningAmount = hop.edge.fusesNext && minimumDeliveredAmount !== null ? minimumDeliveredAmount : deliveredAmount;
+        const refusalReason = refusalReasonByHopIndex[index] ?? null;
+        const outcome = figureHop.figure.kind === 'quote'
+            ? minimumDeliveredAmount === null
+                ? { kind: 'quote', deliveredAmount }
+                : { kind: 'quote', deliveredAmount, minimumDeliveredAmount }
+            : refusalReason === null
+                ? { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis }
+                : { kind: 'estimate', deliveredAmount, basis: figureHop.figure.basis, refusalReason };
+        updatedHops.push({ ...hop, outcome });
+    }
+    return { ...path, hops: updatedHops };
+};
+/**
+ * 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 const planWithEntryTarget = (plan, entryTarget) => {
+    const firstHop = plan.hops[0];
+    if (firstHop === undefined || !firstHop.edge.fusesNext || firstHop.outcome.kind !== 'quote')
+        return null;
+    const minimum = firstHop.outcome.minimumDeliveredAmount;
+    if (minimum === undefined || entryTarget <= 0n || entryTarget > minimum)
+        return null;
+    if (entryTarget === minimum)
+        return plan;
+    const laterHops = [];
+    let handedOriginally = minimum;
+    let handedNow = entryTarget;
+    for (const hop of plan.hops.slice(1)) {
+        const rate = { numerator: hop.outcome.deliveredAmount, denominator: handedOriginally };
+        const deliveredAmount = hopOutputAmount({ edge: hop.edge, figure: { kind: 'probeRate', rate, basis: 'probe-rate' } }, handedNow);
+        if (deliveredAmount === null)
+            return null;
+        laterHops.push({ ...hop, outcome: { ...hop.outcome, deliveredAmount } });
+        handedOriginally = hop.outcome.deliveredAmount;
+        handedNow = deliveredAmount;
+    }
+    return { ...plan, hops: [firstHop, ...laterHops] };
+};
+/**
+ * Computes a {@link CalibrationDivergenceRecord} for one fresh live answer
+ * against its edge's pre-round estimate, or null when the estimate's own
+ * rate cannot be computed (a zero input amount) or the divergence does not
+ * clear {@link CALIBRATION_DIVERGENCE_RATIO_THRESHOLD}.
+ */
+const calibrationDivergence = (options) => {
+    const { edge, askedAmount, liveDeliveredAmount, estimatedDeliveredAmount, estimatedInputAmount } = options;
+    if (estimatedInputAmount <= 0n || askedAmount <= 0n)
+        return null;
+    const estimatedRate = Number(estimatedDeliveredAmount) / Number(estimatedInputAmount);
+    if (!Number.isFinite(estimatedRate) || estimatedRate === 0)
+        return null;
+    const liveRate = Number(liveDeliveredAmount) / Number(askedAmount);
+    const divergenceRatio = (liveRate - estimatedRate) / estimatedRate;
+    if (!Number.isFinite(divergenceRatio) || Math.abs(divergenceRatio) < CALIBRATION_DIVERGENCE_RATIO_THRESHOLD) {
+        return null;
+    }
+    return {
+        edge,
+        askedAmount,
+        liveDeliveredAmount,
+        estimatedDeliveredAmount,
+        estimatedInputAmount,
+        divergenceRatio,
+    };
+};
+/**
+ * Every aggregator edge's PRE-ROUND estimate, keyed by {@link hopEdgeKey} —
+ * built once per {@link searchRouteWaves} call from `paths`' own pristine
+ * hops, so a live answer landing later has something to compare against.
+ * Keeps the FIRST estimate seen for a given edge key; two paths reaching the
+ * same edge at two different (and so differently price-impacted) amounts is
+ * an accepted approximation here — see {@link CalibrationDivergenceRecord}'s
+ * own doc for what this feeds.
+ */
+const buildPreRoundEstimatesByEdgeKey = (paths, amount) => {
+    const estimates = new Map();
+    for (const path of paths) {
+        const inputs = originalHopInputAmounts(path, amount);
+        path.hops.forEach((hop, index) => {
+            if (!isRateLimitedCarrier(hop.edge.carrier))
+                return;
+            if (hop.outcome.kind !== 'estimate')
+                return;
+            const key = hopEdgeKey(hop.edge);
+            if (estimates.has(key))
+                return;
+            estimates.set(key, { inputAmount: inputs[index] ?? amount, deliveredAmount: hop.outcome.deliveredAmount });
+        });
+    }
+    return estimates;
+};
+/** Dedupes a list of planned asks by edge key + asked amount, keeping the first occurrence. */
+const dedupeAsks = (asks) => {
+    const seen = new Set();
+    const result = [];
+    for (const ask of asks) {
+        const key = `${hopEdgeKey(ask.edge)}#${ask.askedAmount.toString()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(ask);
+    }
+    return result;
+};
+/**
+ * Runs one dispatch: dedupes the asks, prunes any already floored, serves
+ * cache hits without a request (except an ask marked
+ * {@link PlannedAsk.requireExactAmount}), dispatches cache misses through the
+ * per-provider limiter, races the whole batch against a time budget, and
+ * reports any fresh answer that diverges from its own pre-round estimate.
+ *
+ * NO SHARED REQUEST COUNTER. Unlike the previous wave-based design, the
+ * asks handed to this function are ALREADY the exact, capped set a round's
+ * own selection step decided on (see {@link buildRoundAAsks}/
+ * {@link buildRoundBAsks}) — this function's only job is running them
+ * safely, not deciding how many to run.
+ *
+ * @returns every refusal freshly learned this round (cache hits are not
+ *   re-reported; they were reported the round they were first learned)
+ */
+const runDispatch = async (options) => {
+    const { asks, timeBudgetMs, askEdge, clock, cache, floors, limiter, preRoundEstimatesByEdgeKey, onCalibrationDivergence, inFlight, } = options;
+    const deduped = dedupeAsks(asks);
+    const freshRefusals = [];
+    const dispatchable = [];
+    for (const ask of deduped) {
+        const cachedEntry = cache.get(ask.edge, ask.askedAmount);
+        const cacheAnswersThisAsk = cachedEntry !== null && (ask.requireExactAmount !== true || cachedEntry.askedAmount === ask.askedAmount);
+        if (cacheAnswersThisAsk)
+            continue;
+        const floor = floors.read(ask.edge)[0];
+        if (floor !== undefined && floor.minimumAmount > ask.askedAmount) {
+            cache.set(ask.edge, ask.askedAmount, {
+                ok: false,
+                refusal: { kind: 'below-minimum', reason: floor.reason, minimumAmount: floor.minimumAmount },
+            });
+            continue;
+        }
+        dispatchable.push(ask);
+    }
+    const pendingSettlements = dispatchable.map((ask) => {
+        const inFlightKey = `${hopEdgeKey(ask.edge)}#${ask.askedAmount.toString()}`;
+        const alreadyAsking = inFlight.get(inFlightKey);
+        if (alreadyAsking !== undefined)
+            return alreadyAsking;
+        const limiterKey = ask.edge.carrier;
+        const limit = isRateLimitedCarrier(ask.edge.carrier)
+            ? providerConcurrencyLimit(ask.edge.carrier)
+            : Number.POSITIVE_INFINITY;
+        const settlement = limiter
+            .run(limiterKey, limit, () => askEdge({ edge: ask.edge, inputAmount: ask.askedAmount }))
+            .then((answer) => {
+            cache.set(ask.edge, ask.askedAmount, answer);
+            if (answer.ok) {
+                const estimate = preRoundEstimatesByEdgeKey.get(hopEdgeKey(ask.edge));
+                if (estimate !== undefined && onCalibrationDivergence !== undefined) {
+                    const record = calibrationDivergence({
+                        edge: ask.edge,
+                        askedAmount: ask.askedAmount,
+                        liveDeliveredAmount: answer.deliveredAmount,
+                        estimatedDeliveredAmount: estimate.deliveredAmount,
+                        estimatedInputAmount: estimate.inputAmount,
+                    });
+                    if (record !== null)
+                        onCalibrationDivergence(record);
+                }
+                return;
+            }
+            freshRefusals.push({ edge: ask.edge, askedAmount: ask.askedAmount, refusal: answer.refusal });
+            if (answer.refusal.minimumAmount !== null) {
+                floors.record(ask.edge, {
+                    reason: answer.refusal.reason ?? answer.refusal.kind,
+                    minimumAmount: answer.refusal.minimumAmount,
+                });
+            }
+        })
+            .catch(() => {
+            // An askEdge that rejects outright (rather than resolving to
+            // `{ok: false, ...}`) is treated as an unanswered edge: it stays
+            // absent from the cache, so the fallback estimate in
+            // `recomposePath` is used and nothing about the omission is
+            // recorded as a floor.
+        })
+            .finally(() => {
+            inFlight.delete(inFlightKey);
+        });
+        inFlight.set(inFlightKey, settlement);
+        return settlement;
+    });
+    await Promise.race([Promise.all(pendingSettlements), clock.after(timeBudgetMs)]);
+    return freshRefusals;
+};
+/**
+ * Stably moves every UNCONFIRMED plan (`planIsConfirmed` false) below every
+ * CONFIRMED one, keeping each group's own relative order from
+ * `compareRoutePlans` untouched. `Array.prototype.sort` is a STABLE sort
+ * (guaranteed since ECMAScript 2019), which is what makes this safe.
+ *
+ * @param ranked - plans already sorted by the search's own comparator
+ * @returns the same plans, confirmed ones first, each group's own order preserved
+ */
+const partitionConfirmedFirst = (ranked) => [...ranked].sort((a, b) => {
+    const confirmedA = planIsConfirmed(a.hops);
+    const confirmedB = planIsConfirmed(b.hops);
+    if (confirmedA === confirmedB)
+        return 0;
+    return confirmedA ? -1 : 1;
+});
+// ---------------------------------------------------------------------------
+// Pruning — an estimate that cannot beat the best confirmed route is dropped
+// ---------------------------------------------------------------------------
+/**
+ * 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 const ESTIMATE_ALLOWANCE_PPM_PER_ESTIMATED_HOP = 10000n;
+const PARTS_PER_MILLION = 1000000n;
+/**
+ * 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 const planBestCaseNetDelivery = (plan, gasCostFor) => {
+    if (!planIsRankable(plan.hops))
+        return null;
+    const deliveredAmount = plan.hops[plan.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
+    const estimatedHopCount = BigInt(plan.hops.filter((hop) => hop.outcome.kind === 'estimate').length);
+    const allowance = (deliveredAmount * ESTIMATE_ALLOWANCE_PPM_PER_ESTIMATED_HOP * estimatedHopCount) / PARTS_PER_MILLION;
+    return gasAdjustedDeliveredAmount(plan, gasCostFor) + allowance;
+};
+/**
+ * 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 const bestConfirmedNetDelivery = (plans, gasCostFor) => plans.reduce((best, plan) => {
+    if (!planIsConfirmed(plan.hops))
+        return best;
+    const net = gasAdjustedDeliveredAmount(plan, gasCostFor);
+    return best === null || net > best ? net : best;
+}, 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 const estimateCanStillWin = (plan, bestConfirmed, gasCostFor) => {
+    const bestCase = planBestCaseNetDelivery(plan, gasCostFor);
+    if (bestCase === null)
+        return false;
+    if (bestConfirmed === null)
+        return true;
+    return bestCase > bestConfirmed;
+};
+/**
+ * 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 const prunePathsThatCannotWin = (paths, gasCostFor) => {
+    const bestConfirmed = bestConfirmedNetDelivery(paths, gasCostFor);
+    if (bestConfirmed === null)
+        return paths;
+    return paths.filter((path) => planIsConfirmed(path.hops) || !planIsRankable(path.hops) || estimateCanStillWin(path, bestConfirmed, gasCostFor));
+};
+/**
+ * Splits plans already sorted best first into the two lists a search
+ * returns: every confirmed plan, and at most {@link MAX_ESTIMATED_CANDIDATES}
+ * unconfirmed ones that carry an estimate AND could still beat the best
+ * confirmed plan. Each list keeps the sorted order it was handed, so the
+ * estimates are the top five by estimated net output.
+ *
+ * @param ranked - plans sorted by the search's own comparator, best first
+ * @param gasCostFor - the real cost of one signature
+ * @returns the confirmed plans and the estimates worth showing
+ */
+const splitConfirmedAndEstimated = (ranked, gasCostFor) => {
+    const plans = ranked.filter((plan) => planIsConfirmed(plan.hops));
+    const bestConfirmed = bestConfirmedNetDelivery(plans, gasCostFor);
+    const estimatedCandidates = ranked
+        .filter((plan) => !planIsConfirmed(plan.hops) && estimateCanStillWin(plan, bestConfirmed, gasCostFor))
+        .slice(0, MAX_ESTIMATED_CANDIDATES);
+    return { plans, estimatedCandidates };
+};
+/**
+ * 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 const applyConfirmedCandidate = (result, plan, options) => {
+    const others = [...result.plans, ...result.estimatedCandidates].filter((entry) => entry.pathKey !== plan.pathKey);
+    const ranked = [...others, plan].sort(options.compareRoutePlans);
+    return { ...result, ...splitConfirmedAndEstimated(ranked, options.gasCostFor) };
+};
+// ---------------------------------------------------------------------------
+// Round selection — which paths' aggregator hops get asked, and in what order
+// ---------------------------------------------------------------------------
+/** Every hop index of `path` carried by a rate-limited (aggregator) carrier, in hop order. */
+const aggregatorHopIndices = (path) => path.hops.reduce((indices, hop, index) => {
+    if (isRateLimitedCarrier(hop.edge.carrier))
+        indices.push(index);
+    return indices;
+}, []);
+/** The amount flowing into hop `hopIndex` of `path`, from enumerate.ts's own pristine chain. */
+const originalAmountAtHop = (path, amount, hopIndex) => originalHopInputAmounts(path, amount)[hopIndex] ?? amount;
+/**
+ * Selects Round A's asks: each path's FIRST aggregator hop, in pre-screen
+ * order (`paths`' own order — `enumerate.ts`'s output), until each provider
+ * holds its own cap ({@link DEFAULT_PROVIDER_CONCURRENCY_LIMIT}/
+ * {@link NEAR_INTENTS_CONCURRENCY_LIMIT}) — WITH a diversity reservation: the
+ * best-ranked path per first-aggregator carrier, and the best-ranked path per
+ * signature count (1, 2, 3), are guaranteed a slot ahead of plain pre-screen
+ * fill, so a search dominated by one provider's paths still asks the other
+ * providers, and a search dominated by long paths still asks a short one.
+ *
+ * A path with no aggregator hop at all (every hop already exact) needs no
+ * Round A ask — it is simply absent from the result.
+ *
+ * @param paths - every candidate path, in pre-screen order
+ * @param amount - the reader's real amount entering each path's first hop
+ * @returns one candidate ask per selected path, never more than one per path
+ */
+const buildRoundAAsks = (paths, amount) => {
+    const candidates = [];
+    for (const path of paths) {
+        const hopIndex = aggregatorHopIndices(path)[0];
+        if (hopIndex === undefined)
+            continue;
+        const providerId = path.hops[hopIndex].edge.carrier;
+        candidates.push({ path, hopIndex, providerId, askedAmount: originalAmountAtHop(path, amount, hopIndex) });
+    }
+    const guaranteed = [];
+    const bestByProvider = new Map();
+    const bestBySignatureCount = new Map();
+    for (const candidate of candidates) {
+        if (!bestByProvider.has(candidate.providerId)) {
+            bestByProvider.set(candidate.providerId, candidate);
+            guaranteed.push(candidate);
+        }
+        const signatureCount = candidate.path.signatures.length;
+        if (signatureCount >= 1 && signatureCount <= 3 && !bestBySignatureCount.has(signatureCount)) {
+            bestBySignatureCount.set(signatureCount, candidate);
+            guaranteed.push(candidate);
+        }
+    }
+    const selected = [];
+    const selectedPathKeys = new Set();
+    const usedByProvider = new Map();
+    const tryAdd = (candidate) => {
+        if (selectedPathKeys.has(candidate.path.pathKey))
+            return;
+        const used = usedByProvider.get(candidate.providerId) ?? 0;
+        if (used >= providerConcurrencyLimit(candidate.providerId))
+            return;
+        selected.push(candidate);
+        selectedPathKeys.add(candidate.path.pathKey);
+        usedByProvider.set(candidate.providerId, used + 1);
+    };
+    for (const candidate of guaranteed)
+        tryAdd(candidate);
+    for (const candidate of candidates)
+        tryAdd(candidate);
+    return selected;
+};
+/**
+ * Selects Round B's asks: each ranked path's SECOND aggregator hop, asked at
+ * Round A's own guaranteed minimum for that path (propagated through any
+ * local-exact hops between the two aggregator hops), up to
+ * {@link ROUND_B_MAX_REQUESTS_PER_PROVIDER} per provider. Only a path whose
+ * FIRST aggregator hop already landed a live answer in Round A is eligible —
+ * a path Round A never reached (its provider's cap was already spent) has no
+ * guaranteed minimum to ask Round B's second hop against, so it is skipped
+ * here rather than asked at a stale estimate.
+ *
+ * @param rankedAfterRoundA - paths ranked by the search's own comparator
+ *   after Round A's answers were recomposed in — best first
+ * @param amount - the reader's real amount entering each path's first hop
+ * @param cache - the edge answers gathered so far (Round A's own answers)
+ * @returns one candidate ask per selected path, capped per provider
+ */
+const buildRoundBAsks = (rankedAfterRoundA, amount, cache) => {
+    const candidates = [];
+    for (const path of rankedAfterRoundA) {
+        const indices = aggregatorHopIndices(path);
+        const firstIndex = indices[0];
+        const secondIndex = indices[1];
+        if (firstIndex === undefined || secondIndex === undefined)
+            continue;
+        const firstAskedAmount = originalAmountAtHop(path, amount, firstIndex);
+        const firstEntry = cache.get(path.hops[firstIndex].edge, firstAskedAmount);
+        if (firstEntry === null || !firstEntry.answer.ok)
+            continue;
+        const propagated = propagatedHopInputAmounts(path, amount, cache);
+        const askedAmount = propagated[secondIndex] ?? originalAmountAtHop(path, amount, secondIndex);
+        const providerId = path.hops[secondIndex].edge.carrier;
+        candidates.push({ path, hopIndex: secondIndex, providerId, askedAmount });
+    }
+    const selected = [];
+    const usedByProvider = new Map();
+    for (const candidate of candidates) {
+        const used = usedByProvider.get(candidate.providerId) ?? 0;
+        if (used >= ROUND_B_MAX_REQUESTS_PER_PROVIDER)
+            continue;
+        selected.push(candidate);
+        usedByProvider.set(candidate.providerId, used + 1);
+    }
+    return selected;
+};
+/**
+ * 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 const searchRouteWaves = async (options) => {
+    const { amount, askEdge, gasCostFor = zeroGasCostFor, compareRoutePlans = compareRoutePlansByGasAdjustedDeliveredAmount(gasCostFor), clock = realWaveClock, edgeAnswerCache, floorsCache, onWaveSettled, onCalibrationDivergence, } = options;
+    // PRUNED BEFORE ANYTHING IS ASKED. A path whose best case cannot beat a
+    // route a local exact read already confirmed is never quoted and never
+    // shown — see `prunePathsThatCannotWin`.
+    const paths = prunePathsThatCannotWin(options.paths, gasCostFor);
+    const cache = edgeAnswerCache ?? createEdgeAnswerCache(clock);
+    const floors = floorsCache ?? createFloorsCache();
+    const limiter = new KeyedConcurrencyLimiter();
+    const inFlight = new Map();
+    const allRefusals = [];
+    const preRoundEstimatesByEdgeKey = buildPreRoundEstimatesByEdgeKey(paths, amount);
+    const pathsByKey = new Map(paths.map((path) => [path.pathKey, path]));
+    const dispatch = (asks, timeBudgetMs) => runDispatch({
+        asks,
+        timeBudgetMs,
+        askEdge,
+        clock,
+        cache,
+        floors,
+        limiter,
+        preRoundEstimatesByEdgeKey,
+        inFlight,
+        ...(onCalibrationDivergence === undefined ? {} : { onCalibrationDivergence }),
+    });
+    const recomposeAll = () => paths.map((path) => recomposePath(path, amount, propagatedHopInputAmounts(path, amount, cache), cache));
+    /**
+     * The next aggregator hop of `path` that has no usable answer yet, as an
+     * ask at the amount the hops before it now deliver — or null when every
+     * aggregator hop of the path already has one.
+     */
+    const nextUnansweredAsk = (path) => {
+        const propagated = propagatedHopInputAmounts(path, amount, cache);
+        const hopIndex = aggregatorHopIndices(path).find((index) => {
+            const askedAmount = propagated[index] ?? originalAmountAtHop(path, amount, index);
+            const entry = cache.get(path.hops[index].edge, askedAmount);
+            const satisfiesBinding = index === 0 ? entry !== null && entry.askedAmount === askedAmount : entry !== null;
+            return !satisfiesBinding;
+        });
+        if (hopIndex === undefined)
+            return null;
+        return {
+            edge: path.hops[hopIndex].edge,
+            askedAmount: propagated[hopIndex] ?? originalAmountAtHop(path, amount, hopIndex),
+            requireExactAmount: hopIndex === 0,
+        };
+    };
+    /**
+     * EVERY AGGREGATOR HOP, ONE AFTER ANOTHER — not only the next one. A later
+     * hop is asked at what the earlier one really delivers, so it cannot go
+     * first; but stopping after one ask (as this once did) left a path with two
+     * aggregator hops an estimate even after it came into view. It stops early
+     * only when an ask is refused or does not answer inside its budget: a
+     * later hop has no real input amount to be asked at then.
+     */
+    const confirmCandidate = async (pathKey) => {
+        const original = pathsByKey.get(pathKey);
+        if (original === undefined)
+            return null;
+        for (let asked = 0; asked < aggregatorHopIndices(original).length; asked += 1) {
+            const ask = nextUnansweredAsk(original);
+            if (ask === null)
+                break;
+            allRefusals.push(...(await dispatch([ask], CONFIRM_CANDIDATE_TIME_BUDGET_MS)));
+            const entry = cache.get(ask.edge, ask.askedAmount);
+            if (entry === null || !entry.answer.ok)
+                break;
+        }
+        return recomposePath(original, amount, propagatedHopInputAmounts(original, amount, cache), cache);
+    };
+    if (paths.length === 0) {
+        return { plans: [], estimatedCandidates: [], refusals: [], confirmCandidate };
+    }
+    // -- Round A --------------------------------------------------------------
+    const roundAAsks = buildRoundAAsks(paths, amount).map((candidate) => ({
+        edge: candidate.path.hops[candidate.hopIndex].edge,
+        askedAmount: candidate.askedAmount,
+        requireExactAmount: candidate.hopIndex === 0,
+    }));
+    allRefusals.push(...(await dispatch(roundAAsks, ROUND_A_TIME_BUDGET_MS)));
+    let ranked = [...recomposeAll()].sort(compareRoutePlans);
+    onWaveSettled?.({ round: 'A', plans: ranked });
+    // -- Round B --------------------------------------------------------------
+    const roundBAsks = buildRoundBAsks(ranked, amount, cache).map((candidate) => ({ edge: candidate.path.hops[candidate.hopIndex].edge, askedAmount: candidate.askedAmount }));
+    allRefusals.push(...(await dispatch(roundBAsks, ROUND_B_TIME_BUDGET_MS)));
+    ranked = [...recomposeAll()].sort(compareRoutePlans);
+    onWaveSettled?.({ round: 'B', plans: ranked });
+    return { ...splitConfirmedAndEstimated(partitionConfirmedFirst(ranked), gasCostFor), refusals: allRefusals, confirmCandidate };
+};