@gibs/quotes 1.13.0

package/dist/search/enumerate.js

@@ -0,0 +1,313 @@
+import { isDepositAddressChain } from '@gibs/bridge-sdk/chain-names';
+import { assetNodeKey, compareRoutePlansByScoreAdjustedDeliveredAmount, groupHopsBySignature, hopEdgeKey, routePlanPathKey, } from '@gibs/bridge-sdk/routing';
+/**
+ * Depth-first search over a fixed node universe, pruning BEFORE anything is
+ * asked over the network (route search design, section 2). Everything here
+ * is pure: the node universe, the {@link CapabilityIndex}, the starting
+ * amount and the estimate function all arrive as arguments, and nothing is
+ * fetched — but a hop whose carrier answers through {@link Carrier.exact}
+ * (a synchronous LOCAL read, never a network call) carries a real `'quote'`
+ * outcome straight out of this module; every other hop carries an
+ * `'estimate'`, refined later by `waves.ts`'s live network asks.
+ *
+ * CARRIER-AGNOSTIC. Every prior version of this module special-cased ONE
+ * host's carriers directly (a hard-coded PulseX-only-runs-on-PulseChain
+ * check, and a hard-coded "only NEAR Intents may open a pay-by-hand
+ * origin"). Both are now the registering carrier's OWN job: `edgesFrom` only
+ * ever returns an edge for the pairs it can actually carry
+ * (`routing/carriers/pulsex.ts`'s own scoping, for gibs), and
+ * {@link Carrier.depositMode} states whether a carrier accepts a by-hand
+ * deposit — so this module never needs to know any carrier's NAME to enforce
+ * either rule, only the vocabulary every registered `Carrier` speaks.
+ */
+/** Depth cap: at most this many hops in one plan (design section 2, item 3). */
+export const DEFAULT_MAX_HOPS = 4;
+/** Signature cap: at most this many signature groups in one plan. */
+export const DEFAULT_MAX_SIGNATURES = 3;
+/**
+ * A hard, absolute ceiling on how many finished plans one
+ * {@link enumerateRoutes} call collects — a SAFETY VALVE, not a ranking cut.
+ * The owner's own routing model is "iterate through each possible pathway
+ * and order them by output": every path within `maxHops`/`maxSignatures` is
+ * enumerated and returned, sorted, with nothing trimmed to a top-N slice.
+ * This constant exists only to bound the search on a node universe
+ * pathological enough that the hop/signature caps alone do not keep it
+ * finite in practice; hitting it is a signal to revisit the node universe or
+ * the caps, not evidence that ranking picked correctly among what remained.
+ */
+export const MAX_ENUMERATED_PATHS = 10_000;
+/** Dedupes a node list by {@link assetNodeKey}, keeping the first occurrence. */
+const uniqueNodes = (nodes) => {
+    const seen = new Map();
+    for (const node of nodes) {
+        const key = assetNodeKey(node);
+        if (!seen.has(key)) {
+            seen.set(key, node);
+        }
+    }
+    return Array.from(seen.values());
+};
+/**
+ * Whether `node` sits on an Ethereum-Virtual-Machine chain — the one thing a
+ * deferred leg's start must be, because `deferredLeg.ts`'s `isComposableAddress`
+ * can only compose an address there (design section 2, item 2).
+ */
+const isEvmNode = (node) => node.ecosystem === 'evm';
+/**
+ * Decides what one candidate hop delivers, preferring the acting carrier's
+ * own {@link Carrier.exact} over its {@link Carrier.estimate} over the
+ * caller-supplied price-feed `estimateHopOutput` — the owner's own model:
+ * "each individual step and its associated fees can be known ahead of time
+ * ... you can at least start by getting their price for each token and their
+ * fee." Three guard-clause branches, no nesting:
+ *
+ * 1. `exact` defined — the carrier KNOWS its own math (the omnibridge
+ *    crossing, a PulseX swap). A `'delivered'` result becomes a `'quote'`
+ *    outcome; `null` (`'no-answer'`) or `'refused'` PRUNES the hop entirely
+ *    rather than falling through — a carrier that knows its own
+ *    exact math and says no is a firm refusal, not a number to estimate
+ *    around. A CARRIER WITH `exact` NEVER YIELDS AN `'estimate'` OUTCOME.
+ * 2. `estimate` defined (and `exact` was not) AND IT RETURNS A RESULT — the
+ *    carrier's own provider model answers, always grounded on the
+ *    `'provider-model'` {@link @gibs/bridge-sdk/routing!EstimateBasis}. A
+ *    carrier whose `estimate` returns `null` (most commonly: it has no price
+ *    for one side of this edge — see `types.ts`'s `Carrier.estimate` doc)
+ *    falls through to branch 3, exactly as if `estimate` were absent.
+ * 3. Neither, or `estimate` returned `null` — the caller's own price-feed
+ *    `estimateHopOutput` answers, exactly as it did before either method
+ *    existed.
+ *
+ * @param options - the acting carrier (if registered), the candidate edge, the input amount, and the price-feed fallback
+ * @returns the resolved delivered amount and outcome, the carrier's own refusal, or no answer
+ */
+const resolveHopOutcome = (options) => {
+    const { carrier, edge, amountIn, estimateHopOutput } = options;
+    if (carrier?.exact !== undefined) {
+        const exactResult = carrier.exact(edge, amountIn);
+        if (exactResult === null) {
+            return { kind: 'no-answer' };
+        }
+        if (exactResult.outcome === 'refused') {
+            return { kind: 'refused', refusal: exactResult.refusal };
+        }
+        return {
+            kind: 'delivered',
+            deliveredAmount: exactResult.deliveredAmount,
+            outcome: { kind: 'quote', deliveredAmount: exactResult.deliveredAmount },
+        };
+    }
+    if (carrier?.estimate !== undefined) {
+        const estimateResult = carrier.estimate(edge, amountIn);
+        if (estimateResult !== null) {
+            return {
+                kind: 'delivered',
+                deliveredAmount: estimateResult.deliveredAmount,
+                outcome: { kind: 'estimate', deliveredAmount: estimateResult.deliveredAmount, basis: 'provider-model' },
+            };
+        }
+    }
+    const { deliveredAmount, basis } = estimateHopOutput(edge, amountIn);
+    return { kind: 'delivered', deliveredAmount, outcome: { kind: 'estimate', deliveredAmount, basis } };
+};
+/**
+ * The venues one carrier offers between two nodes, read off the carrier's own
+ * `edgesFrom` — each a separate candidate hop, quoted and ranked on its own
+ * (see `HopEdge.venue`). A carrier whose edges name no venue yields the one
+ * venue-less candidate every carrier had before venues existed.
+ *
+ * Only edges the carrier says it performs under THIS id count: a registered
+ * view may answer `edgesFrom` for several ids.
+ *
+ * @param carrier - the registered carrier, or undefined when none is registered under `carrierId`
+ * @param carrierId - the id the capability index named for this pair
+ * @param from - the hop's input node
+ * @param to - the hop's output node
+ * @returns the distinct venues, or `[undefined]` when the carrier names none
+ */
+const venuesBetween = (carrier, carrierId, from, to) => {
+    if (carrier === undefined)
+        return [undefined];
+    const venues = new Set();
+    for (const edge of carrier.edgesFrom(from, to)) {
+        if (edge.carrier === carrierId && edge.venue !== undefined)
+            venues.add(edge.venue);
+    }
+    return venues.size === 0 ? [undefined] : [...venues];
+};
+/**
+ * Depth-first search from `options.origin` to `options.destination` over
+ * `options.nodes`, pruning every candidate hop before it is added and
+ * collecting every finished plan the hop/signature caps allow, up to the
+ * {@link MAX_ENUMERATED_PATHS} safety valve.
+ *
+ * PRUNING, APPLIED BEFORE A CANDIDATE HOP IS EVER ADDED (design section 2,
+ * item 2):
+ * - the carrier must support both nodes ({@link CapabilityIndex.carriersFrom});
+ * - no node is revisited within one plan;
+ * - the same carrier never runs twice in a row, whatever venue each hop names
+ *   (so one carrier never splits a hop across two of its own venues);
+ * - a pay-by-hand origin's first hop must be filled by a carrier whose
+ *   {@link Carrier.depositMode} accepts a by-hand deposit — `'by-hand-deposit'`
+ *   or `'either'`, never `'wallet-signed'` alone
+ *   ({@link isDepositAddressChain} is the pay-by-hand test);
+ * - a hop that starts a DEFERRED leg (every signature group after the first)
+ *   must start on an Ethereum-Virtual-Machine chain;
+ * - a known floor, if any, must be at or below the amount flowing into that
+ *   hop;
+ * - the acting carrier's own {@link Carrier.exact}, when it has one, must not
+ *   refuse the amount flowing into that hop ({@link resolveHopOutcome}); a
+ *   refusal it does give is handed to `onExactRefusal`, once per edge and
+ *   amount;
+ * - the plan must not exceed `maxHops` hops or `maxSignatures` signature
+ *   groups (grouped with {@link groupHopsBySignature}, reused rather than
+ *   re-derived, so a fused pair always counts as one signature here exactly
+ *   as it does everywhere else that reads a `RoutePlan`).
+ *
+ * A HOP'S `fusesNext` CANNOT BE KNOWN WHEN IT IS BUILT — it depends on the hop
+ * that follows it, which does not exist yet in a depth-first walk. So each
+ * hop is built provisionally with `fusesNext: false`, and is replaced with an
+ * updated copy (never mutated) the moment its successor is chosen, once
+ * {@link CapabilityIndex.fusesWithBridgeEntry} can actually answer.
+ *
+ * @param options - the search's endpoints, node universe, capability index and estimate function
+ * @returns every plan the caps allow, best first, never exceeding {@link MAX_ENUMERATED_PATHS}
+ */
+export const enumerateRoutes = (options) => {
+    const { origin, destination, amount, nodes, capabilities, estimateHopOutput, knownFloors = () => [], maxHops = DEFAULT_MAX_HOPS, maxSignatures = DEFAULT_MAX_SIGNATURES, compareRoutePlans = compareRoutePlansByScoreAdjustedDeliveredAmount, onExactRefusal, } = options;
+    const originKey = assetNodeKey(origin);
+    const destinationKey = assetNodeKey(destination);
+    if (originKey === destinationKey) {
+        return [];
+    }
+    const searchNodes = uniqueNodes([origin, destination, ...nodes]);
+    const found = [];
+    const foundPathKeys = new Set();
+    // The same edge is reached at the same amount by many paths; its refusal is
+    // one fact, reported once.
+    const reportedRefusalKeys = new Set();
+    const reportExactRefusal = (refusal) => {
+        if (onExactRefusal === undefined)
+            return;
+        const refusalKey = `${hopEdgeKey(refusal.edge)}#${refusal.askedAmount.toString()}`;
+        if (reportedRefusalKeys.has(refusalKey))
+            return;
+        reportedRefusalKeys.add(refusalKey);
+        onExactRefusal(refusal);
+    };
+    /**
+     * Extends the path ending at `currentNode` by one hop, over every candidate
+     * node and every carrier that connects them, recursing on whatever survives
+     * pruning.
+     *
+     * @param currentNode - where the path currently ends
+     * @param visitedKeys - every node key already used in this path
+     * @param hopsSoFar - the path's hops so far, last one's `fusesNext` still provisional
+     * @param currentAmount - the estimated amount available at `currentNode`
+     */
+    const visit = (currentNode, visitedKeys, hopsSoFar, currentAmount) => {
+        if (hopsSoFar.length >= maxHops || found.length >= MAX_ENUMERATED_PATHS) {
+            return;
+        }
+        const previousHop = hopsSoFar[hopsSoFar.length - 1];
+        for (const candidateNode of searchNodes) {
+            const candidateKey = assetNodeKey(candidateNode);
+            if (visitedKeys.has(candidateKey)) {
+                continue;
+            }
+            for (const carrier of capabilities.carriersFrom(currentNode, candidateNode)) {
+                for (const venue of venuesBetween(capabilities.carrierById(carrier), carrier, currentNode, candidateNode)) {
+                    // RE-CHECKED PER CANDIDATE, NOT ONLY AT `visit`'S OWN ENTRY — many
+                    // candidate hops (parallel carriers, or parallel venues of one
+                    // carrier, between the same pair of nodes) are walked inside ONE call
+                    // to `visit`, with no recursion between them, so the top-of-function
+                    // guard alone would never see the cap cross mid-loop.
+                    if (found.length >= MAX_ENUMERATED_PATHS) {
+                        return;
+                    }
+                    if (previousHop !== undefined && previousHop.edge.carrier === carrier) {
+                        continue;
+                    }
+                    const isFirstHop = hopsSoFar.length === 0;
+                    const depositMode = capabilities.carrierById(carrier)?.depositMode;
+                    const acceptsByHandDeposit = depositMode === 'by-hand-deposit' || depositMode === 'either';
+                    if (isFirstHop && isDepositAddressChain(origin.chainId) && !acceptsByHandDeposit) {
+                        continue;
+                    }
+                    const previousFusesThisHop = previousHop === undefined
+                        ? false
+                        : capabilities.fusesWithBridgeEntry({
+                            carrier: previousHop.edge.carrier,
+                            hopFrom: previousHop.edge.from,
+                            nextHopCarrier: carrier,
+                            nextHopFrom: currentNode,
+                            nextHopDestinationChainId: candidateNode.chainId,
+                        });
+                    const startsNewGroup = previousHop === undefined || !previousFusesThisHop;
+                    const startsDeferredLeg = startsNewGroup && !isFirstHop;
+                    if (startsDeferredLeg && !isEvmNode(currentNode)) {
+                        continue;
+                    }
+                    const floors = knownFloors({ carrier, from: currentNode, to: candidateNode });
+                    if (floors.some((floor) => floor.minimumAmount > currentAmount)) {
+                        continue;
+                    }
+                    const provisionalEdge = {
+                        carrier,
+                        from: currentNode,
+                        to: candidateNode,
+                        fusesNext: false,
+                        origin: isFirstHop && isDepositAddressChain(currentNode.chainId) ? 'by-hand' : 'wallet',
+                        floors,
+                        ...(venue === undefined ? {} : { venue }),
+                    };
+                    const resolved = resolveHopOutcome({
+                        carrier: capabilities.carrierById(carrier),
+                        edge: provisionalEdge,
+                        amountIn: currentAmount,
+                        estimateHopOutput,
+                    });
+                    if (resolved.kind === 'refused') {
+                        reportExactRefusal({ edge: provisionalEdge, askedAmount: currentAmount, refusal: resolved.refusal });
+                        continue;
+                    }
+                    if (resolved.kind === 'no-answer') {
+                        continue;
+                    }
+                    const { deliveredAmount, outcome } = resolved;
+                    const newHop = {
+                        edge: provisionalEdge,
+                        request: null,
+                        outcome,
+                    };
+                    const updatedHopsSoFar = previousHop === undefined
+                        ? [newHop]
+                        : [
+                            ...hopsSoFar.slice(0, -1),
+                            { ...previousHop, edge: { ...previousHop.edge, fusesNext: previousFusesThisHop } },
+                            newHop,
+                        ];
+                    if (groupHopsBySignature(updatedHopsSoFar).length > maxSignatures) {
+                        continue;
+                    }
+                    const newVisitedKeys = new Set(visitedKeys);
+                    newVisitedKeys.add(candidateKey);
+                    if (candidateKey === destinationKey) {
+                        const pathKey = routePlanPathKey(updatedHopsSoFar);
+                        if (!foundPathKeys.has(pathKey)) {
+                            foundPathKeys.add(pathKey);
+                            found.push({
+                                hops: updatedHopsSoFar,
+                                signatures: groupHopsBySignature(updatedHopsSoFar),
+                                pathKey,
+                            });
+                        }
+                        continue;
+                    }
+                    visit(candidateNode, newVisitedKeys, updatedHopsSoFar, deliveredAmount);
+                }
+            }
+        }
+    };
+    visit(origin, new Set([originKey]), [], amount);
+    return found.sort(compareRoutePlans);
+};

