@gibs/bridge-sdk 1.13.1 → 1.17.0

package/dist/cjs/routing/search/graph.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareRoutePlansByDeliveredAmount = exports.groupHopsBySignature = exports.routePlanPathKey = exports.hopEdgeKey = exports.planIsConfirmed = exports.hopComposedBasis = exports.planComposedBasis = exports.isConfirmedBasis = exports.isRankableBasis = exports.combineComposedPathBasis = exports.planIsRankable = exports.RANKABLE_ESTIMATE_BASES = exports.isRateLimitedCarrier = exports.assetNodeKey = void 0;
+const ecosystems_js_1 = require("../../ecosystems.js");
+const providers_js_1 = require("../../providers.js");
+/**
+ * The stable, collision-free key for one {@link AssetNode}.
+ *
+ * Normalizes address casing through the ecosystem registry
+ * (`ecosystemById(...).addressCasing`) before keying, so a checksummed and a
+ * lower-cased reference to the SAME Ethereum address produce the SAME key —
+ * two representations of one asset must key identically, or the search would
+ * treat one node as two and silently duplicate work. An ecosystem whose
+ * addresses are case-SIGNIFICANT (Solana, Tron, The Open Network, Bitcoin,
+ * Zcash — see `ecosystems.ts`) is left exactly as given, because lower-casing
+ * a case-significant address can turn it into a different, unrelated one.
+ *
+ * Collision-free for any two distinct `(chainId, normalizedAddress)` pairs:
+ * `chainId` renders as a plain decimal numeral (never containing `:`), so the
+ * FIRST `:` in the key always marks the same boundary a caller would expect,
+ * and no two distinct pairs can render the same string.
+ *
+ * @param node - the asset to key
+ * @returns the node's graph key, e.g. `"1:0xa0b8...eb48"`
+ */
+const assetNodeKey = (node) => {
+    const casing = (0, ecosystems_js_1.ecosystemById)(node.ecosystem).addressCasing;
+    const normalizedAddress = casing === 'insensitive' ? node.address.toLowerCase() : node.address;
+    return `${node.chainId}:${normalizedAddress}`;
+};
+exports.assetNodeKey = assetNodeKey;
+/** Every registered rate-limited provider id (LI.FI, Relay, NEAR Intents), as a lookup set. */
+const registeredProviderIds = new Set(providers_js_1.providerRegistry.map((descriptor) => descriptor.id));
+/**
+ * Whether `carrier` is one of the three rate-limited aggregators
+ * (`ProviderId`) rather than a FREE local read (the omnibridge crossing or a
+ * PulseX swap). Free carriers are asked on EVERY wave without counting
+ * against `waves.ts`'s own request budget or per-provider concurrency cap —
+ * design section 3: "Bridge and PulseX hops are free local reads ... done
+ * exactly at any amount."
+ *
+ * CANONICAL HOME FOR THIS CHECK — PHASE 3. Moved here from `waves.ts` (which
+ * re-exports it) because {@link compareRoutePlansByDeliveredAmount}'s own
+ * tiebreak among unpriced plans needs it too (see that function's doc): a
+ * free-carrier first hop is guaranteed a real answer, a rate-limited one is
+ * not, and that distinction belongs on `HopCarrier` itself, not inside the
+ * one module that happened to need it first.
+ *
+ * @param carrier - the carrier to classify
+ * @returns true for `'lifi'`, `'relay'` or `'near-intents'`
+ */
+const isRateLimitedCarrier = (carrier) => registeredProviderIds.has(carrier);
+exports.isRateLimitedCarrier = isRateLimitedCarrier;
+/**
+ * The bases a ranking may compare a hop's `deliveredAmount` on — every
+ * {@link EstimateBasis} except `'unpriced'`. `'unpriced'` is EXCLUDED ON
+ * PURPOSE: it names a figure with no value behind it (see that member's own
+ * doc), and a ranking that compared on it would be comparing one path's real
+ * number against another path's decimal-shifted guess — exactly the defect
+ * shadow mode found. A caller checking whether a hop or a whole plan may
+ * enter a ranking reads this set (or calls {@link planIsRankable}), never a
+ * hand-rolled `!== 'unpriced'` check, so the one rule lives in one place.
+ *
+ * THIS IS A SEARCH-ORDER RULE, NOT A REPORTING RULE — PHASE 3, SECOND ROUND.
+ * `'priced-conversion'` stays in this set on purpose: `enumerate.ts`'s own
+ * cut and `waves.ts`'s between-wave top-candidate selection both need SOME
+ * way to compare two not-yet-quoted plans, and a price-feed conversion is a
+ * far better signal for THAT purpose than no signal at all. It is a
+ * DIFFERENT question whether a plan may be handed back to a reader as the
+ * winner while still carrying `'priced-conversion'` on any hop — it may not;
+ * see {@link isConfirmedBasis} and {@link planIsConfirmed}, the stricter pair
+ * `waves.ts`'s own final return step applies, for that rule and the live
+ * shadow-mode finding it closes (1 Zcash reported as 131.6 million Wrapped
+ * Pulse via `'priced-conversion'`, against a real 33.3 million from the
+ * pool's own `getAmountsOut` — a thin-pool price-impact gap `'priced-conversion'`
+ * cannot see, because it never asks the pool at all).
+ */
+exports.RANKABLE_ESTIMATE_BASES = new Set([
+    'probe-rate',
+    'priced-conversion',
+    'provider-model',
+]);
+/**
+ * Whether every hop of `hops` carries a figure a ranking may trust: a live
+ * quote, or an estimate whose {@link EstimateBasis} is in
+ * {@link RANKABLE_ESTIMATE_BASES} AND was never refused
+ * ({@link HopOutcome.refusalReason} is `null`/`undefined`). False the moment
+ * ANY hop is `'unpriced'` — one ungrounded hop taints the whole path's
+ * composed figure, because composition multiplies every hop's figure into
+ * the next (`compose.ts`), so a single meaningless number anywhere in the
+ * chain makes the FINAL delivered amount meaningless too, however real the
+ * other hops were.
+ *
+ * A REFUSED HOP IS UNRANKABLE EVEN WITH A GOOD BASIS. A hop that carries
+ * `'priced-conversion'` or `'probe-rate'` still fails this check once a real
+ * ask for it came back declined — see {@link HopOutcome.refusalReason}'s own
+ * doc for the shadow-mode finding this closes: a refused hop's leftover
+ * price-feed estimate has no fees behind it and kept beating real quotes,
+ * because a provider's own refusal was never checked before the hop's
+ * ORIGINAL basis was trusted again.
+ *
+ * A plan that fails this check is never dropped by this function — it is the
+ * CALLER's job to decide what "not yet known" means for it (excluded from
+ * being the ranked winner, but still held back in the list; see
+ * `waves.ts`'s and `useRouteSearch.ts`'s own comparators, both of which sort
+ * every unrankable plan below every rankable one rather than comparing raw
+ * amounts across the two groups).
+ *
+ * @param hops - the plan's hops
+ * @returns true when every hop's figure is trustworthy enough to rank on
+ */
+const planIsRankable = (hops) => hops.every((hop) => hop.outcome.kind === 'quote' ||
+    (exports.RANKABLE_ESTIMATE_BASES.has(hop.outcome.basis) && (hop.outcome.refusalReason ?? null) === null));
+exports.planIsRankable = planIsRankable;
+/** How much a ranking trusts each {@link ComposedPathBasis}, highest first — private to this module's own combination and rankability logic. */
+const COMPOSED_PATH_BASIS_RANK = {
+    quoted: 3,
+    'probe-rate': 2,
+    'priced-conversion': 1,
+    // SAME TIER AS `'priced-conversion'`, ON PURPOSE — both are rankable (see
+    // `RANKABLE_ESTIMATE_BASES`) but neither ever asked a real provider for
+    // THIS edge, so neither may report as a confirmed winner
+    // (`isConfirmedBasis` requires rank 2 or higher, `probe-rate`'s own tier).
+    'provider-model': 1,
+    unpriced: 0,
+};
+/**
+ * Combines two hops' (or two paths') bases into the basis their COMPOSITION
+ * deserves: the WORSE of the two, never the better one and never an average.
+ * A composed figure is a chain — `hop2`'s output is computed FROM `hop1`'s
+ * output — so if either link is `'unpriced'`, the number at the far end
+ * carries no value regardless of how solid the other link was. "Worst wins"
+ * is the only rule that keeps that true; picking the better basis (or the
+ * LAST hop's own basis, which an earlier draft of this reasoning tried) would
+ * let one grounded hop launder an ungrounded one earlier in the same chain.
+ *
+ * @param a - one basis being combined
+ * @param b - the other
+ * @returns whichever of `a`/`b` a ranking trusts less
+ */
+const combineComposedPathBasis = (a, b) => (COMPOSED_PATH_BASIS_RANK[a] <= COMPOSED_PATH_BASIS_RANK[b] ? a : b);
+exports.combineComposedPathBasis = combineComposedPathBasis;
+/**
+ * Whether a ranking may compare on `basis` — true for every
+ * {@link ComposedPathBasis} except `'unpriced'`. The whole-path counterpart to
+ * {@link RANKABLE_ESTIMATE_BASES}; see that constant's doc for the rule both
+ * enforce.
+ *
+ * @param basis - the composed path basis to check
+ * @returns false only for `'unpriced'`
+ */
+const isRankableBasis = (basis) => basis !== 'unpriced';
+exports.isRankableBasis = isRankableBasis;
+/**
+ * Whether a ranking may report `basis` as a WINNER — true only for
+ * `'quoted'` and `'probe-rate'`, i.e. {@link COMPOSED_PATH_BASIS_RANK} of 2 or
+ * higher. FALSE for `'priced-conversion'`, even though {@link isRankableBasis}
+ * accepts it — see that function's own "SEARCH-ORDER RULE, NOT A REPORTING
+ * RULE" note for why the two disagree on that one basis, on purpose.
+ *
+ * THE DEFECT THIS CLOSES. A live shadow comparison found 1 Zcash routed to
+ * Pulse (Wrapped) through the Binance Smart Chain omnibridge reported 131.6
+ * million Wrapped Pulse on `'priced-conversion'` — a United States dollar
+ * price-feed conversion that never asks the destination PulseX pool at all
+ * — while the pool's OWN `getAmountsOut` answers 33.3 million for the same
+ * size (86,540 per unit at 1 unit, 13,121 per unit at 1,500 units: an 84.8%
+ * worse rate at real size). `isRankableBasis` treated the two bases as
+ * equally trustworthy, so the price-feed number stood as the reported
+ * winner. `'priced-conversion'` IGNORES PRICE IMPACT BY CONSTRUCTION
+ * (`buildEstimateHopOutput`, `packages/ui/src/lib/state/useRouteSearch.ts`,
+ * converts through a flat United States dollar rate on each side, with no
+ * pool, no depth and no size in the computation) — it is not merely
+ * unconfirmed, it is blind to the one thing that broke here, so no amount of
+ * "it is probably close enough" reasoning can rescue it.
+ *
+ * WHY `'probe-rate'` IS STILL ACCEPTED HERE. A hop's basis is `'probe-rate'`
+ * ONLY WHEN A REAL PROVIDER (or a free local read — `getAmountsOut` included)
+ * ANSWERED THAT EXACT EDGE — see {@link HopOutcome}'s own doc and
+ * `waves.ts`'s `recomposePath`, whose fallback branch always carries forward
+ * a hop's ORIGINAL, pre-network basis (`'priced-conversion'`/`'unpriced'`,
+ * NEVER `'probe-rate'`) rather than inventing one. So a `'probe-rate'` hop is
+ * always grounded in a real, size-aware answer for SOME amount — the one
+ * residual imprecision is that `waves.ts`'s early waves may have asked it at
+ * an amount close to, but not exactly, the plan's final fully-propagated
+ * figure (see `waves.ts`'s own "confirmation pass" doc for how the final
+ * return step narrows that gap for a plan's TOP candidates before this
+ * function is ever consulted). A real answer at a slightly-off size still
+ * beats a number no provider was ever asked for at any size.
+ *
+ * @param basis - the composed path basis to check
+ * @returns true only for `'quoted'` and `'probe-rate'`
+ */
+const isConfirmedBasis = (basis) => COMPOSED_PATH_BASIS_RANK[basis] >= COMPOSED_PATH_BASIS_RANK['probe-rate'];
+exports.isConfirmedBasis = isConfirmedBasis;
+/**
+ * What grounds a WHOLE PLAN's delivered figure, read directly off its hops'
+ * own `outcome`s — the WORST (least-grounded) {@link ComposedPathBasis} across
+ * every hop, folded with {@link combineComposedPathBasis} exactly as
+ * `compose.ts`'s `composeRouteDelivery` folds one while a path is being
+ * actively composed.
+ *
+ * USE THIS ONCE A PLAN'S HOPS ALREADY CARRY THEIR FINAL `outcome`S — a
+ * finished `enumerate.ts`/`waves.ts` plan — rather than re-deriving a fresh
+ * `ComposedRouteDelivery` from scratch. `buildRouteScoreInputsFromPlan`
+ * (`plan-route-data.ts`) is the first caller, feeding `scoreRoutePlan`
+ * (`score.ts`) the one figure it needs to refuse ever scoring an unpriced
+ * plan as if its `deliveredUsd` meant anything.
+ *
+ * AGREES WITH {@link planIsRankable} BY CONSTRUCTION, NEVER BY COINCIDENCE:
+ * `isRankableBasis(planComposedBasis(hops)) === planIsRankable(hops)` for
+ * every plan, because "worst wins" and "true unless any hop is unpriced" are
+ * the same rule read two ways — see `graph.test.ts`'s own test pinning that
+ * equivalence so the two can never quietly drift apart.
+ *
+ * A REFUSED HOP FOLDS AS `'unpriced'`, WHATEVER ITS OWN `basis` SAYS — the
+ * same rule {@link planIsRankable} applies, read through
+ * {@link combineComposedPathBasis}'s "worst wins": a hop a real provider has
+ * declined is worse-grounded than any {@link EstimateBasis}, refused or not.
+ * This is WHY {@link isRankableBasis}`(planComposedBasis(hops)) === planIsRankable(hops)`
+ * still holds for every plan — see this function's own "AGREES WITH..." note
+ * below.
+ *
+ * @param hops - the plan's hops
+ * @returns the plan's composed basis; `'quoted'` (the fold's identity value)
+ *   for an empty plan
+ */
+const planComposedBasis = (hops) => hops.reduce((basis, hop) => (0, exports.combineComposedPathBasis)(basis, (0, exports.hopComposedBasis)(hop)), 'quoted');
+exports.planComposedBasis = planComposedBasis;
+/**
+ * The {@link ComposedPathBasis} one hop contributes to
+ * {@link planComposedBasis}'s fold: `'quoted'` for a live quote, `'unpriced'`
+ * for a REFUSED estimate regardless of its own `basis` (see
+ * {@link planComposedBasis}'s own "REFUSED HOP" note), else the estimate's
+ * own `basis`.
+ *
+ * EXPORTED FOR `waves.ts`'s OWN "confirmation pass" — the final step,
+ * described on {@link isConfirmedBasis}'s own doc, that upgrades a
+ * TOP-ranked plan's still-estimated free-carrier hops to a real quote before
+ * the search returns. That pass needs the SAME per-hop fold this function
+ * already applies (a hop a real provider has since refused is no better
+ * grounded than one that was never asked) to decide WHICH hops still need
+ * upgrading, so it reuses this rather than re-deriving the fold by hand.
+ */
+const hopComposedBasis = (hop) => {
+    if (hop.outcome.kind === 'quote')
+        return 'quoted';
+    if ((hop.outcome.refusalReason ?? null) !== null)
+        return 'unpriced';
+    return hop.outcome.basis;
+};
+exports.hopComposedBasis = hopComposedBasis;
+/**
+ * Whether every hop of `hops` carries a CONFIRMED figure — read straight off
+ * {@link planComposedBasis} through {@link isConfirmedBasis}, so this agrees
+ * with that function BY CONSTRUCTION, never by coincidence, exactly as
+ * {@link planIsRankable} agrees with {@link isRankableBasis} (see that pair's
+ * own "AGREES WITH" note above). STRICTER than {@link planIsRankable}: every
+ * confirmed plan is rankable, but a rankable plan carrying `'priced-conversion'`
+ * on any hop is not confirmed — see {@link isConfirmedBasis}'s own doc for why.
+ *
+ * USE THIS TO DECIDE WHAT A SEARCH MAY REPORT AS A WINNER. `waves.ts`'s own
+ * final return step is the one caller that PARTITIONS on this (confirmed
+ * plans ahead of unconfirmed ones, each group's own search-order preserved)
+ * — see that module's "confirmation pass" doc. NEVER use this to prune or
+ * rank DURING search: `planIsRankable` is still the correct predicate for
+ * `enumerate.ts`'s cut and `waves.ts`'s between-wave top-candidate
+ * selection, so `'priced-conversion'` keeps doing its job there exactly as
+ * before — see {@link RANKABLE_ESTIMATE_BASES}'s own "SEARCH-ORDER RULE, NOT
+ * A REPORTING RULE" note.
+ *
+ * @param hops - the plan's hops
+ * @returns true when every hop's figure is confirmed by a real ask
+ */
+const planIsConfirmed = (hops) => (0, exports.isConfirmedBasis)((0, exports.planComposedBasis)(hops));
+exports.planIsConfirmed = planIsConfirmed;
+/**
+ * Encodes one string as a length-prefixed ("netstring") segment: `"3:abc"`.
+ *
+ * WHY THIS AND NOT A DELIMITER. Joining segments with a fixed delimiter
+ * (`"|"`, `":"`, ...) collides whenever a segment can itself contain that
+ * delimiter — and a `HopEdge` key is built FROM asset addresses, which this
+ * module does not control the alphabet of. Prefixing each segment with its
+ * own length makes the boundary self-describing: reconstructing the segment
+ * count from the encoded string requires no assumption about what characters
+ * appear inside a segment, so two different segment sequences can never
+ * encode to the same string. See `graph.test.ts` for a worked collision that
+ * a plain delimiter join would produce and this does not.
+ *
+ * @param value - the segment to encode
+ * @returns the length-prefixed segment
+ */
+const netstringEncode = (value) => `${value.length}:${value}`;
+/**
+ * The stable, collision-free key for one {@link HopEdge}.
+ *
+ * The {@link HopEdge.venue}, when present, is a fourth segment: two venues
+ * between the same assets are two edges, so they must never share a key (a
+ * path deduplication or an answer cache would otherwise merge them). An edge
+ * with no venue keeps its three-segment key unchanged.
+ *
+ * @param edge - the edge to key
+ * @returns the edge's key, built from its carrier, its two node keys, and its venue when it has one
+ */
+const hopEdgeKey = (edge) => [edge.carrier, (0, exports.assetNodeKey)(edge.from), (0, exports.assetNodeKey)(edge.to), ...(edge.venue === undefined ? [] : [edge.venue])]
+    .map(netstringEncode)
+    .join('');
+exports.hopEdgeKey = hopEdgeKey;
+/**
+ * The stable, collision-free key for a whole path — the value
+ * {@link RoutePlan.pathKey} must hold.
+ *
+ * Two DIFFERENT hop sequences never produce the same key, and the SAME
+ * sequence always produces the same key, because each hop's key is
+ * length-prefixed before joining (see {@link netstringEncode}). This is what
+ * makes the key usable for deduplicating plans found by different search
+ * paths that happen to walk the same edges.
+ *
+ * @param hops - the plan's hops, first to last
+ * @returns the path's key
+ */
+const routePlanPathKey = (hops) => hops.map((hop) => netstringEncode((0, exports.hopEdgeKey)(hop.edge))).join('');
+exports.routePlanPathKey = routePlanPathKey;
+/**
+ * Groups a plan's hops into signature groups, as hop indices.
+ *
+ * THE ONE RULE: a hop whose PREDECESSOR fused it (`fusesNext` was true on the
+ * hop before it) joins that predecessor's group; every other hop — including
+ * the first — starts a new one. A pay-by-hand hop needs no special case
+ * either: {@link HopEdge.origin} only says how a hop is FUNDED, not whether it
+ * groups with what follows, and design section 1 is explicit that a
+ * pay-by-hand deposit "counts as one reader action but needs no wallet
+ * signature" — a fact for the ACTION count Phase 1's `score.ts` will compute
+ * (design section 4, the `A` term), not a fact about signature grouping.
+ *
+ * @param hops - the plan's hops, first to last
+ * @returns the hop index groups, in signature order — the outer array's
+ *   length is the plan's signature count
+ */
+const groupHopsBySignature = (hops) => {
+    const groups = [];
+    hops.forEach((_currentHop, index) => {
+        const previousHop = hops[index - 1];
+        const continuesPreviousGroup = previousHop !== undefined && previousHop.edge.fusesNext;
+        if (continuesPreviousGroup) {
+            groups[groups.length - 1]?.push(index);
+            return;
+        }
+        groups.push([index]);
+    });
+    return groups;
+};
+exports.groupHopsBySignature = groupHopsBySignature;
+/**
+ * Whether `plan`'s FIRST hop is a FREE carrier (the omnibridge crossing or a
+ * PulseX swap) rather than a rate-limited aggregator ({@link isRateLimitedCarrier}).
+ * A free first hop is asked on every wave of `waves.ts`'s own search
+ * unconditionally — never skipped for a spent request budget — so a plan
+ * with one is guaranteed a real answer; a rate-limited first hop competes
+ * with every other rate-limited ask for `WAVE_0_MAX_REQUESTS` and can be
+ * silently skipped when the budget runs out before it. {@link compareUnrankablePlans}
+ * is the one place this distinguishes two plans neither of which has a
+ * trustworthy figure yet.
+ *
+ * @param plan - the plan to classify
+ * @returns true when the plan's first hop is free, false for a rate-limited
+ *   first hop or an empty plan
+ */
+const firstHopIsFreeCarrier = (plan) => {
+    const firstHop = plan.hops[0];
+    return firstHop !== undefined && !(0, exports.isRateLimitedCarrier)(firstHop.edge.carrier);
+};
+/**
+ * Orders two UNRANKABLE plans (both fail {@link planIsRankable}) — PHASE 3,
+ * closing the gap `compareRoutePlansByDeliveredAmount` left: within this
+ * group `deliveredAmount` is not a real signal at all, it is a bare decimal
+ * rescale with no value behind it (`EstimateBasis`'s own doc), so an earlier
+ * version of that comparator fell back to comparing it anyway — an EMERGENT
+ * tiebreak that happened to work only because nothing else was tried. That
+ * let an entirely unrelated, equally-ungrounded plan win the enumeration
+ * cut's remaining slots (and `waves.ts`'s wave-0 request-budget priority,
+ * which reads plans in this same order) purely because its decimal point
+ * happened to land somewhere bigger — discarding, in the worst case, the
+ * price-feed-blind but perfectly real DIRECT omnibridge crossing in favour
+ * of aggregator noise.
+ *
+ * THE EXPLICIT RESERVATION, IN RANK ORDER:
+ *
+ * 1. A plan whose first hop is a FREE carrier ({@link firstHopIsFreeCarrier})
+ *    sorts ahead of one whose first hop is rate-limited — a free hop is
+ *    GUARANTEED a real wave-0 answer; a rate-limited one is only a maybe,
+ *    gated by a shared, exhaustible budget.
+ * 2. Within the same free-or-not group, fewer hops sorts first — a shorter
+ *    plan costs less of that shared budget to try and is simpler to execute,
+ *    matching this search's own hop/signature caps (design section 2).
+ * 3. A final, purely COSMETIC tiebreak — the plan's own stable `pathKey`,
+ *    lexicographically — keeps the comparator total and deterministic.
+ *    Never `deliveredAmount`: see this function's own head note for why.
+ *
+ * @param a - one unrankable plan being compared
+ * @param b - the other
+ * @returns negative when `a` ranks ahead of `b`, positive when `b` ranks
+ *   ahead of `a`, zero when they tie
+ */
+const compareUnrankablePlans = (a, b) => {
+    const freeFirstHopA = firstHopIsFreeCarrier(a);
+    const freeFirstHopB = firstHopIsFreeCarrier(b);
+    if (freeFirstHopA !== freeFirstHopB)
+        return freeFirstHopA ? -1 : 1;
+    if (a.hops.length !== b.hops.length)
+        return a.hops.length - b.hops.length;
+    if (a.pathKey === b.pathKey)
+        return 0;
+    return a.pathKey < b.pathKey ? -1 : 1;
+};
+/**
+ * THE ONE PLACE THIS COMPARATOR IS WRITTEN. Every rankable plan
+ * ({@link planIsRankable}) sorts ahead of every unrankable one, whatever its
+ * raw `deliveredAmount` claims to be — a QUOTABLE plan never loses its slot
+ * to one that is not, at the enumeration cut or anywhere else this
+ * comparator runs. Within the same rankability group: two RANKABLE plans
+ * compare on the larger last-hop delivered amount, a real signal; two
+ * UNRANKABLE plans compare with {@link compareUnrankablePlans} instead, per
+ * that function's own doc, because `deliveredAmount` carries no signal for
+ * that group at all. Bigint-safe throughout for the rankable branch — never
+ * widens to `Number`, which would lose precision on a large delivered amount
+ * long before the comparison needed it to.
+ *
+ * IMPORTED, NEVER RESTATED — PHASE 3's OWN CLOSE-THE-GAP RULE. Three
+ * independent call sites need exactly this rule: `enumerate.ts`'s own
+ * default (its top-N keep, applied to freshly enumerated plans — the SAME
+ * cut that decides which plans even reach `waves.ts`'s request budget),
+ * `waves.ts`'s default (its between-wave re-ranking), and
+ * `packages/ui/src/lib/state/useRouteSearch.ts`'s final sort. Before this
+ * function existed, two of those three each carried their own hand-written
+ * copy of the identical rule — a DRY violation that is also a correctness
+ * risk: a future edit to one copy (say, widening `RANKABLE_ESTIMATE_BASES`)
+ * could silently fail to reach the other, reopening the exact defect shadow
+ * mode measured (an unpriced 276 PLS outranking a priced 23 million PLS).
+ * Importing this one function everywhere a plan-to-plan comparison happens
+ * is what makes that drift structurally impossible rather than merely
+ * against convention.
+ *
+ * @param a - one plan being compared
+ * @param b - the other
+ * @returns negative when `a` ranks ahead of `b`, positive when `b` ranks
+ *   ahead of `a`, zero when they tie
+ */
+const compareRoutePlansByDeliveredAmount = (a, b) => {
+    const rankableA = (0, exports.planIsRankable)(a.hops);
+    const rankableB = (0, exports.planIsRankable)(b.hops);
+    if (rankableA !== rankableB)
+        return rankableA ? -1 : 1;
+    if (!rankableA)
+        return compareUnrankablePlans(a, b);
+    const amountA = a.hops[a.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
+    const amountB = b.hops[b.hops.length - 1]?.outcome.deliveredAmount ?? 0n;
+    if (amountA === amountB)
+        return 0;
+    return amountA > amountB ? -1 : 1;
+};
+exports.compareRoutePlansByDeliveredAmount = compareRoutePlansByDeliveredAmount;