package/dist/search/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The route-search maximization engine: "get every quote, then pick the most
+ * tokens out for the fewest steps." Carrier-agnostic — see
+ * `docs/quote-service.md`'s "Carriers" section. A host registers whatever
+ * `Carrier`s (`../types.js`) it wants searched over; nothing in this
+ * directory names a host's own carrier.
+ *
+ * The pure graph data model (`AssetNode`, `HopEdge`, `RoutePlan`, ...) and
+ * the composition/scoring math stay in `@gibs/bridge-sdk/routing` — see that
+ * package's `routing/index.ts` for why this package cannot import them back
+ * the other way (a circular package dependency) and re-exports them under
+ * its own `Carrier*` names in `../types.js` instead.
+ */
+export * from './capabilities.js';
+export * from './enumerate.js';
+export * from './serve.js';
+export * from './waves.js';

package/dist/search/index.js

@@ -0,0 +1,17 @@
+/**
+ * The route-search maximization engine: "get every quote, then pick the most
+ * tokens out for the fewest steps." Carrier-agnostic — see
+ * `docs/quote-service.md`'s "Carriers" section. A host registers whatever
+ * `Carrier`s (`../types.js`) it wants searched over; nothing in this
+ * directory names a host's own carrier.
+ *
+ * The pure graph data model (`AssetNode`, `HopEdge`, `RoutePlan`, ...) and
+ * the composition/scoring math stay in `@gibs/bridge-sdk/routing` — see that
+ * package's `routing/index.ts` for why this package cannot import them back
+ * the other way (a circular package dependency) and re-exports them under
+ * its own `Carrier*` names in `../types.js` instead.
+ */
+export * from './capabilities.js';
+export * from './enumerate.js';
+export * from './serve.js';
+export * from './waves.js';

package/dist/search/serve.d.ts

@@ -0,0 +1,178 @@
+import { type ComposedRouteVerdict, type PlannedHop, type RoutePlan } from '@gibs/bridge-sdk/routing';
+/**
+ * Decides whether a priced {@link RoutePlan} may be served to a reader as a
+ * route they can sign — the boundary between the route-search engine
+ * (`enumerate.ts`, `waves.ts`) and a host's own execution flow.
+ *
+ * HOST-AGNOSTIC. This file names no carrier, no chain, and no host. It reads
+ * only the plan's own structure and the facts the caller passes in
+ * {@link ServableContext}. A host decides what to DO with a `'withheld'`
+ * verdict (grey the route out, hide it, show a reason) and what to do with a
+ * `'servable'` one (build the real signing request for
+ * {@link ServableVerdict.firstSectionRequest}); this file only judges.
+ *
+ * ONE PLAN, ONE VERDICT. Call {@link servableVerdict} again whenever the plan
+ * or the context changes — a fresh quote, a new gas balance, a new recipient.
+ * This module keeps no state of its own.
+ */
+/**
+ * Who — or what — signs a plan's FIRST section.
+ *
+ * `'by-hand'` — the reader sends funds to a deposit address. No wallet
+ * transaction starts this section.
+ *
+ * `'rate-limited-provider'` — a rate-limited aggregator carries the first
+ * hop ({@link isRateLimitedCarrier}). A host must go get a fresh, binding
+ * quote from that provider before it can build a signable transaction.
+ *
+ * `'free-carrier'` — a free, local carrier (a bridge read, a pool read)
+ * carries the first hop. A host can build the signable transaction directly,
+ * with no external quote request first.
+ */
+export type PlanFirstLegKind = 'by-hand' | 'rate-limited-provider' | 'free-carrier';
+/**
+ * Reads {@link PlanFirstLegKind} off a plan's FIRST hop only.
+ *
+ * THE OLD `derivePlanKind` (`@gibs/bridge-sdk`'s `plan-route-data.ts`) READS
+ * THE WRONG HOP FOR THIS QUESTION. It answers `'conversion'` when the plan's
+ * LAST hop is a swap — a fact about how the journey ENDS, useful for a
+ * section label, useless for deciding who signs FIRST. A three-hop plan that
+ * starts with an aggregator and ends with a swap reads `'conversion'` from
+ * `derivePlanKind`, which tells a host nothing about what the very first
+ * signature needs. This function asks a narrower, serving-specific question
+ * — "what starts section one?" — and reads only `plan.hops[0]`.
+ *
+ * @param plan - the plan to classify
+ * @returns the first section's signer kind
+ */
+export declare const planFirstLegKind: (plan: RoutePlan) => PlanFirstLegKind;
+/**
+ * Checks a structural fact about a plan: does each section start on the
+ * exact asset the PREVIOUS section ended on?
+ *
+ * WHY THIS CAN EVER BE FALSE. `enumerate.ts` only ever builds a plan whose
+ * hops already chain this way — a depth-first walk cannot skip a node. This
+ * check exists for a plan this module did NOT build itself: one assembled by
+ * hand, by a test, or by a future caller that composes a plan from pieces.
+ * {@link servableVerdict} treats a `false` result as a defect in whatever
+ * built the plan, not a business reason to withhold it — see that function's
+ * own doc.
+ *
+ * @param plan - the plan to check
+ * @returns true when every section's first hop starts where the previous
+ *   section's last hop landed; true trivially for a one-section plan
+ */
+export declare const sectionHandoverAgrees: (plan: RoutePlan) => boolean;
+/** What a host must go build once {@link servableVerdict} clears a plan's first section. */
+export type FirstSectionRequest = {
+    /** The plan's first signature group's hops, first to last. */
+    readonly hops: readonly PlannedHop[];
+    /** The reader's real, typed amount entering the very first hop, in that hop's `from` node's base units. */
+    readonly inputAmount: bigint;
+};
+/** Why {@link servableVerdict} withheld a plan. One reason per verdict — the first check that fails wins. */
+export type ServableWithheldReason = {
+    /** No hop of the plan has a live, provider-confirmed figure yet — see `planIsConfirmed`. */
+    readonly kind: 'unconfirmed';
+} | {
+    /** The plan asks for more signatures than the owner allows. */
+    readonly kind: 'too-many-signatures';
+    readonly signatureCount: number;
+    readonly maxSignatures: number;
+} | {
+    /**
+     * A section other than the first starts on a chain the reader holds no
+     * native gas on, and the hop landing there does not deliver native
+     * coin either — so the reader would have nothing to pay that section's
+     * own signature with.
+     */
+    readonly kind: 'gasless-middle-chain';
+    readonly chainId: number;
+} | {
+    /**
+     * The reader named a recipient other than their own wallet for a
+     * section that is NOT the plan's last one. Only the last section may
+     * carry a custom recipient — every earlier section must land back in
+     * the reader's own wallet, because the reader still has to sign the
+     * next section from wherever the previous one landed.
+     */
+    readonly kind: 'middle-recipient-not-reader';
+    readonly sectionIndex: number;
+} | {
+    /** A composed, multi-signature plan failed (or has not yet passed) the value-loss gate. */
+    readonly kind: 'quality';
+    readonly verdict: ComposedRouteVerdict | null;
+};
+/** The verdict {@link servableVerdict} returns. */
+export type ServableVerdict = {
+    readonly kind: 'servable';
+    /** What a host needs to go build a real, signable request for the plan's first section. */
+    readonly firstSectionRequest: FirstSectionRequest;
+    /** Who signs the first section. */
+    readonly leg: PlanFirstLegKind;
+} | {
+    readonly kind: 'withheld';
+    readonly reason: ServableWithheldReason;
+};
+/** Owner decision, 2026-09-23: "minimize the steps, but if you have to go through 3 ... that is what you have to do." */
+export declare const MAX_SERVABLE_SIGNATURES = 3;
+/** Everything {@link servableVerdict} needs beyond the plan's own structure — every fact a host, never this module, measures. */
+export type ServableContext = {
+    /** The reader's real, typed amount entering the plan's first hop. */
+    readonly amount: bigint;
+    /**
+     * Chain ids the reader holds no native gas on right now, from a live
+     * wallet balance read. A chain absent from this set is treated as funded.
+     */
+    readonly gaslessChainIds: ReadonlySet<number>;
+    /**
+     * Section indices (0-based, into `plan.signatures`) where the reader named
+     * a recipient other than their own connected wallet. Only the plan's LAST
+     * section index may legitimately appear here.
+     */
+    readonly customRecipientSectionIndexes: ReadonlySet<number>;
+    /**
+     * The composed-route quality verdict for this plan (`assessComposedRoute`,
+     * `@gibs/bridge-sdk/routing`). Read only when the plan has more than one
+     * signature — a single-signature plan strands the reader nowhere between
+     * signatures, so the gate this verdict feeds does not apply to it. `null`
+     * or omitted means "not priced yet," which withholds a multi-signature
+     * plan exactly as a `'rejected'` verdict would.
+     */
+    readonly qualityVerdict?: ComposedRouteVerdict | null;
+    /** Overrides the signature-count ceiling. Defaults to {@link MAX_SERVABLE_SIGNATURES}. */
+    readonly maxSignatures?: number;
+};
+/**
+ * Decides whether `plan` may be served to a reader as a route they can sign
+ * right now, against the five reasons a route can be held back:
+ *
+ * 1. **`unconfirmed`** — some hop still rests on an estimate, not a live
+ *    quote (`planIsConfirmed`).
+ * 2. **`too-many-signatures`** — more signature groups than
+ *    {@link ServableContext.maxSignatures} allows.
+ * 3. **`middle-recipient-not-reader`** — a non-last section would land
+ *    somewhere other than the reader's own wallet.
+ * 4. **`gasless-middle-chain`** — a non-first section starts on a chain the
+ *    reader cannot pay gas on, and nothing lands native coin there to cover
+ *    it.
+ * 5. **`quality`** — a composed, multi-signature plan fails the value-loss
+ *    gate (`assessComposedRoute`).
+ *
+ * Checked in that order; the first failing check is the reason returned. A
+ * plan that clears all five is `'servable'`, carrying the first section's
+ * hops and the first-hop signer kind ({@link planFirstLegKind}) so a host can
+ * go build the real signing request.
+ *
+ * THROWS, RATHER THAN RETURNING A VERDICT, FOR A MALFORMED PLAN — an empty
+ * plan, or one that fails {@link sectionHandoverAgrees}. Both name a defect
+ * in whatever BUILT the plan, not a business reason to withhold a route a
+ * reader could otherwise take; see `toHeadlineProviderKey` in
+ * `@gibs/bridge-sdk`'s `plan-route-data.ts` for the same pattern applied to
+ * the same class of fault.
+ *
+ * @param plan - the plan to judge
+ * @param context - the live facts this module cannot measure on its own
+ * @returns the verdict
+ */
+export declare const servableVerdict: (plan: RoutePlan, context: ServableContext) => ServableVerdict;

package/dist/search/serve.js

@@ -0,0 +1,142 @@
+import { isNativeAsset } from '@gibs/bridge-sdk/ecosystems';
+import { assetNodeKey, composedRouteMayBeOffered, isRateLimitedCarrier, planIsConfirmed, } from '@gibs/bridge-sdk/routing';
+/**
+ * Reads {@link PlanFirstLegKind} off a plan's FIRST hop only.
+ *
+ * THE OLD `derivePlanKind` (`@gibs/bridge-sdk`'s `plan-route-data.ts`) READS
+ * THE WRONG HOP FOR THIS QUESTION. It answers `'conversion'` when the plan's
+ * LAST hop is a swap — a fact about how the journey ENDS, useful for a
+ * section label, useless for deciding who signs FIRST. A three-hop plan that
+ * starts with an aggregator and ends with a swap reads `'conversion'` from
+ * `derivePlanKind`, which tells a host nothing about what the very first
+ * signature needs. This function asks a narrower, serving-specific question
+ * — "what starts section one?" — and reads only `plan.hops[0]`.
+ *
+ * @param plan - the plan to classify
+ * @returns the first section's signer kind
+ */
+export const planFirstLegKind = (plan) => {
+    const firstHop = plan.hops[0];
+    if (firstHop === undefined) {
+        throw new Error('planFirstLegKind: a plan needs at least one hop');
+    }
+    if (firstHop.edge.origin === 'by-hand') {
+        return 'by-hand';
+    }
+    return isRateLimitedCarrier(firstHop.edge.carrier) ? 'rate-limited-provider' : 'free-carrier';
+};
+// ---------------------------------------------------------------------------
+// sectionHandoverAgrees
+// ---------------------------------------------------------------------------
+/**
+ * Checks a structural fact about a plan: does each section start on the
+ * exact asset the PREVIOUS section ended on?
+ *
+ * WHY THIS CAN EVER BE FALSE. `enumerate.ts` only ever builds a plan whose
+ * hops already chain this way — a depth-first walk cannot skip a node. This
+ * check exists for a plan this module did NOT build itself: one assembled by
+ * hand, by a test, or by a future caller that composes a plan from pieces.
+ * {@link servableVerdict} treats a `false` result as a defect in whatever
+ * built the plan, not a business reason to withhold it — see that function's
+ * own doc.
+ *
+ * @param plan - the plan to check
+ * @returns true when every section's first hop starts where the previous
+ *   section's last hop landed; true trivially for a one-section plan
+ */
+export const sectionHandoverAgrees = (plan) => {
+    for (let sectionIndex = 1; sectionIndex < plan.signatures.length; sectionIndex += 1) {
+        const previousGroup = plan.signatures[sectionIndex - 1];
+        const currentGroup = plan.signatures[sectionIndex];
+        if (previousGroup === undefined || currentGroup === undefined)
+            return false;
+        const previousLastHop = plan.hops[previousGroup[previousGroup.length - 1] ?? -1];
+        const currentFirstHop = plan.hops[currentGroup[0] ?? -1];
+        if (previousLastHop === undefined || currentFirstHop === undefined)
+            return false;
+        if (assetNodeKey(previousLastHop.edge.to) !== assetNodeKey(currentFirstHop.edge.from))
+            return false;
+    }
+    return true;
+};
+/** Owner decision, 2026-09-23: "minimize the steps, but if you have to go through 3 ... that is what you have to do." */
+export const MAX_SERVABLE_SIGNATURES = 3;
+/**
+ * Decides whether `plan` may be served to a reader as a route they can sign
+ * right now, against the five reasons a route can be held back:
+ *
+ * 1. **`unconfirmed`** — some hop still rests on an estimate, not a live
+ *    quote (`planIsConfirmed`).
+ * 2. **`too-many-signatures`** — more signature groups than
+ *    {@link ServableContext.maxSignatures} allows.
+ * 3. **`middle-recipient-not-reader`** — a non-last section would land
+ *    somewhere other than the reader's own wallet.
+ * 4. **`gasless-middle-chain`** — a non-first section starts on a chain the
+ *    reader cannot pay gas on, and nothing lands native coin there to cover
+ *    it.
+ * 5. **`quality`** — a composed, multi-signature plan fails the value-loss
+ *    gate (`assessComposedRoute`).
+ *
+ * Checked in that order; the first failing check is the reason returned. A
+ * plan that clears all five is `'servable'`, carrying the first section's
+ * hops and the first-hop signer kind ({@link planFirstLegKind}) so a host can
+ * go build the real signing request.
+ *
+ * THROWS, RATHER THAN RETURNING A VERDICT, FOR A MALFORMED PLAN — an empty
+ * plan, or one that fails {@link sectionHandoverAgrees}. Both name a defect
+ * in whatever BUILT the plan, not a business reason to withhold a route a
+ * reader could otherwise take; see `toHeadlineProviderKey` in
+ * `@gibs/bridge-sdk`'s `plan-route-data.ts` for the same pattern applied to
+ * the same class of fault.
+ *
+ * @param plan - the plan to judge
+ * @param context - the live facts this module cannot measure on its own
+ * @returns the verdict
+ */
+export const servableVerdict = (plan, context) => {
+    if (plan.hops.length === 0 || plan.signatures.length === 0) {
+        throw new Error('servableVerdict: a plan needs at least one hop');
+    }
+    if (!sectionHandoverAgrees(plan)) {
+        throw new Error('servableVerdict: a section does not start where the previous one landed');
+    }
+    if (!planIsConfirmed(plan.hops)) {
+        return { kind: 'withheld', reason: { kind: 'unconfirmed' } };
+    }
+    const maxSignatures = context.maxSignatures ?? MAX_SERVABLE_SIGNATURES;
+    if (plan.signatures.length > maxSignatures) {
+        return {
+            kind: 'withheld',
+            reason: { kind: 'too-many-signatures', signatureCount: plan.signatures.length, maxSignatures },
+        };
+    }
+    const lastSectionIndex = plan.signatures.length - 1;
+    for (const sectionIndex of context.customRecipientSectionIndexes) {
+        if (sectionIndex !== lastSectionIndex) {
+            return { kind: 'withheld', reason: { kind: 'middle-recipient-not-reader', sectionIndex } };
+        }
+    }
+    for (let sectionIndex = 1; sectionIndex < plan.signatures.length; sectionIndex += 1) {
+        const previousGroup = plan.signatures[sectionIndex - 1];
+        const landingHop = plan.hops[previousGroup[previousGroup.length - 1]];
+        const landingNode = landingHop.edge.to;
+        const landsNativeCoin = isNativeAsset(landingNode.address, landingNode.ecosystem);
+        if (!landsNativeCoin && context.gaslessChainIds.has(landingNode.chainId)) {
+            return { kind: 'withheld', reason: { kind: 'gasless-middle-chain', chainId: landingNode.chainId } };
+        }
+    }
+    if (plan.signatures.length > 1) {
+        const verdict = context.qualityVerdict ?? null;
+        const passesQualityGate = verdict !== null && composedRouteMayBeOffered(verdict);
+        if (!passesQualityGate) {
+            return { kind: 'withheld', reason: { kind: 'quality', verdict } };
+        }
+    }
+    const firstGroup = plan.signatures[0];
+    const firstSectionHops = firstGroup.map((hopIndex) => plan.hops[hopIndex]);
+    return {
+        kind: 'servable',
+        firstSectionRequest: { hops: firstSectionHops, inputAmount: context.amount },
+        leg: planFirstLegKind(plan),
+    };
+};