@adaptic/utils 0.0.1037 → 0.0.1039

package/dist/index.cjs

@@ -10090,6 +10090,160 @@ class AlpacaMarketDataAPI extends require$$0$4.EventEmitter {
 // Export the singleton instance
 const marketDataAPI = AlpacaMarketDataAPI.getInstance();
 
+/**
+ * Alpaca's hard upper limit for `trail_percent` on trailing-stop orders.
+ * Submissions exceeding this value are rejected with HTTP 422 / code 42210000
+ * ("trail_percent must be <= 25"). See:
+ * https://docs.alpaca.markets/reference/postorder
+ */
+const ALPACA_MAX_TRAIL_PERCENT = 25;
+
+/**
+ * Trailing-stop replace-unit contract.
+ *
+ * Alpaca's order replace (`PATCH /v2/orders/{id}`) takes a single unitless
+ * `trail` field. The broker reads it in the unit of the ORIGINAL order: a
+ * `trail_percent` order reads `trail` as a percent, a `trail_price` order
+ * reads it as dollars. A replace cannot change the unit. A caller that holds
+ * a distance in one unit must therefore resolve it against the resting
+ * order's unit before the replace, or the broker stores the number in the
+ * other unit: a $22 dollar distance becomes a 22% trail.
+ *
+ * This module is the pure resolution step. It never guesses a unit, never
+ * defaults a reference price, and refuses rather than send a value the broker
+ * would reject or treat as effectively zero.
+ */
+/**
+ * Smallest `trail_percent` this module will send. Below it the trail is a
+ * rounding artefact of the broker's tick grid rather than a protective
+ * distance, so a conversion landing under it is refused.
+ */
+const MIN_CONVERTED_TRAIL_PERCENT = 0.1;
+/** Percent values are sent to the broker at hundredths of a percent. */
+const PERCENT_DECIMALS_SCALE = 100;
+/** A ratio expressed in percent. */
+const PERCENT_PER_UNIT = 100;
+/**
+ * Thrown when a trail replace cannot be expressed in the resting order's unit
+ * without guessing. No replace is sent; the resting stop keeps protecting.
+ */
+class TrailUnitConversionRefusedError extends AdapticUtilsError {
+    /** The order the replace targeted. */
+    orderId;
+    /** Why the replace was refused. */
+    reason;
+    /** The converted percent, or `null` when no conversion was computed. */
+    pct;
+    /** The conversion reference price, or `null` when none was usable. */
+    ref;
+    constructor(params) {
+        super(`Trailing stop replace refused for ${params.orderId} (${params.reason}): ${params.detail}`, "TRAIL_UNIT_REFUSED", "alpaca", false);
+        this.orderId = params.orderId;
+        this.reason = params.reason;
+        this.pct = params.pct;
+        this.ref = params.ref;
+    }
+}
+/** Parse a broker decimal string; `null` when absent, non-finite or not positive. */
+function positiveOrNull(value) {
+    if (value === null || value === undefined || value === "") {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+ * Read the unit a resting trailing-stop order trails in.
+ *
+ * @param order - The resting order as returned by the broker.
+ * @returns `"price"` for a dollar trail, `"percent"` for a percent trail, or
+ *   `null` when neither (or both) unit fields carry a positive value.
+ */
+function readTrailUnit(order) {
+    const hasPrice = positiveOrNull(order.trail_price) !== null;
+    const hasPercent = positiveOrNull(order.trail_percent) !== null;
+    if (hasPrice === hasPercent) {
+        return null;
+    }
+    return hasPrice ? "price" : "percent";
+}
+/**
+ * Resolve the replace `trail` value for a requested trail against the resting
+ * order's unit.
+ *
+ * - A dollar distance on a dollar order is sent unchanged.
+ * - A dollar distance on a percent order is converted against
+ *   `ref = max(hwm, stop_price)`. For a long the HWM is at or above the live
+ *   price; for a short the stop is above it. So `ref` is at or above live on
+ *   both sides, and `distance / ref` is at or below `distance / live`: the
+ *   resulting stop is at or tighter than `live ∓ distance`. The percent is
+ *   rounded down to hundredths, which only tightens it further.
+ * - A percent on a percent order is sent unchanged.
+ * - A percent on a dollar order is refused. There is no conversion that keeps
+ *   the caller's intent without a live price this seam does not own.
+ *
+ * @param orderId - The order being replaced (for the refusal record).
+ * @param order - The resting order as returned by the broker.
+ * @param requested - Exactly one of a positive dollar distance or percent.
+ * @returns The resolved `trail` value and its unit.
+ * @throws {TrailUnitConversionRefusedError} When the unit is unknown, no
+ *   finite reference exists, the converted percent falls outside
+ *   [{@link MIN_CONVERTED_TRAIL_PERCENT}, {@link ALPACA_MAX_TRAIL_PERCENT}],
+ *   or a percent targets a dollar order.
+ */
+function resolveReplaceTrail(orderId, order, requested) {
+    const unit = readTrailUnit(order);
+    if (unit === null) {
+        throw new TrailUnitConversionRefusedError({
+            orderId,
+            reason: "unit_unknown",
+            pct: null,
+            ref: null,
+            detail: `order carries trail_price=${String(order.trail_price)} trail_percent=${String(order.trail_percent)}; the replace unit cannot be determined`,
+        });
+    }
+    if ("trailPercent" in requested) {
+        if (unit === "price") {
+            throw new TrailUnitConversionRefusedError({
+                orderId,
+                reason: "percent_on_price_order",
+                pct: requested.trailPercent,
+                ref: null,
+                detail: `a ${requested.trailPercent}% trail sent to a dollar-trail order would be stored as $${requested.trailPercent}`,
+            });
+        }
+        return { trail: requested.trailPercent.toString(), unit, referencePrice: null };
+    }
+    if (unit === "price") {
+        return { trail: requested.trailPrice.toString(), unit, referencePrice: null };
+    }
+    const candidates = [positiveOrNull(order.hwm), positiveOrNull(order.stop_price)].filter((value) => value !== null);
+    if (candidates.length === 0) {
+        throw new TrailUnitConversionRefusedError({
+            orderId,
+            reason: "reference_unavailable",
+            pct: null,
+            ref: null,
+            detail: `percent-trail order has no finite hwm (${String(order.hwm)}) or stop_price (${String(order.stop_price)}) to convert $${requested.trailPrice} against`,
+        });
+    }
+    const ref = Math.max(...candidates);
+    const pct = Math.floor((requested.trailPrice / ref) * PERCENT_PER_UNIT * PERCENT_DECIMALS_SCALE) /
+        PERCENT_DECIMALS_SCALE;
+    if (!Number.isFinite(pct) ||
+        pct < MIN_CONVERTED_TRAIL_PERCENT ||
+        pct > ALPACA_MAX_TRAIL_PERCENT) {
+        throw new TrailUnitConversionRefusedError({
+            orderId,
+            reason: "converted_percent_out_of_range",
+            pct,
+            ref,
+            detail: `$${requested.trailPrice} against ref ${ref} is ${pct}%, outside [${MIN_CONVERTED_TRAIL_PERCENT}, ${ALPACA_MAX_TRAIL_PERCENT}]`,
+        });
+    }
+    return { trail: pct.toFixed(2), unit, referencePrice: ref };
+}
+
 const limitPriceSlippagePercent100 = 0.1; // 0.1%
 /**
  * Alpaca's maximum page size for GET /orders — also our explicit default.
@@ -11039,12 +11193,18 @@ class AlpacaTradingAPI {
             return null;
         }
         const originalOrderId = trailingStopOrder.id;
+        // Alpaca reads the replace `trail` in the resting order's unit. A percent
+        // sent to a dollar-trail order would be stored as dollars, so it is refused
+        // (typed, no replace sent) and the resting dollar trail keeps protecting.
+        const resolvedTrail = resolveReplaceTrail(originalOrderId, trailingStopOrder, {
+            trailPercent: trailPercent100,
+        });
         this.log(`Updating trailing stop for ${symbol} from ${currentTrailPercent}% to ${trailPercent100}% (orderId=${originalOrderId})`, {
             symbol,
         });
         try {
             const updatedOrder = await this.makeRequest(`/orders/${trailingStopOrder.id}`, "PATCH", {
-                trail: trailPercent100.toString(),
+                trail: resolvedTrail.trail,
             });
             // Log the replacement: Alpaca replaces orders on PATCH, so new ID is returned
             this.log(`Trailing stop updated for ${symbol}: newOrderId=${updatedOrder.id}, replaces=${updatedOrder.replaces || originalOrderId}`, { symbol });
@@ -63460,13 +63620,6 @@ var orderUtils$1 = /*#__PURE__*/Object.freeze({
 });
 
 const LOG_SOURCE$7 = "TrailingStops";
-/**
- * Alpaca's hard upper limit for `trail_percent` on trailing-stop orders.
- * Submissions exceeding this value are rejected with HTTP 422 / code 42210000
- * ("trail_percent must be <= 25"). See:
- * https://docs.alpaca.markets/reference/postorder
- */
-const ALPACA_MAX_TRAIL_PERCENT = 25;
 /**
  * Internal logging helper with consistent source
  */
@@ -63595,23 +63748,42 @@ async function createTrailingStop(client, params) {
     }
 }
 /**
- * Update an existing trailing stop order
+ * Update the trail distance of an existing trailing stop order.
+ *
+ * ## Unit contract
  *
- * You can update the trail_percent or trail_price of an existing order.
- * Note: Alpaca uses 'trail' parameter for replacements (works for both percent and price).
+ * Alpaca's replace takes a single unitless `trail` field and reads it in the
+ * unit of the ORIGINAL order; a replace cannot change the unit. This function
+ * therefore reads the resting order first and resolves the request against its
+ * unit ({@link resolveReplaceTrail}):
+ *
+ * - `trailPrice` on a dollar-trail order is sent as dollars, unchanged.
+ * - `trailPrice` on a percent-trail order is converted to a percent against
+ *   `max(hwm, stop_price)`, which is at or above the live price on both sides,
+ *   so the resulting stop is at or tighter than `live ∓ trailPrice`. The
+ *   percent is rounded down to hundredths (tighter).
+ * - `trailPercent` on a percent-trail order is sent unchanged.
+ * - `trailPercent` on a dollar-trail order is refused.
+ *
+ * A refusal throws {@link TrailUnitConversionRefusedError} and sends no
+ * replace, so the resting stop keeps protecting. The unit is never guessed and
+ * the conversion reference is never defaulted.
  *
  * @param client - AlpacaClient instance
  * @param orderId - The ID of the order to update
- * @param updates - New trail parameters (specify one of trailPercent or trailPrice)
- * @returns The updated order
- * @throws {Error} If no update parameters provided or update fails
+ * @param updates - New trail parameters (specify exactly one of trailPercent or trailPrice)
+ * @returns The replacement order
+ * @throws {Error} If no/both update parameters are given, or a value is not positive
+ * @throws {TrailUnitConversionRefusedError} If the request cannot be expressed
+ *   in the resting order's unit
+ * @throws {AlpacaApiError} If the order read or the replace fails at the broker
  *
  * @example
  * ```typescript
- * // Tighten trailing stop to 1.5%
+ * // Tighten a percent trailing stop to 1.5%
  * await updateTrailingStop(client, 'order-id-123', { trailPercent: 1.5 });
  *
- * // Change to $3 trail
+ * // Pin a $3 trail distance (converted when the order trails in percent)
  * await updateTrailingStop(client, 'order-id-123', { trailPrice: 3.00 });
  * ```
  */
@@ -63631,21 +63803,41 @@ async function updateTrailingStop(client, orderId, updates) {
         throw new Error("trailPrice must be greater than 0");
     }
     const sdk = client.getSDK();
-    const updateDescription = updates.trailPercent
-        ? `${updates.trailPercent}%`
-        : `$${updates.trailPrice?.toFixed(2)}`;
+    const requested = updates.trailPercent !== undefined
+        ? { trailPercent: updates.trailPercent }
+        : { trailPrice: updates.trailPrice };
+    const updateDescription = "trailPercent" in requested
+        ? `${requested.trailPercent}%`
+        : `$${requested.trailPrice.toFixed(2)}`;
     log$g(`Updating trailing stop ${orderId} to trail: ${updateDescription}`, {
         type: "info",
     });
+    let resting;
     try {
-        const replaceParams = {};
-        // Alpaca's replaceOrder uses 'trail' for both percent and price updates
-        if (updates.trailPercent !== undefined) {
-            replaceParams.trail = updates.trailPercent.toString();
-        }
-        else if (updates.trailPrice !== undefined) {
-            replaceParams.trail = updates.trailPrice.toString();
-        }
+        resting = (await sdk.getOrder(orderId));
+    }
+    catch (error) {
+        const err = error;
+        log$g(`Trailing stop update aborted for ${orderId}: order read failed: ${err.message}`, {
+            type: "error",
+        });
+        throw enrichAlpacaError(new Error(`Failed to read trailing stop ${orderId} before update: ${err.message}`), error);
+    }
+    let resolved;
+    try {
+        resolved = resolveReplaceTrail(orderId, resting, requested);
+    }
+    catch (refusal) {
+        log$g(`Trailing stop update refused for ${orderId}: ${refusal.message}`, {
+            type: "warn",
+        });
+        throw refusal;
+    }
+    if (resolved.referencePrice !== null) {
+        log$g(`Trailing stop ${orderId}: ${updateDescription} on percent order → ${resolved.trail}% (ref ${resolved.referencePrice})`, { type: "info" });
+    }
+    try {
+        const replaceParams = { trail: resolved.trail };
         const order = await sdk.replaceOrder(orderId, replaceParams);
         log$g(`Trailing stop updated: orderId=${order.id}, new replacement created`, {
             type: "info",
@@ -72350,6 +72542,192 @@ const alpaca = {
     streams: streams$1,
 };
 
+/**
+ * Rolling healthy-latency evidence per (provider, model), split by prompt size.
+ *
+ * The chain's timeouts and hedge points are only as good as its idea of how
+ * long a healthy answer takes. A flat route budget encodes no such idea: it
+ * treats a thirty-second wait on a model whose healthy answers arrive in four
+ * the same as a thirty-second wait on one that needs twenty-five. This tracker
+ * supplies the measured alternative.
+ *
+ * It is keyed by provider and model rather than by alias and role, because
+ * health is a property of the model at its host: the same model reached as one
+ * alias's primary and another alias's secondary is one population, and
+ * splitting it would halve the evidence each side sees. Samples are split by
+ * prompt size, because generation time grows with input and a model that
+ * struggles on large prompts would otherwise have its large-prompt tail hidden
+ * by a crowd of small, fast calls.
+ *
+ * Only healthy (answered) attempts are recorded. A timeout says the answer
+ * took at least the budget, not how long it took, and folding it in would pull
+ * the quantiles toward whatever budget happened to be configured.
+ *
+ * Unknown stays unknown: a cell with fewer than the minimum samples answers
+ * `null`, and every consumer treats `null` as "no evidence", never as a value.
+ *
+ * @module llm/leg-latency-tracker
+ */
+/** Characters per token used to size a prompt before the provider has counted it. */
+const CHARS_PER_TOKEN = 4;
+/** The bucket used when a prompt's size could not be estimated. */
+const UNKNOWN_BUCKET = "unknown";
+/**
+ * Estimate a prompt's size in tokens from its serialised length.
+ *
+ * Only used to choose a size bucket, and the same estimate is applied when a
+ * sample is recorded and when it is looked up, so its bias cancels. Content
+ * that cannot be serialised yields `null` rather than a guessed size.
+ *
+ * @param parts The prompt, developer instruction and prior turns.
+ * @returns The estimated token count, or null.
+ */
+function estimatePromptTokens(parts) {
+    let characters = 0;
+    for (const part of parts) {
+        if (part === undefined) {
+            continue;
+        }
+        if (typeof part === "string") {
+            characters += part.length;
+            continue;
+        }
+        try {
+            const serialised = JSON.stringify(part);
+            if (typeof serialised !== "string") {
+                return null;
+            }
+            characters += serialised.length;
+        }
+        catch {
+            // A circular or otherwise unserialisable part has no knowable size; the
+            // caller files its latency under the unknown bucket rather than a guess.
+            return null;
+        }
+    }
+    return Math.ceil(characters / CHARS_PER_TOKEN);
+}
+/**
+ * The nearest-rank quantile of a sorted sample.
+ *
+ * @param sorted Ascending values; must be non-empty.
+ * @param q The quantile, in (0, 1).
+ * @returns The value at that rank.
+ */
+function nearestRank(sorted, q) {
+    const rank = Math.min(sorted.length, Math.max(1, Math.ceil(q * sorted.length)));
+    return sorted[rank - 1];
+}
+/**
+ * Per-process healthy-latency windows.
+ */
+class LegLatencyTracker {
+    cells = new Map();
+    config;
+    now;
+    /**
+     * @param config Window sizing and prompt-size buckets.
+     * @param now Clock, injected so ageing is testable without waiting.
+     */
+    constructor(config, now = Date.now) {
+        this.config = config;
+        this.now = now;
+    }
+    /**
+     * The size bucket a prompt falls in.
+     *
+     * @param promptTokens Estimated prompt tokens, or null when unknown.
+     * @returns The bucket label.
+     */
+    bucketOf(promptTokens) {
+        if (promptTokens === null || !Number.isFinite(promptTokens)) {
+            return UNKNOWN_BUCKET;
+        }
+        const index = this.config.promptTokenBuckets.findIndex((edge) => promptTokens < edge);
+        return String(index === -1 ? this.config.promptTokenBuckets.length : index);
+    }
+    /**
+     * Record one healthy (answered) attempt.
+     *
+     * @param provider The provider that answered.
+     * @param modelId The model it answered with.
+     * @param promptTokens Estimated prompt tokens, or null.
+     * @param durationMs How long the answer took.
+     * @returns void
+     */
+    record(provider, modelId, promptTokens, durationMs) {
+        if (!Number.isFinite(durationMs) || durationMs < 0) {
+            return;
+        }
+        const key = this.cellKey(provider, modelId, promptTokens);
+        const samples = this.fresh(key);
+        samples.push({ atMs: this.now(), durationMs });
+        while (samples.length > this.config.windowSize) {
+            samples.shift();
+        }
+        this.cells.set(key, samples);
+    }
+    /**
+     * A healthy-latency quantile, or null without enough evidence.
+     *
+     * @param provider The provider.
+     * @param modelId The model.
+     * @param promptTokens Estimated prompt tokens, or null.
+     * @param q The quantile, in (0, 1).
+     * @returns The quantile in milliseconds, or null.
+     */
+    quantile(provider, modelId, promptTokens, q) {
+        const samples = this.fresh(this.cellKey(provider, modelId, promptTokens));
+        if (samples.length < this.config.minSamples) {
+            return null;
+        }
+        const sorted = samples.map((sample) => sample.durationMs).sort((a, b) => a - b);
+        return nearestRank(sorted, q);
+    }
+    /**
+     * How many fresh samples a cell holds.
+     *
+     * @param provider The provider.
+     * @param modelId The model.
+     * @param promptTokens Estimated prompt tokens, or null.
+     * @returns The count.
+     */
+    sampleCount(provider, modelId, promptTokens) {
+        return this.fresh(this.cellKey(provider, modelId, promptTokens)).length;
+    }
+    /**
+     * Discard all evidence.
+     *
+     * @returns void
+     */
+    reset() {
+        this.cells.clear();
+    }
+    /**
+     * @param provider The provider.
+     * @param modelId The model.
+     * @param promptTokens Estimated prompt tokens, or null.
+     * @returns The cell key.
+     */
+    cellKey(provider, modelId, promptTokens) {
+        return `${provider}/${modelId}@${this.bucketOf(promptTokens)}`;
+    }
+    /**
+     * A cell's samples with the stale ones removed.
+     *
+     * @param key The cell key.
+     * @returns The fresh samples (the stored array, pruned in place).
+     */
+    fresh(key) {
+        const samples = this.cells.get(key) ?? [];
+        const oldest = this.now() - this.config.sampleMaxAgeMs;
+        while (samples.length > 0 && samples[0].atMs < oldest) {
+            samples.shift();
+        }
+        return samples;
+    }
+}
+
 /**
  * Per-route circuit breaker for the alias client.
  *
@@ -72367,16 +72745,57 @@ const alpaca = {
  * traffic can neither trip nor be tripped by traffic on the other side of the
  * PD-9 boundary.
  *
+ * How long a tripped breaker stays open depends on WHY it tripped. A provider
+ * that is refusing work because it is momentarily full ("model busy", 429,
+ * 503, 529, or a leg that ran out its budget queued behind other traffic) is
+ * shedding load it expects to take back within seconds; excluding it for a
+ * full minute pushes every call onto the next leg, which is how one provider's
+ * capacity blip becomes the last leg's overload. Such a run opens for the
+ * shorter `capacity_cooldown_ms`. A run that contains any hard failure (a
+ * rejected credential, a malformed request, an unreachable gateway, an answer
+ * that does not parse) says the route is broken rather than busy, and opens
+ * for the full `cooldown_ms`. Either way the route then admits a bounded number
+ * of half-open probes, and one success closes it.
+ *
+ * A route can also be opened by LATENCY (when `latency_trip` is armed): a
+ * provider whose answers arrive, but later than the latency class's objective
+ * in most recent windows, is failing a hot path without ever producing an
+ * error. A latency-opened breaker is not closed by an answer from an attempt
+ * that started before it opened, because such an answer is exactly the slow
+ * evidence that opened it.
+ *
+ * The half-open probe budget scales with how much traffic the route carried
+ * before it opened (`probe_fraction`), so a route that served forty calls at
+ * once is not re-tested by a single probe whose one slow answer decides it.
+ *
  * The clock is injected. Breaker behaviour is entirely about elapsed time, and
  * a test that must sleep to observe a cooldown is a test nobody runs.
  *
  * @module llm/circuit-breaker
  */
+/**
+ * @returns A record for a route with no failures on file.
+ */
+function freshRecord() {
+    return {
+        consecutiveFailures: 0,
+        openedAtMs: null,
+        probesInFlight: 0,
+        runHasHardFailure: false,
+        openedByLatency: false,
+        concurrencyAtOpen: 0,
+    };
+}
 /**
  * Tracks route health and decides whether a leg may be attempted.
  */
 class CircuitBreakerRegistry {
     records = new Map();
+    latency = new Map();
+    /** Attempts currently in flight per route, for scaling the probe budget. */
+    inFlight = new Map();
+    /** Peak of {@link inFlight} since the route last opened. */
+    peakInFlight = new Map();
     config;
     now;
     /**
@@ -72404,7 +72823,26 @@ class CircuitBreakerRegistry {
             return "closed";
         }
         const elapsed = this.now() - record.openedAtMs;
-        return elapsed >= this.config.cooldown_ms ? "half-open" : "open";
+        return elapsed >= this.cooldownFor(record) ? "half-open" : "open";
+    }
+    /**
+     * The cooldown a record's current run earns.
+     *
+     * A run made only of capacity failures earns the capacity cooldown; one hard
+     * failure anywhere in the run earns the full one. Mixed evidence is read as
+     * the worse case, because a route that is both busy and broken is broken.
+     * The capacity cooldown is never allowed to exceed the full one, so a
+     * misconfigured table cannot make busy routes wait longer than broken ones.
+     *
+     * @param record The route's record.
+     * @returns The cooldown in milliseconds.
+     */
+    cooldownFor(record) {
+        const capacityCooldown = this.config.capacity_cooldown_ms ?? this.config.cooldown_ms;
+        if (record.runHasHardFailure) {
+            return this.config.cooldown_ms;
+        }
+        return Math.min(capacityCooldown, this.config.cooldown_ms);
     }
     /**
      * Whether a route may be attempted now.
@@ -72426,7 +72864,20 @@ class CircuitBreakerRegistry {
             return false;
         }
         const record = this.recordFor(routeKey);
-        return record.probesInFlight < this.config.half_open_probes;
+        return record.probesInFlight < this.probeBudgetFor(record);
+    }
+    /**
+     * How many half-open probes a route admits at once.
+     *
+     * @param record The route's record.
+     * @returns The larger of the configured floor and the concurrency-scaled budget.
+     */
+    probeBudgetFor(record) {
+        const fraction = this.config.probe_fraction;
+        if (fraction === undefined || fraction <= 0) {
+            return this.config.half_open_probes;
+        }
+        return Math.max(this.config.half_open_probes, Math.ceil(fraction * record.concurrencyAtOpen));
     }
     /**
      * Register that an attempt is starting, so half-open probes stay bounded.
@@ -72437,6 +72888,9 @@ class CircuitBreakerRegistry {
      *   {@link onAttemptAbandoned}, or the slot is never returned.
      */
     onAttemptStart(routeKey) {
+        const inFlight = (this.inFlight.get(routeKey) ?? 0) + 1;
+        this.inFlight.set(routeKey, inFlight);
+        this.peakInFlight.set(routeKey, Math.max(this.peakInFlight.get(routeKey) ?? 0, inFlight));
         if (this.stateOf(routeKey) === "half-open") {
             this.recordFor(routeKey).probesInFlight += 1;
             return true;
@@ -72463,6 +72917,17 @@ class CircuitBreakerRegistry {
             record.probesInFlight -= 1;
         }
     }
+    /**
+     * Mark an attempt started with {@link onAttemptStart} as finished, whatever
+     * its outcome, so the in-flight count that scales the probe budget stays true.
+     *
+     * @param routeKey The route's stable key.
+     * @returns void
+     */
+    onAttemptEnd(routeKey) {
+        const inFlight = this.inFlight.get(routeKey) ?? 0;
+        this.inFlight.set(routeKey, Math.max(0, inFlight - 1));
+    }
     /**
      * Record a success, closing the breaker.
      *
@@ -72471,15 +72936,68 @@ class CircuitBreakerRegistry {
      * working call answers it; requiring several would keep a recovered provider
      * excluded while the chain paid for slower legs.
      *
+     * The one exception is a breaker opened by latency: an answer from an
+     * attempt that started before it opened is the slow evidence that opened it,
+     * not evidence of recovery, and is ignored.
+     *
      * @param routeKey The route's stable key.
+     * @param startedAtMs When the answering attempt started, on the registry's clock.
      * @returns void
      */
-    onSuccess(routeKey) {
-        this.records.set(routeKey, {
-            consecutiveFailures: 0,
-            openedAtMs: null,
-            probesInFlight: 0,
-        });
+    onSuccess(routeKey, startedAtMs) {
+        const record = this.records.get(routeKey);
+        if (record !== undefined &&
+            record.openedByLatency &&
+            record.openedAtMs !== null &&
+            startedAtMs !== undefined &&
+            startedAtMs < record.openedAtMs) {
+            return;
+        }
+        this.records.set(routeKey, freshRecord());
+    }
+    /**
+     * Record how long an attempt that reached the provider took.
+     *
+     * Durations fill fixed-size windows; each full window is judged against the
+     * latency class's objective at the configured quantile, and the breaker opens
+     * when enough of the recent windows were over it. Does nothing unless the
+     * latency trip is armed.
+     *
+     * @param routeKey The route's stable key.
+     * @param durationMs The attempt's duration.
+     * @param latencyClass The alias's latency class, which selects the objective.
+     * @returns void
+     */
+    onLatencySample(routeKey, durationMs, latencyClass) {
+        const trip = this.config.latency_trip;
+        if (trip === undefined || !trip.enabled || latencyClass === undefined) {
+            return;
+        }
+        if (!Number.isFinite(durationMs) || durationMs < 0) {
+            return;
+        }
+        let state = this.latency.get(routeKey);
+        if (state === undefined) {
+            state = { samples: [], verdicts: [] };
+            this.latency.set(routeKey, state);
+        }
+        state.samples.push(durationMs);
+        if (state.samples.length < trip.window_size) {
+            return;
+        }
+        const sorted = [...state.samples].sort((a, b) => a - b);
+        state.samples = [];
+        state.verdicts.push(nearestRank(sorted, trip.quantile) > trip.slo_ms[latencyClass]);
+        while (state.verdicts.length > trip.of_windows) {
+            state.verdicts.shift();
+        }
+        const over = state.verdicts.filter(Boolean).length;
+        if (over >= trip.trip_windows && this.stateOf(routeKey) === "closed") {
+            const record = this.recordFor(routeKey);
+            this.open(routeKey, record);
+            record.openedByLatency = true;
+            state.verdicts = [];
+        }
     }
     /**
      * Record a failure, opening the breaker once the threshold is reached.
@@ -72488,17 +73006,36 @@ class CircuitBreakerRegistry {
      * re-accumulate the threshold: the probe was the test, and it failed.
      *
      * @param routeKey The route's stable key.
+     * @param kind Whether the failure was a capacity signal or a hard failure.
+     *   Defaults to `hard`, so a caller that cannot tell gets the longer, safer
+     *   cooldown.
      * @returns void
      */
-    onFailure(routeKey) {
+    onFailure(routeKey, kind = "hard") {
         const wasHalfOpen = this.stateOf(routeKey) === "half-open";
         const record = this.recordFor(routeKey);
         record.probesInFlight = 0;
         record.consecutiveFailures += 1;
+        if (kind === "hard") {
+            record.runHasHardFailure = true;
+        }
         if (wasHalfOpen || record.consecutiveFailures >= this.config.failure_threshold) {
-            record.openedAtMs = this.now();
+            this.open(routeKey, record);
+            record.openedByLatency = false;
         }
     }
+    /**
+     * Open a route, capturing the concurrency its probe budget scales with.
+     *
+     * @param routeKey The route's stable key.
+     * @param record Its record.
+     * @returns void
+     */
+    open(routeKey, record) {
+        record.openedAtMs = this.now();
+        record.concurrencyAtOpen = Math.max(record.concurrencyAtOpen, this.peakInFlight.get(routeKey) ?? 0);
+        this.peakInFlight.set(routeKey, this.inFlight.get(routeKey) ?? 0);
+    }
     /**
      * Inspect a route's breaker.
      *
@@ -72506,17 +73043,21 @@ class CircuitBreakerRegistry {
      * @returns A snapshot.
      */
     snapshot(routeKey) {
-        const record = this.records.get(routeKey) ?? {
-            consecutiveFailures: 0,
-            openedAtMs: null,
-            probesInFlight: 0,
-        };
+        const record = this.records.get(routeKey) ?? freshRecord();
         return {
             routeKey,
             state: this.stateOf(routeKey),
             consecutiveFailures: record.consecutiveFailures,
             openedAtMs: record.openedAtMs,
             probesInFlight: record.probesInFlight,
+            failureKind: record.consecutiveFailures === 0
+                ? null
+                : record.runHasHardFailure
+                    ? "hard"
+                    : "capacity",
+            cooldownMs: this.cooldownFor(record),
+            openedByLatency: record.openedByLatency,
+            probeBudget: this.probeBudgetFor(record),
         };
     }
     /**
@@ -72536,6 +73077,9 @@ class CircuitBreakerRegistry {
      */
     reset() {
         this.records.clear();
+        this.latency.clear();
+        this.inFlight.clear();
+        this.peakInFlight.clear();
     }
     /**
      * @param routeKey The route's stable key.
@@ -72544,7 +73088,7 @@ class CircuitBreakerRegistry {
     recordFor(routeKey) {
         let record = this.records.get(routeKey);
         if (record === undefined) {
-            record = { consecutiveFailures: 0, openedAtMs: null, probesInFlight: 0 };
+            record = freshRecord();
             this.records.set(routeKey, record);
         }
         return record;
@@ -72820,7 +73364,17 @@ var providers$1 = {
 		max_concurrent: 12,
 		acquire_timeout_ms: 15000,
 		source: null,
-		note: "The unit is per model: the scope_source states 'Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously', measured as requests, input tokens and output tokens per minute for each model class, with no concurrency ceiling. Each model therefore gets its own guard, so traffic on one model class (an Opus incumbent serving background aliases) cannot refuse calls to another (the Haiku incumbent of the hot-path alias). The NUMBERS stay conservative-default: the organisation's usage tier sets the real ceilings and is read only from the Claude Console rate-limits page, which has not been transcribed. The lowest standard tier listed at the source allows 1,000 requests per minute per model; organisations with limited history can start on an evaluation tier below that, which is why these values are held well under it. Transcribe the tier's limits (W3-07) and set basis to published."
+		note: "The unit is per model: the scope_source states 'Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously', measured as requests, input tokens and output tokens per minute for each model class, with no concurrency ceiling. Each model therefore gets its own guard, so traffic on one model class (an Opus incumbent serving background aliases) cannot refuse calls to another (the Haiku incumbent of the hot-path alias). The NUMBERS stay conservative-default: the organisation's usage tier sets the real ceilings and is read only from the Claude Console rate-limits page, which has not been transcribed. The lowest standard tier listed at the source allows 1,000 requests per minute per model; organisations with limited history can start on an evaluation tier below that, which is why these values are held well under it. Transcribe the tier's limits (W3-07) and set basis to published.",
+		models: {
+			"claude-haiku-4-5": {
+				basis: "conservative-default",
+				requests_per_minute: 300,
+				max_concurrent: 48,
+				acquire_timeout_ms: 10000,
+				source: null,
+				note: "Raised 2026-09-28 for the closed-incumbent role this model holds on llm.fast, llm.decide and llm.extract. Measured that day: when DeepInfra was capacity-limited ('Model busy, retry later', timeouts at the 30000 ms hot-path budget), both DeepInfra legs of llm.fast opened their breakers and ALL of the alias's traffic fell to this model, where the 12-permit guard could not absorb it. In the 12 minutes to 15:33Z the incumbent leg recorded 18 timeouts, 15 breaker-open and 11 guard refusals ('did not admit the call within 15000 ms'), and the chain exhausted 20-45 times per 5 minutes. Sizing: in-flight demand is arrival rate times leg duration (Little's law), and the leg duration that matters is the worst case the chain permits, 30 s. 12 permits at 30 s serve 24 calls/min; 48 permits serve 96 calls/min at 30 s and up to the 300/min rate bound at haiku's normal single-digit-second latency, which covers the diverted llm.fast load plus normal llm.decide/llm.extract volume on the same guard. requests_per_minute is raised with it (the two bind in series) to 300, which is 30% of the 1,000 requests per minute per model that the scope_source lists for the lowest standard tier, so it remains below any standard tier's ceiling; no Anthropic 429 was observed in the window. acquire_timeout_ms is cut from 15000 to 10000 so an admitted call keeps at least 20 s of its 30 s leg budget: a call admitted after a 15 s wait had half its budget left, timed out at the provider, and that timeout was charged to this route's breaker, which then refused every call for the cooldown. STILL conservative-default: the organisation's tier has not been transcribed from the Claude Console (W3-07). Other Anthropic models keep the provider numbers."
+			}
+		}
 	},
 	openai: {
 		basis: "conservative-default",
@@ -72929,18 +73483,42 @@ const SECONDS_PER_MINUTE = 60;
 const TOKENS_PER_REQUEST = 1;
 const config$1 = limitsConfig;
 /**
- * Resolve the limits that apply to a provider.
+ * Resolve the limits that apply to a provider, or to one of its models.
  *
  * An unregistered provider falls back to the conservative defaults rather than
  * to no limit at all. Treating "unknown" as "unlimited" would make every newly
  * onboarded provider the one most likely to be over-driven, which is exactly
  * backwards: a new provider is the one whose real ceiling is least understood.
  *
+ * A model with an override on a per-model provider runs at the override's
+ * numbers and provenance; every other model runs at the provider's. The
+ * override is ignored for a provider scoped as a whole, because that provider
+ * has one guard and a per-model number cannot be enforced on it.
+ *
  * @param provider The provider key.
+ * @param modelId The model, when the caller knows which one it addresses.
  * @returns Its limits.
  */
-function limitsFor(provider) {
-    return config$1.providers[provider] ?? config$1.defaults;
+function limitsFor(provider, modelId) {
+    const limits = config$1.providers[provider] ?? config$1.defaults;
+    if (limits.scope !== "model" || modelId === undefined || modelId.length === 0) {
+        return limits;
+    }
+    const override = limits.models?.[modelId];
+    if (override === undefined) {
+        return limits;
+    }
+    const { models: _siblings, ...providerLimits } = limits;
+    return {
+        ...providerLimits,
+        basis: override.basis,
+        requests_per_minute: override.requests_per_minute,
+        requests_per_minute_basis: override.requests_per_minute_basis,
+        max_concurrent: override.max_concurrent,
+        acquire_timeout_ms: override.acquire_timeout_ms,
+        source: override.source ?? null,
+        note: override.note,
+    };
 }
 /** Every provider with a recorded limit, plus whether it is published or a default. */
 function limitsInventory() {
@@ -73136,7 +73714,7 @@ const guardIdentities = new Map();
 function rateLimiterFor(identity) {
     let limiter = rateLimiters.get(identity.key);
     if (limiter === undefined) {
-        const limits = limitsFor(identity.provider);
+        const limits = limitsFor(identity.provider, identity.modelId);
         limiter = new TokenBucketRateLimiter({
             maxTokens: limits.requests_per_minute,
             refillRate: limits.requests_per_minute / SECONDS_PER_MINUTE,
@@ -73157,7 +73735,7 @@ function rateLimiterFor(identity) {
 function concurrencyGateFor(identity) {
     let gate = concurrencyGates.get(identity.key);
     if (gate === undefined) {
-        gate = new ConcurrencyGate(identity, limitsFor(identity.provider).max_concurrent);
+        gate = new ConcurrencyGate(identity, limitsFor(identity.provider, identity.modelId).max_concurrent);
         concurrencyGates.set(identity.key, gate);
         guardIdentities.set(identity.key, identity);
     }
@@ -73187,8 +73765,8 @@ function concurrencyGateFor(identity) {
  *   or the caller stopped waiting first.
  */
 async function withProviderGuards(provider, call, maxWaitMs, scope = {}) {
-    const limits = limitsFor(provider);
     const identity = guardIdentity(provider, scope.modelId);
+    const limits = limitsFor(provider, identity.modelId);
     const waitBudgetMs = maxWaitMs === undefined
         ? limits.acquire_timeout_ms
         : Math.min(maxWaitMs, limits.acquire_timeout_ms);
@@ -73211,6 +73789,35 @@ async function withProviderGuards(provider, call, maxWaitMs, scope = {}) {
         release();
     }
 }
+/**
+ * Whether a provider guard has room for a DUPLICATE attempt above a reserve.
+ *
+ * A duplicate is a hedge: a second request for an answer another attempt is
+ * already fetching. It is only worth sending with capacity no first attempt
+ * needs, so it is admitted only when nobody is queued behind either bound and
+ * both the free concurrency (after the duplicate) and the rate tokens stay at
+ * or above the reserved fraction of the guard's ceilings. A provider that is
+ * already busy therefore never sees duplicates, which is when they would do
+ * the most harm.
+ *
+ * @param provider The provider key.
+ * @param modelId The model the duplicate would address.
+ * @param reserveFraction Fraction of each ceiling kept free, in [0, 1).
+ * @returns Whether the duplicate may start.
+ */
+function hasDuplicateHeadroom(provider, modelId, reserveFraction) {
+    const identity = guardIdentity(provider, modelId);
+    const limits = limitsFor(provider, identity.modelId);
+    const limiter = rateLimiterFor(identity);
+    const gate = concurrencyGateFor(identity);
+    if (limiter.getQueueLength() > 0 || gate.queueLength() > 0) {
+        return false;
+    }
+    const freeAfter = limits.max_concurrent - gate.inFlightCount() - 1;
+    const tokensAfter = limiter.getAvailableTokens() - TOKENS_PER_REQUEST;
+    return (freeAfter >= Math.ceil(limits.max_concurrent * reserveFraction) &&
+        tokensAfter >= Math.ceil(limits.requests_per_minute * reserveFraction));
+}
 /**
  * Inspect the guards currently in use.
  *
@@ -73220,7 +73827,7 @@ function guardSnapshots() {
     return [...guardIdentities.values()]
         .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
         .map((identity) => {
-        const limits = limitsFor(identity.provider);
+        const limits = limitsFor(identity.provider, identity.modelId);
         const limiter = rateLimiters.get(identity.key);
         const gate = concurrencyGates.get(identity.key);
         return {
@@ -73353,6 +73960,703 @@ function parseStructuredContent(content, responseFormat, usage) {
     }
 }
 
+/**
+ * One attempt against one leg: dispatch under a hard timeout, and the
+ * classification of how it ended.
+ *
+ * Split from the chain walker so the same-model hedge runner and the walker
+ * share exactly one definition of what a timeout, a capacity refusal, a
+ * cancellation and a superseded attempt are. Two copies of that
+ * classification would drift, and the breaker would then read the same event
+ * differently depending on which code path produced it.
+ *
+ * @module llm/leg-attempt
+ */
+/** Raised internally when an attempt exceeds its hard budget. */
+class LegTimeoutError extends Error {
+    /**
+     * @param routeKey The leg that timed out.
+     * @param budgetMs Its budget in milliseconds.
+     */
+    constructor(routeKey, budgetMs) {
+        super(`route ${routeKey} exceeded its ${budgetMs} ms budget`);
+        this.name = "LegTimeoutError";
+    }
+}
+/**
+ * Raised internally when an attempt ran past its MEASURED timeout and was
+ * replaced by another attempt on the same model.
+ *
+ * Not a verdict on the provider: the measured timeout is the chain's own
+ * impatience, applied only because a same-model alternative could take over,
+ * so the breaker learns nothing from it.
+ */
+class AttemptSupersededError extends Error {
+    /**
+     * @param routeKey The attempt's leg.
+     * @param afterMs How long it ran before it was replaced.
+     */
+    constructor(routeKey, afterMs) {
+        super(`route ${routeKey} exceeded its measured ${afterMs} ms attempt timeout and was ` +
+            "superseded by a same-model attempt");
+        this.name = "AttemptSupersededError";
+    }
+}
+/**
+ * Raised internally on an attempt that was still running when another
+ * attempt on the same model answered first. Not a verdict on the provider.
+ */
+class HedgeLoserError extends Error {
+    /**
+     * @param routeKey The losing attempt's leg.
+     */
+    constructor(routeKey) {
+        super(`route ${routeKey} was cancelled: a same-model attempt answered first`);
+        this.name = "HedgeLoserError";
+    }
+}
+/**
+ * Start one attempt under a hard timeout, honouring the caller's own cancellation.
+ *
+ * The timer is always cleared and the abort listener always removed, including
+ * on the success path. A long-lived process that leaked one timer per LLM call
+ * would accumulate them at exactly the rate it does useful work.
+ *
+ * @param leg The leg to run.
+ * @param params Normalised parameters for this leg.
+ * @param request The call's request fields and cancellation.
+ * @param budgetMs The attempt's hard budget.
+ * @returns A handle on the attempt.
+ */
+function startAttempt(leg, params, request, budgetMs) {
+    const controller = new AbortController();
+    let chainReason;
+    let hardTimeout = false;
+    const timer = setTimeout(() => {
+        hardTimeout = true;
+        controller.abort(new LegTimeoutError(leg.route.routeKey, budgetMs));
+    }, budgetMs);
+    const forwardAbort = () => {
+        controller.abort(request.callerSignal?.reason);
+    };
+    if (request.callerSignal !== undefined) {
+        if (request.callerSignal.aborted) {
+            forwardAbort();
+        }
+        else {
+            request.callerSignal.addEventListener("abort", forwardAbort, { once: true });
+        }
+    }
+    const run = async () => {
+        try {
+            // The guards wrap the transport rather than the whole attempt, so the
+            // hard timeout above still bounds the total wait: a caller queued behind
+            // the rate limiter is spending its budget just as surely as one waiting
+            // on the provider, and only one clock should govern both. The attempt's
+            // own signal is handed to the guard as well, so an attempt whose budget
+            // or caller is gone leaves the queue at once instead of holding its place.
+            const response = await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
+                route: leg.route,
+                content: request.content,
+                responseFormat: request.responseFormat,
+                params,
+                developerPrompt: request.developerPrompt,
+                context: request.context,
+                signal: controller.signal,
+                correlationId: request.correlationId,
+            }), budgetMs, { modelId: leg.route.modelId, signal: controller.signal });
+            assertToolChoiceHonoured(leg.route, params, response);
+            return response;
+        }
+        finally {
+            clearTimeout(timer);
+            request.callerSignal?.removeEventListener("abort", forwardAbort);
+        }
+    };
+    return {
+        promise: run(),
+        abort: (reason) => {
+            if (chainReason === undefined && !controller.signal.aborted) {
+                chainReason = reason;
+                controller.abort(reason);
+            }
+        },
+        abortReason: () => chainReason,
+        timedOut: () => hardTimeout,
+    };
+}
+/**
+ * HTTP statuses a provider (or the gateway relaying it) uses to say it is full
+ * rather than that the request or the route is wrong: request timeout, too
+ * early, too many requests, service unavailable, and Anthropic's overloaded.
+ */
+const CAPACITY_STATUSES = new Set([408, 425, 429, 503, 529]);
+/**
+ * Wording providers use for a capacity refusal when the status is lost on the
+ * way (a relayed body, a client library's own error). DeepInfra's is
+ * "Model busy, retry later"; Anthropic's is "Overloaded".
+ */
+const CAPACITY_WORDING = /\b(busy|overloaded|capacity|rate[ -]?limit(ed)?|too many requests)\b/i;
+/**
+ * Whether a failure is the provider saying it is full rather than broken.
+ *
+ * Read by shape rather than by class, because the same signal reaches the
+ * chain from more than one transport and not every transport's error class is
+ * importable here.
+ *
+ * @param error The thrown value.
+ * @param reason Its message.
+ * @returns Whether it is a capacity signal.
+ */
+function isCapacitySignal(error, reason) {
+    if (typeof error === "object" && error !== null) {
+        const status = error.status;
+        if (typeof status === "number" && CAPACITY_STATUSES.has(status)) {
+            return true;
+        }
+    }
+    return CAPACITY_WORDING.test(reason);
+}
+/**
+ * Classify why a leg failed.
+ *
+ * The distinction matters to the breaker: a timeout and a 5xx are evidence the
+ * provider is unhealthy, while the caller cancelling is not. Counting a
+ * cancellation as a provider failure would let a burst of user-cancelled
+ * requests open the breaker on a perfectly healthy route.
+ *
+ * Among failures that do count, a capacity signal (the provider said it is
+ * busy, or the leg ran out its budget waiting on it) is told apart from a hard
+ * failure so the breaker can re-admit a busy route sooner than a broken one. A
+ * timeout is read as capacity: on a reachable provider it is what a full queue
+ * looks like from outside, and a provider that is actually down still costs no
+ * more than one probe per capacity cooldown.
+ *
+ * An attempt the chain itself cancelled — replaced after its measured
+ * timeout, or beaten by a same-model attempt — is not a verdict on the
+ * provider either, and is classified by the chain's reason rather than by
+ * whatever the transport happened to throw on the way out.
+ *
+ * @param error The thrown value.
+ * @param callerSignal The caller's cancellation signal, if any.
+ * @returns The outcome and whether it counts against route health.
+ */
+function classify(error, callerSignal) {
+    if (callerSignal !== undefined && callerSignal.aborted) {
+        return {
+            outcome: "skipped",
+            reason: "caller cancelled",
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
+    }
+    if (error instanceof AttemptSupersededError) {
+        return {
+            outcome: "timeout",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "capacity",
+        };
+    }
+    if (error instanceof HedgeLoserError) {
+        return {
+            outcome: "skipped",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "capacity",
+        };
+    }
+    if (error instanceof LegTimeoutError) {
+        return {
+            outcome: "timeout",
+            reason: error.message,
+            countsAgainstHealth: true,
+            failureKind: "capacity",
+        };
+    }
+    if (error instanceof UnsupportedCapabilityError) {
+        return {
+            outcome: "skipped",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
+    }
+    if (error instanceof ToolChoiceIgnoredError) {
+        // The route answered; it broke a declared guarantee rather than failing to
+        // be available, so its breaker is not charged for it.
+        return {
+            outcome: "error",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
+    }
+    // Self-inflicted pacing, not provider ill-health. Counting it would let the
+    // client's own throttling open a breaker on a perfectly healthy provider and
+    // permanently reroute traffic nobody chose to reroute.
+    if (error instanceof RateGuardTimeoutError) {
+        return {
+            outcome: "skipped",
+            reason: error.message,
+            countsAgainstHealth: false,
+            failureKind: "hard",
+        };
+    }
+    const reason = error instanceof Error ? error.message : String(error);
+    if (/abort/i.test(reason)) {
+        return {
+            outcome: "timeout",
+            reason: `aborted: ${reason}`,
+            countsAgainstHealth: true,
+            failureKind: "capacity",
+        };
+    }
+    if (error instanceof LlmResponseFormatError) {
+        // The provider answered, badly. That is a route defect, not a full queue,
+        // whatever words the unparseable content happens to contain.
+        return { outcome: "error", reason, countsAgainstHealth: true, failureKind: "hard" };
+    }
+    return {
+        outcome: "error",
+        reason,
+        countsAgainstHealth: true,
+        failureKind: isCapacitySignal(error, reason) ? "capacity" : "hard",
+    };
+}
+/**
+ * Whether the caller has stopped waiting.
+ *
+ * Read through a function rather than inline, because `AbortSignal.aborted` is
+ * a live getter: it can flip to true while a leg is in flight, but a compiler
+ * that narrowed it at the top of the loop would prove the later check
+ * unreachable and invite its removal. The check is not redundant — it is the
+ * only thing that stops the chain spending money on an answer nobody will read.
+ *
+ * @param signal The caller's signal, if any.
+ * @returns Whether the call has been cancelled.
+ */
+function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/**
+ * The usage a failed leg was billed for, when the leg reached an answer.
+ *
+ * A leg that failed after the provider answered — content that does not parse,
+ * or prose where a tool call was mandatory — was still charged. A leg that
+ * never answered (timeout, outage, skip) carries no usage, and none is invented.
+ *
+ * @param error The thrown value.
+ * @returns The billed usage, or undefined when the leg never produced an answer.
+ */
+function billedUsageOf(error) {
+    if (error instanceof LlmResponseFormatError || error instanceof ToolChoiceIgnoredError) {
+        return error.usage;
+    }
+    return undefined;
+}
+
+/**
+ * Same-model attempts for one leg: hedging, measured attempt timeouts, and
+ * reserving deadline for a same-model alternative.
+ *
+ * A leg is a model. Before the chain gives up on it and reaches a DIFFERENT
+ * model — which changes the answer's quality, not just its latency — it is
+ * worth spending the leg's budget on every way of getting that same model to
+ * answer: the same model at another provider (an "equivalent"), or a second
+ * request to the same provider when that provider has capacity to spare (a
+ * "duplicate"). This module runs those attempts as one group.
+ *
+ * Three mechanics, all bounded by the leg's budget and none of them selecting
+ * a different model:
+ *
+ * - **Hedging.** Once an attempt has run past the model's healthy p90 (from
+ *   the latency tracker), the next same-model attempt starts beside it. The
+ *   first answer wins and every other attempt is cancelled through its own
+ *   abort signal. A hedge that loses, or an attempt cancelled because another
+ *   won, says nothing about the provider and never touches its breaker.
+ *
+ * - **Measured attempt timeout.** With latency evidence, an attempt that has
+ *   run past `k × p99` of healthy latency is replaced by a same-model
+ *   alternative instead of holding the budget to its end. It is replaced only
+ *   when an alternative exists: with none, cutting it short would only move
+ *   the call to a different model sooner, and it runs to the leg budget as
+ *   before.
+ *
+ * - **Deadline reservation.** When a same-model equivalent exists, no single
+ *   attempt holds more than `max_attempt_share` of the remaining budget before
+ *   the equivalent starts beside it, so a slow first attempt cannot consume the
+ *   whole deadline while the equivalent that could have answered never runs.
+ *
+ * With no latency evidence and no equivalent, none of the three can act and
+ * the group is exactly one attempt with the leg's full budget: the serial
+ * chain's behaviour, which a fresh process therefore starts from.
+ *
+ * @module llm/hedge
+ */
+/**
+ * Read the policy from the table's defaults.
+ *
+ * @param defaults The `hedging` defaults.
+ * @returns The policy.
+ */
+function sameModelPolicyFrom(defaults) {
+    return {
+        maxExtraAttempts: defaults.max_same_model_hedges,
+        hedgeQuantile: defaults.hedge_quantile,
+        timeoutQuantile: defaults.timeout_quantile,
+        kTimeout: defaults.k_timeout,
+        attemptTimeoutFloorMs: defaults.attempt_timeout_floor_ms,
+        maxAttemptShare: defaults.max_attempt_share,
+        duplicateReserve: defaults.duplicate_headroom_reserve,
+    };
+}
+/**
+ * The parameters of a prepared leg, when it can serve.
+ *
+ * @param leg The leg.
+ * @returns Its parameters, or undefined when it cannot serve this request.
+ */
+function paramsOf(leg) {
+    return leg.params instanceof UnsupportedCapabilityError ? undefined : leg.params;
+}
+/**
+ * Run every same-model attempt for one leg until one answers or the budget,
+ * the alternatives, or the caller run out.
+ *
+ * The caller has already found the leg servable (breaker allows it, budget
+ * positive). The returned promise settles only once every attempt it started
+ * has been recorded, so the call's attempt record is complete when it returns.
+ *
+ * @param leg The leg, with its equivalents.
+ * @param groupBudgetMs The leg's budget: its route budget cut to the deadline.
+ * @param budgetIsDeadline Whether that budget was cut by the caller's deadline.
+ * @param ctx The chain around the group.
+ * @returns How the group ended.
+ */
+function runSameModelGroup(leg, groupBudgetMs, budgetIsDeadline, ctx) {
+    const { breakers, now, policy, tracker, promptTokens, request } = ctx;
+    const endsAt = now() + groupBudgetMs;
+    const equivalents = (leg.equivalents ?? []).filter((equivalent) => paramsOf(equivalent) !== undefined);
+    const live = new Set();
+    const billed = [];
+    const timeoutCharged = new Set();
+    let nextEquivalent = 0;
+    let extraLaunched = 0;
+    let settled = false;
+    let finished = false;
+    let deadlineBound = false;
+    let hedgeTimer;
+    let answer;
+    return new Promise((resolve) => {
+        /**
+         * A healthy-latency quantile for a leg's model, when there is evidence.
+         *
+         * @param route The leg's route.
+         * @param q The quantile.
+         * @returns Milliseconds, or null.
+         */
+        const quantileOf = (route, q) => tracker === undefined ? null : tracker.quantile(route.providerName, route.modelId, promptTokens, q);
+        /**
+         * The next same-model attempt that could start now: an equivalent first,
+         * then a duplicate, which needs latency evidence and spare provider capacity.
+         *
+         * @returns The candidate, or undefined.
+         */
+        const peek = () => {
+            if (policy === undefined || extraLaunched >= policy.maxExtraAttempts) {
+                return undefined;
+            }
+            for (let index = nextEquivalent; index < equivalents.length; index += 1) {
+                const equivalent = equivalents[index];
+                if (breakers.allows(equivalent.route.routeKey)) {
+                    return { leg: equivalent, kind: "equivalent", index };
+                }
+            }
+            if (quantileOf(leg.route, policy.hedgeQuantile) !== null &&
+                breakers.allows(leg.route.routeKey) &&
+                ctx.admitDuplicate(leg.route, policy.duplicateReserve)) {
+                return { leg, kind: "duplicate", index: -1 };
+            }
+            return undefined;
+        };
+        /** Resolve once nothing is left in flight. */
+        const finishIfIdle = () => {
+            if (finished || live.size > 0) {
+                return;
+            }
+            finished = true;
+            if (hedgeTimer !== undefined) {
+                clearTimeout(hedgeTimer);
+            }
+            resolve({ answer, billed, deadlineBound });
+        };
+        /**
+         * Arm the hedge for the most recent attempt: at the model's healthy p90,
+         * or — when an equivalent is waiting — no later than the reserved share of
+         * the remaining budget.
+         *
+         * @param latest The attempt just started.
+         */
+        const scheduleHedge = (latest) => {
+            if (hedgeTimer !== undefined) {
+                clearTimeout(hedgeTimer);
+                hedgeTimer = undefined;
+            }
+            const candidate = peek();
+            if (policy === undefined || candidate === undefined) {
+                return;
+            }
+            const measured = quantileOf(latest.leg.route, policy.hedgeQuantile);
+            const reserved = candidate.kind === "equivalent"
+                ? policy.maxAttemptShare * (endsAt - now())
+                : Number.POSITIVE_INFINITY;
+            const delay = Math.min(measured ?? Number.POSITIVE_INFINITY, reserved);
+            if (!Number.isFinite(delay)) {
+                return;
+            }
+            hedgeTimer = setTimeout(() => {
+                hedgeTimer = undefined;
+                if (settled) {
+                    return;
+                }
+                const next = peek();
+                if (next !== undefined) {
+                    launch(next.leg, next, true);
+                }
+            }, Math.max(0, delay));
+        };
+        /**
+         * Start one attempt.
+         *
+         * @param target The leg to address.
+         * @param candidate The candidate it came from, for a hedge.
+         * @param hedged Whether this is a hedge rather than the leg's first attempt.
+         * @returns Whether it started.
+         */
+        const launch = (target, candidate, hedged) => {
+            const params = paramsOf(target);
+            const budgetMs = endsAt - now();
+            if (params === undefined || budgetMs <= 0 || isAborted(request.callerSignal)) {
+                return false;
+            }
+            if (candidate !== undefined) {
+                extraLaunched += 1;
+                if (candidate.kind === "equivalent") {
+                    nextEquivalent = candidate.index + 1;
+                }
+            }
+            const key = target.route.routeKey;
+            const attempt = {
+                leg: target,
+                handle: startAttempt(target, params, request, budgetMs),
+                startedAt: now(),
+                budgetMs,
+                holdsProbe: breakers.onAttemptStart(key),
+                hedged,
+                attemptIndex: ctx.nextAttemptIndex(),
+                closed: false,
+            };
+            live.add(attempt);
+            if (policy !== undefined) {
+                const tail = quantileOf(target.route, policy.timeoutQuantile);
+                if (tail !== null) {
+                    const measuredMs = Math.max(policy.attemptTimeoutFloorMs, policy.kTimeout * tail);
+                    if (measuredMs < budgetMs) {
+                        attempt.softTimer = setTimeout(() => supersede(attempt, measuredMs), measuredMs);
+                    }
+                }
+            }
+            scheduleHedge(attempt);
+            attempt.handle.promise.then((response) => onAnswer(attempt, response), (error) => onFailure(attempt, error));
+            return true;
+        };
+        /**
+         * An attempt ran past its measured timeout: replace it if a same-model
+         * alternative can take over, otherwise leave it running to the leg budget.
+         *
+         * @param attempt The slow attempt.
+         * @param afterMs Its measured timeout.
+         */
+        const supersede = (attempt, afterMs) => {
+            attempt.softTimer = undefined;
+            if (settled || !live.has(attempt)) {
+                return;
+            }
+            const othersInFlight = live.size > 1;
+            const candidate = othersInFlight ? undefined : peek();
+            if (!othersInFlight && candidate === undefined) {
+                return;
+            }
+            // Recorded now rather than when its rejection arrives, so a replacement
+            // that answers first cannot find it still live and misfile it as a loser.
+            const superseded = new AttemptSupersededError(attempt.leg.route.routeKey, afterMs);
+            close(attempt, superseded);
+            if (candidate !== undefined) {
+                launch(candidate.leg, candidate, true);
+            }
+            finishIfIdle();
+        };
+        /**
+         * Cancel an attempt the chain no longer wants and record it at once, with
+         * no verdict on the provider.
+         *
+         * @param attempt The attempt.
+         * @param reason Why it was cancelled.
+         */
+        const close = (attempt, reason) => {
+            const fields = baseFields(attempt);
+            attempt.handle.abort(reason);
+            attempt.closed = true;
+            retire(attempt);
+            if (attempt.holdsProbe) {
+                breakers.onAttemptAbandoned(attempt.leg.route.routeKey);
+            }
+            const failure = classify(reason, request.callerSignal);
+            emit(attempt, { ...fields, outcome: failure.outcome, reason: failure.reason });
+        };
+        /**
+         * Stop tracking an attempt and release its breaker bookkeeping.
+         *
+         * @param attempt The attempt.
+         */
+        const retire = (attempt) => {
+            if (attempt.softTimer !== undefined) {
+                clearTimeout(attempt.softTimer);
+                attempt.softTimer = undefined;
+            }
+            live.delete(attempt);
+            breakers.onAttemptEnd(attempt.leg.route.routeKey);
+        };
+        /**
+         * Record one attempt through the chain.
+         *
+         * @param attempt The attempt.
+         * @param fields What happened.
+         * @param servedProvider The provider's own report of who served, if any.
+         */
+        const emit = (attempt, fields, servedProvider) => {
+            ctx.record(attempt.leg.route, fields, { hedged: attempt.hedged, attemptIndex: attempt.attemptIndex }, servedProvider);
+        };
+        /**
+         * Base fields shared by every record of an attempt.
+         *
+         * @param attempt The attempt.
+         * @returns The identity and timing fields.
+         */
+        const baseFields = (attempt) => ({
+            routeKey: attempt.leg.route.routeKey,
+            role: attempt.leg.route.role,
+            provider: attempt.leg.route.providerName,
+            modelId: attempt.leg.route.modelId,
+            durationMs: now() - attempt.startedAt,
+            budgetMs: attempt.budgetMs,
+        });
+        const onAnswer = (attempt, response) => {
+            if (attempt.closed) {
+                return;
+            }
+            const { route } = attempt.leg;
+            const fields = baseFields(attempt);
+            retire(attempt);
+            breakers.onSuccess(route.routeKey, attempt.startedAt);
+            breakers.onLatencySample(route.routeKey, fields.durationMs, route.latencyClass);
+            tracker?.record(route.providerName, route.modelId, promptTokens, fields.durationMs);
+            billed.push(response.usage);
+            if (settled) {
+                // Answered in the same instant as the winner, before its cancellation
+                // arrived. Its spend is real; its answer is not the one returned.
+                emit(attempt, {
+                    ...fields,
+                    outcome: "skipped",
+                    reason: "answered after a same-model attempt had already won",
+                    servedModel: response.servedModel ?? null,
+                    usage: response.usage,
+                }, response.servedProvider);
+                finishIfIdle();
+                return;
+            }
+            settled = true;
+            answer = { response, route, hedged: attempt.hedged };
+            emit(attempt, {
+                ...fields,
+                outcome: "ok",
+                servedModel: response.servedModel ?? null,
+                usage: response.usage,
+            }, response.servedProvider);
+            for (const loser of [...live]) {
+                // Cancelled through its own signal and recorded now, so the answer is
+                // returned without waiting for a loser still queued at the provider.
+                close(loser, new HedgeLoserError(loser.leg.route.routeKey));
+            }
+            finishIfIdle();
+        };
+        const onFailure = (attempt, error) => {
+            if (attempt.closed) {
+                return;
+            }
+            const { route } = attempt.leg;
+            const key = route.routeKey;
+            const fields = baseFields(attempt);
+            const hardTimeout = attempt.handle.timedOut();
+            retire(attempt);
+            const failure = classify(attempt.handle.abortReason() ?? error, request.callerSignal);
+            let charged = failure.countsAgainstHealth;
+            if (charged && hardTimeout) {
+                // Every attempt of a leg shares the leg's end, so several can time out
+                // together; the provider is charged once for the leg, as before hedging.
+                charged = !timeoutCharged.has(key);
+                timeoutCharged.add(key);
+                if (budgetIsDeadline) {
+                    deadlineBound = true;
+                }
+            }
+            if (charged) {
+                breakers.onFailure(key, failure.failureKind);
+            }
+            else if (attempt.holdsProbe) {
+                // No verdict on the route's health, but the probe slot this attempt
+                // took must come back, or a half-open route admits no probe ever again.
+                breakers.onAttemptAbandoned(key);
+            }
+            if (failure.countsAgainstHealth) {
+                breakers.onLatencySample(key, fields.durationMs, route.latencyClass);
+            }
+            // A provider that answered — with unparseable content, or in prose where a
+            // tool call was mandatory — still billed for the answer.
+            const usage = billedUsageOf(error);
+            if (usage !== undefined) {
+                billed.push(usage);
+            }
+            const answeredBy = error instanceof ToolChoiceIgnoredError ? error.servedModel : undefined;
+            emit(attempt, {
+                ...fields,
+                outcome: failure.outcome,
+                reason: failure.reason,
+                ...(answeredBy === undefined ? {} : { servedModel: answeredBy }),
+                ...(usage === undefined ? {} : { usage }),
+            });
+            if (settled || live.size > 0) {
+                finishIfIdle();
+                return;
+            }
+            if (!hardTimeout && !isAborted(request.callerSignal)) {
+                // A failed attempt with time left moves to the same model at another
+                // provider at once. A duplicate on the provider that just failed is not
+                // started here: it would most likely fail the same way.
+                const candidate = peek();
+                if (candidate !== undefined && candidate.kind === "equivalent") {
+                    launch(candidate.leg, candidate, true);
+                }
+            }
+            finishIfIdle();
+        };
+        if (!launch(leg, undefined, false)) {
+            finishIfIdle();
+        }
+    });
+}
+
 /**
  * Ordered execution of an alias's fallback chain (PD-3).
  *
@@ -73365,10 +74669,21 @@ function parseStructuredContent(content, responseFormat, usage) {
  * why the budget is enforced here — at the only place that knows both the
  * caller's deadline and how many legs are left to spend it on.
  *
+ * Each leg is first run as a group of SAME-MODEL attempts (see `hedge.ts`):
+ * hedged at the model's healthy p90, replaced after a measured timeout, and
+ * reaching the same model at another provider before the leg is given up.
+ * Only then does the walk move to the next leg — and a leg that serves a
+ * different model than the configured one runs only when the caller's
+ * cross-model policy allows it. With no latency evidence and no equivalent
+ * configured, each group is a single attempt with the leg's budget, which is
+ * the serial walk exactly.
+ *
  * Nothing here ever substitutes a value for an outcome. When every leg is
- * exhausted the caller gets a typed error naming each leg and why it failed,
- * because a default returned in place of an answer is a wrong answer that
- * nobody is told about.
+ * exhausted the caller gets a typed error naming each leg and why it failed —
+ * `LlmDeadlineExceededError` when the caller's deadline is what ran out,
+ * `ChainExhaustedError` with reason `cross_model_denied` when policy stopped
+ * the walk — because a default returned in place of an answer is a wrong
+ * answer that nobody is told about.
  *
  * @module llm/fallback-chain
  */
@@ -73395,21 +74710,64 @@ class ChainExhaustedError extends Error {
     attempts;
     /** Usage spent across the failed attempts, so the spend is still accounted for. */
     totalUsage;
+    /**
+     * Why the chain ended. `cross_model_denied`: the configured model's attempts
+     * were spent and policy forbade a different model. Callers map every reason
+     * to no decision; the reason says which remedy applies.
+     */
+    reason;
     /**
      * @param alias The alias.
      * @param attempts The attempt record.
      * @param totalUsage Usage spent across all attempts.
+     * @param reason Why the chain ended; defaults to plain exhaustion.
      */
-    constructor(alias, attempts, totalUsage) {
+    constructor(alias, attempts, totalUsage, reason = "exhausted") {
         const detail = attempts
             .map((attempt) => `${attempt.role}(${attempt.provider}/${attempt.modelId}): ${attempt.outcome}` +
             (attempt.reason === undefined ? "" : ` — ${attempt.reason}`))
             .join("; ");
-        super(`LLM alias "${alias}" exhausted its fallback chain. Attempts: ${detail || "(no leg was servable)"}`);
+        const why = reason === "cross_model_denied"
+            ? " Different-model legs were denied by the caller's cross-model policy."
+            : reason === "deadline_exceeded"
+                ? " The caller's deadline ran out."
+                : "";
+        super(`LLM alias "${alias}" exhausted its fallback chain.${why} Attempts: ${detail || "(no leg was servable)"}`);
         this.name = "ChainExhaustedError";
         this.alias = alias;
         this.attempts = attempts;
         this.totalUsage = totalUsage;
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown when the caller's deadline ran out before any leg answered.
+ *
+ * A subclass of {@link ChainExhaustedError}, so a consumer that already treats
+ * exhaustion as "no answer" keeps doing so, while one that needs to tell "the
+ * models failed" from "we ran out of time" can match this class — the two call
+ * for different remedies (a provider problem versus a budget problem), and
+ * both map to no decision, never to a default.
+ */
+class LlmDeadlineExceededError extends ChainExhaustedError {
+    /** Discriminant for consumers that switch on shape rather than class. */
+    kind = "deadline_exceeded";
+    /** The whole-call budget the chain started with, in milliseconds. */
+    deadlineMs;
+    /** The model class of the last attempt dispatched, or null when none was. */
+    lastModelClass;
+    /**
+     * @param alias The alias.
+     * @param attempts The attempt record.
+     * @param totalUsage Usage spent across all attempts.
+     * @param deadlineMs The budget the chain started with.
+     * @param lastModelClass The last dispatched attempt's model class.
+     */
+    constructor(alias, attempts, totalUsage, deadlineMs, lastModelClass) {
+        super(alias, attempts, totalUsage, "deadline_exceeded");
+        this.name = "LlmDeadlineExceededError";
+        this.deadlineMs = deadlineMs;
+        this.lastModelClass = lastModelClass;
     }
 }
 /**
@@ -73475,148 +74833,70 @@ function legBudgetMs(routeBudgetMs, deadlineAtMs, nowMs) {
     }
     return Math.min(routeBudgetMs, deadlineAtMs - nowMs);
 }
-/** Raised internally when a leg exceeds its budget. */
-class LegTimeoutError extends Error {
-    /**
-     * @param routeKey The leg that timed out.
-     * @param budgetMs Its budget in milliseconds.
-     */
-    constructor(routeKey, budgetMs) {
-        super(`route ${routeKey} exceeded its ${budgetMs} ms budget`);
-        this.name = "LegTimeoutError";
-    }
-}
 /**
- * Run one leg under a hard timeout, honouring the caller's own cancellation.
+ * The model a leg serves, independent of which provider hosts it.
  *
- * The timer is always cleared and the abort listener always removed, including
- * on the success path. A long-lived process that leaked one timer per LLM call
- * would accumulate them at exactly the rate it does useful work.
- *
- * @param leg The leg to run.
- * @param params Normalised parameters for this leg.
- * @param execution The call context.
- * @param budgetMs The leg's budget: its route budget cut to the caller's deadline.
- * @returns The provider's answer.
+ * @param route The leg's route.
+ * @returns Its model class.
  */
-async function runLeg(leg, params, execution, budgetMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-        controller.abort(new LegTimeoutError(leg.route.routeKey, budgetMs));
-    }, budgetMs);
-    const forwardAbort = () => {
-        controller.abort(execution.callerSignal?.reason);
-    };
-    if (execution.callerSignal !== undefined) {
-        if (execution.callerSignal.aborted) {
-            forwardAbort();
-        }
-        else {
-            execution.callerSignal.addEventListener("abort", forwardAbort, { once: true });
-        }
-    }
-    try {
-        // The guards wrap the transport rather than the whole leg, so the per-leg
-        // timeout above still bounds the total wait: a caller queued behind the
-        // rate limiter is spending its budget just as surely as one waiting on the
-        // provider, and only one clock should govern both. The leg's own signal is
-        // handed to the guard as well, so a leg whose budget or caller is gone
-        // leaves the queue at once instead of holding its place in it.
-        const response = await withProviderGuards(leg.route.providerName, () => leg.transport.execute({
-            route: leg.route,
-            content: execution.content,
-            responseFormat: execution.responseFormat,
-            params,
-            developerPrompt: execution.developerPrompt,
-            context: execution.context,
-            signal: controller.signal,
-            correlationId: execution.correlationId,
-        }), budgetMs, { modelId: leg.route.modelId, signal: controller.signal });
-        assertToolChoiceHonoured(leg.route, params, response);
-        return response;
-    }
-    finally {
-        clearTimeout(timer);
-        execution.callerSignal?.removeEventListener("abort", forwardAbort);
-    }
+function modelClassOf(route) {
+    return route.modelClass ?? route.modelId;
 }
 /**
- * Classify why a leg failed.
+ * Whether a provider-reported model names the model a route addressed.
  *
- * The distinction matters to the breaker: a timeout and a 5xx are evidence the
- * provider is unhealthy, while the caller cancelling is not. Counting a
- * cancellation as a provider failure would let a burst of user-cancelled
- * requests open the breaker on a perfectly healthy route.
+ * Providers report with or without an organisation prefix and in their own
+ * case, so the comparison is case-insensitive and accepts one side being a
+ * `/`-suffix of the other.
  *
- * @param error The thrown value.
- * @param callerSignal The caller's cancellation signal, if any.
- * @returns The outcome and whether it counts against route health.
+ * @param reported The provider's report.
+ * @param expected The route's model id.
+ * @returns Whether they name the same model.
  */
-function classify(error, callerSignal) {
-    if (callerSignal !== undefined && callerSignal.aborted) {
-        return {
-            outcome: "skipped",
-            reason: "caller cancelled",
-            countsAgainstHealth: false,
-        };
-    }
-    if (error instanceof LegTimeoutError) {
-        return { outcome: "timeout", reason: error.message, countsAgainstHealth: true };
-    }
-    if (error instanceof UnsupportedCapabilityError) {
-        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
-    }
-    if (error instanceof ToolChoiceIgnoredError) {
-        // The route answered; it broke a declared guarantee rather than failing to
-        // be available, so its breaker is not charged for it.
-        return { outcome: "error", reason: error.message, countsAgainstHealth: false };
-    }
-    if (error instanceof RateGuardTimeoutError) {
-        // Self-inflicted pacing, not provider ill-health. Counting it would let the
-        // client's own throttling open a breaker on a perfectly healthy provider
-        // and permanently reroute traffic nobody chose to reroute.
-        return { outcome: "skipped", reason: error.message, countsAgainstHealth: false };
-    }
-    const reason = error instanceof Error ? error.message : String(error);
-    if (/abort/i.test(reason)) {
-        return {
-            outcome: "timeout",
-            reason: `aborted: ${reason}`,
-            countsAgainstHealth: true,
-        };
-    }
-    return { outcome: "error", reason, countsAgainstHealth: true };
+function isSameReportedModel(reported, expected) {
+    const a = reported.trim().toLowerCase();
+    const b = expected.trim().toLowerCase();
+    return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
 }
 /**
- * Whether the caller has stopped waiting.
+ * How an attempt's model relates to the configured one.
  *
- * Read through a function rather than inline, because `AbortSignal.aborted` is
- * a live getter: it can flip to true while a leg is in flight, but a compiler
- * that narrowed it at the top of the loop would prove the later check
- * unreachable and invite its removal. The check is not redundant — it is the
- * only thing that stops the chain spending money on an answer nobody will read.
+ * A leg addressed to a different model class is `different` whatever it
+ * reported. A leg addressed to the configured class is `same` only when it
+ * answered and the provider named the expected model; `different` when the
+ * provider named another; `unknown` when it answered without saying. An
+ * attempt that never answered carries the relation of the model it was
+ * addressed to.
  *
- * @param signal The caller's signal, if any.
- * @returns Whether the call has been cancelled.
+ * @param route The attempt's route.
+ * @param configuredClass The configured model class.
+ * @param fields What the attempt recorded.
+ * @returns The relation.
  */
-function isAborted(signal) {
-    return signal !== undefined && signal.aborted;
+function modelClassRelationOf(route, configuredClass, fields) {
+    if (modelClassOf(route) !== configuredClass) {
+        return "different";
+    }
+    if (fields.outcome !== "ok") {
+        return "same";
+    }
+    if (fields.servedModel === undefined || fields.servedModel === null) {
+        return "unknown";
+    }
+    return isSameReportedModel(fields.servedModel, route.modelId) ? "same" : "different";
 }
 /**
- * The usage a failed leg was billed for, when the leg reached an answer.
+ * The prompt size the latency evidence is bucketed by.
  *
- * A leg that failed after the provider answered — content that does not parse,
- * or prose where a tool call was mandatory — was still charged. A leg that
- * never answered (timeout, outage, skip) carries no usage, and none is invented.
- *
- * @param error The thrown value.
- * @returns The billed usage, or undefined when the leg never produced an answer.
+ * @param execution The call.
+ * @returns Estimated prompt tokens, or null.
  */
-function billedUsageOf(error) {
-    if (error instanceof LlmResponseFormatError || error instanceof ToolChoiceIgnoredError) {
-        return error.usage;
-    }
-    return undefined;
+function promptTokensOf(execution) {
+    return estimatePromptTokens([
+        execution.content,
+        execution.developerPrompt,
+        execution.context,
+    ]);
 }
 /**
  * Walk a chain until a leg answers.
@@ -73624,12 +74904,58 @@ function billedUsageOf(error) {
  * @param alias The alias being served, for error attribution.
  * @param execution The call context.
  * @returns The first successful leg's answer, with the full attempt record.
+ * @throws {LlmDeadlineExceededError} When the caller's deadline ran out first.
  * @throws {ChainExhaustedError} When no leg produced an answer.
  */
 async function executeChain(alias, execution) {
     const now = execution.now ?? Date.now;
+    const startedAt = now();
     const attempts = [];
+    const firstRoute = execution.legs[0]?.route;
+    const configuredClass = execution.configuredModelClass ?? (firstRoute === undefined ? "" : modelClassOf(firstRoute));
+    const policy = execution.crossModelPolicy ?? "allow_record";
+    const promptTokens = execution.latency === undefined ? null : promptTokensOf(execution);
     let totalUsage = EMPTY_USAGE;
+    let dispatchIndex = 0;
+    let deadlineHit = false;
+    let crossModelDenied = false;
+    let lastModelClass = null;
+    /**
+     * Record one attempt with its provenance.
+     *
+     * @param route The attempt's route.
+     * @param fields What happened.
+     * @param dispatch Whether it was a hedge, and its dispatch index.
+     * @param servedProvider The provider's own report of who served, if any.
+     * @returns The record.
+     */
+    const record = (route, fields, dispatch, servedProvider) => {
+        const full = {
+            ...fields,
+            servedProvider: servedProvider ?? route.providerName,
+            modelClass: modelClassOf(route),
+            modelClassRelation: modelClassRelationOf(route, configuredClass, fields),
+            ...(dispatch === undefined
+                ? {}
+                : { hedged: dispatch.hedged, attemptIndex: dispatch.attemptIndex }),
+        };
+        attempts.push(full);
+        execution.onAttempt?.(full);
+        return full;
+    };
+    /**
+     * The identity fields of a leg that was never dispatched.
+     *
+     * @param route The leg's route.
+     * @returns The fields.
+     */
+    const undispatched = (route) => ({
+        routeKey: route.routeKey,
+        role: route.role,
+        provider: route.providerName,
+        modelId: route.modelId,
+        durationMs: 0,
+    });
     for (const leg of execution.legs) {
         const { route } = leg;
         if (isAborted(execution.callerSignal)) {
@@ -73637,108 +74963,80 @@ async function executeChain(alias, execution) {
             // spend money on an answer nobody will read.
             break;
         }
-        if (leg.params instanceof UnsupportedCapabilityError) {
-            const record = {
-                routeKey: route.routeKey,
-                role: route.role,
-                provider: route.providerName,
-                modelId: route.modelId,
+        if (policy === "deny" && modelClassOf(route) !== configuredClass) {
+            crossModelDenied = true;
+            record(route, {
+                ...undispatched(route),
                 outcome: "skipped",
-                durationMs: 0,
-                reason: leg.params.message,
-            };
-            attempts.push(record);
-            execution.onAttempt?.(record);
+                reason: `cross-model leg denied by policy: configured model is ${configuredClass}, this leg serves ${modelClassOf(route)}`,
+            });
+            continue;
+        }
+        if (leg.params instanceof UnsupportedCapabilityError) {
+            record(route, { ...undispatched(route), outcome: "skipped", reason: leg.params.message });
             continue;
         }
         if (!execution.breakers.allows(route.routeKey)) {
-            const record = {
-                routeKey: route.routeKey,
-                role: route.role,
-                provider: route.providerName,
-                modelId: route.modelId,
+            record(route, {
+                ...undispatched(route),
                 outcome: "breaker-open",
-                durationMs: 0,
                 reason: `circuit breaker is ${execution.breakers.stateOf(route.routeKey)}`,
-            };
-            attempts.push(record);
-            execution.onAttempt?.(record);
+            });
             continue;
         }
         const budgetMs = legBudgetMs(route.timeoutMs, execution.deadlineAtMs, now());
         if (budgetMs <= 0) {
             // The caller's deadline is spent. Dispatching now would start a call
             // that is cancelled the moment it begins, and charge nothing but noise.
-            const record = {
-                routeKey: route.routeKey,
-                role: route.role,
-                provider: route.providerName,
-                modelId: route.modelId,
+            deadlineHit = true;
+            record(route, {
+                ...undispatched(route),
                 outcome: "skipped",
-                durationMs: 0,
                 reason: "caller deadline exhausted before this leg",
-            };
-            attempts.push(record);
-            execution.onAttempt?.(record);
+            });
             continue;
         }
-        const startedAt = now();
-        const holdsProbe = execution.breakers.onAttemptStart(route.routeKey);
-        try {
-            const response = await runLeg(leg, leg.params, execution, budgetMs);
-            execution.breakers.onSuccess(route.routeKey);
-            totalUsage = sumUsage(totalUsage, response.usage);
-            const record = {
-                routeKey: route.routeKey,
-                role: route.role,
-                provider: route.providerName,
-                modelId: route.modelId,
-                outcome: "ok",
-                durationMs: now() - startedAt,
-                budgetMs,
-                servedModel: response.servedModel ?? null,
-                usage: response.usage,
-            };
-            attempts.push(record);
-            execution.onAttempt?.(record);
-            return { response, servedBy: route, attempts, totalUsage };
+        lastModelClass = modelClassOf(route);
+        const group = await runSameModelGroup(leg, budgetMs, budgetMs < route.timeoutMs, {
+            request: execution,
+            breakers: execution.breakers,
+            now,
+            policy: execution.hedging,
+            tracker: execution.latency,
+            promptTokens,
+            admitDuplicate: execution.admitDuplicate ?? (() => false),
+            record: (attemptRoute, fields, dispatch, servedProvider) => {
+                record(attemptRoute, fields, dispatch, servedProvider);
+            },
+            nextAttemptIndex: () => {
+                const index = dispatchIndex;
+                dispatchIndex += 1;
+                return index;
+            },
+        });
+        for (const usage of group.billed) {
+            totalUsage = sumUsage(totalUsage, usage);
         }
-        catch (error) {
-            const { outcome, reason, countsAgainstHealth } = classify(error, execution.callerSignal);
-            if (countsAgainstHealth) {
-                execution.breakers.onFailure(route.routeKey);
-            }
-            else if (holdsProbe) {
-                // No verdict on the route's health, but the probe slot this attempt
-                // took must come back, or a half-open route admits no probe ever again.
-                execution.breakers.onAttemptAbandoned(route.routeKey);
-            }
-            // A provider that answered — with unparseable content, or in prose where a
-            // tool call was mandatory — still billed for the answer; the spend belongs
-            // in the total whether or not a later leg serves.
-            const billed = billedUsageOf(error);
-            const answeredBy = error instanceof ToolChoiceIgnoredError ? error.servedModel : undefined;
-            totalUsage = sumUsage(totalUsage, billed);
-            const record = {
-                routeKey: route.routeKey,
-                role: route.role,
-                provider: route.providerName,
-                modelId: route.modelId,
-                outcome,
-                durationMs: now() - startedAt,
-                budgetMs,
-                reason,
-                ...(answeredBy === undefined ? {} : { servedModel: answeredBy }),
-                ...(billed === undefined ? {} : { usage: billed }),
+        deadlineHit = deadlineHit || group.deadlineBound;
+        if (group.answer !== undefined) {
+            const winner = attempts.find((attempt) => attempt.outcome === "ok" && attempt.routeKey === group.answer?.route.routeKey);
+            return {
+                response: group.answer.response,
+                servedBy: group.answer.route,
+                attempts,
+                totalUsage,
+                modelClassRelation: winner?.modelClassRelation ?? "unknown",
+                hedged: group.answer.hedged,
             };
-            attempts.push(record);
-            execution.onAttempt?.(record);
-            if (outcome === "skipped" && isAborted(execution.callerSignal)) {
-                break;
-            }
         }
+        if (isAborted(execution.callerSignal)) {
+            break;
+        }
+    }
+    if (deadlineHit && !isAborted(execution.callerSignal) && execution.deadlineAtMs !== undefined) {
+        throw new LlmDeadlineExceededError(alias, attempts, totalUsage, execution.deadlineAtMs - startedAt, lastModelClass);
     }
-    throw new ChainExhaustedError(alias, attempts, totalUsage);
+    throw new ChainExhaustedError(alias, attempts, totalUsage, crossModelDenied ? "cross_model_denied" : "exhausted");
 }
 
 var schema_version = 1;
@@ -73754,7 +75052,38 @@ var defaults = {
 	circuit_breaker: {
 		failure_threshold: 5,
 		cooldown_ms: 60000,
-		half_open_probes: 1
+		capacity_cooldown_ms: 15000,
+		half_open_probes: 1,
+		probe_fraction: 0.1,
+		latency_trip: {
+			enabled: false,
+			slo_ms: {
+				"hot-path": 20000,
+				background: 60000,
+				batch: 240000
+			},
+			quantile: 0.9,
+			window_size: 20,
+			trip_windows: 3,
+			of_windows: 5
+		}
+	},
+	hedging: {
+		max_same_model_hedges: 1,
+		hedge_quantile: 0.9,
+		timeout_quantile: 0.99,
+		k_timeout: 3,
+		attempt_timeout_floor_ms: 5000,
+		max_attempt_share: 0.5,
+		duplicate_headroom_reserve: 0.25,
+		min_samples: 20,
+		window_size: 200,
+		sample_max_age_ms: 900000,
+		prompt_token_buckets: [
+			2000,
+			8000,
+			32000
+		]
 	}
 };
 var providers = {
@@ -74490,6 +75819,86 @@ const ISOLATED_SUFFIX = ".isolated";
  * caller change every other caller's routing.
  */
 const routeTable = rawTable;
+/** Separates a leg's route key from the provider of one of its equivalents. */
+const EQUIVALENT_SEPARATOR = "~";
+/** Gateway name segment for an equivalent leg. */
+const EQUIVALENT_NAMESPACE = "equivalent";
+/**
+ * Whether a number lies in a closed or open range.
+ *
+ * @param value The value.
+ * @param min Lower bound.
+ * @param max Upper bound.
+ * @param open Whether the bounds are excluded.
+ * @returns Whether it is in range.
+ */
+function inRange(value, min, max, open) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return false;
+    }
+    return open ? value > min && value < max : value >= min && value <= max;
+}
+/**
+ * Bounds violations in the tail-latency defaults (hedging, probe scaling and
+ * the latency trip).
+ *
+ * These values are mechanics rather than routing choices, but a value outside
+ * its bounds turns a mechanic into a routing change — a quantile of 1.0 makes
+ * every hedge wait for the slowest answer ever seen, a zero floor lets a
+ * measured timeout cut an attempt the instant it starts — so they are checked
+ * as strictly as the routing itself.
+ *
+ * @param defaults The table's defaults.
+ * @returns One message per violation; empty when every value is in bounds.
+ */
+function tailLatencyViolations(defaults) {
+    const violations = [];
+    const check = (ok, message) => {
+        if (!ok) {
+            violations.push(message);
+        }
+    };
+    const hedging = defaults.hedging;
+    if (hedging !== undefined) {
+        check(Number.isInteger(hedging.max_same_model_hedges) && inRange(hedging.max_same_model_hedges, 0, 3, false), "hedging.max_same_model_hedges must be an integer in [0, 3]");
+        check(inRange(hedging.hedge_quantile, 0.5, 1, true), "hedging.hedge_quantile must be in (0.5, 1)");
+        check(inRange(hedging.timeout_quantile, 0.5, 1, true), "hedging.timeout_quantile must be in (0.5, 1)");
+        check(hedging.timeout_quantile >= hedging.hedge_quantile, "hedging.timeout_quantile must not be below hedging.hedge_quantile");
+        check(inRange(hedging.k_timeout, 1, 10, false), "hedging.k_timeout must be in [1, 10]");
+        check(inRange(hedging.attempt_timeout_floor_ms, 1000, Number.MAX_SAFE_INTEGER, false), "hedging.attempt_timeout_floor_ms must be at least 1000");
+        check(inRange(hedging.max_attempt_share, 0.25, 1, false), "hedging.max_attempt_share must be in [0.25, 1]");
+        check(inRange(hedging.duplicate_headroom_reserve, 0, 0.9, false), "hedging.duplicate_headroom_reserve must be in [0, 0.9]");
+        check(Number.isInteger(hedging.min_samples) && inRange(hedging.min_samples, 5, 10_000, false), "hedging.min_samples must be an integer in [5, 10000]");
+        check(Number.isInteger(hedging.window_size) && hedging.window_size >= hedging.min_samples, "hedging.window_size must be an integer no smaller than min_samples");
+        check(inRange(hedging.sample_max_age_ms, 60_000, Number.MAX_SAFE_INTEGER, false), "hedging.sample_max_age_ms must be at least 60000");
+        check(hedging.prompt_token_buckets.every((edge, index, edges) => Number.isFinite(edge) && edge > 0 && (index === 0 || edge > edges[index - 1])), "hedging.prompt_token_buckets must be positive and strictly ascending");
+    }
+    const breaker = defaults.circuit_breaker;
+    if (breaker.probe_fraction !== undefined) {
+        check(inRange(breaker.probe_fraction, 0, 0.5, false), "circuit_breaker.probe_fraction must be in [0, 0.5]");
+    }
+    const trip = breaker.latency_trip;
+    if (trip !== undefined) {
+        check(inRange(trip.quantile, 0.5, 1, true), "circuit_breaker.latency_trip.quantile must be in (0.5, 1)");
+        check(Number.isInteger(trip.window_size) && trip.window_size >= 5, "circuit_breaker.latency_trip.window_size must be an integer of at least 5");
+        check(Number.isInteger(trip.of_windows) &&
+            Number.isInteger(trip.trip_windows) &&
+            trip.trip_windows >= 1 &&
+            trip.trip_windows <= trip.of_windows, "circuit_breaker.latency_trip needs integer 1 <= trip_windows <= of_windows");
+        for (const latencyClass of Object.keys(defaults.request_timeout_ms)) {
+            check(inRange(trip.slo_ms[latencyClass], 1000, defaults.request_timeout_ms[latencyClass], false), `circuit_breaker.latency_trip.slo_ms.${latencyClass} must be in [1000, its request timeout]`);
+        }
+    }
+    return violations;
+}
+{
+    // Checked when the table loads: it is bundled, so a violation can only
+    // arrive in a release, and it must stop that release rather than run it.
+    const violations = tailLatencyViolations(routeTable.defaults);
+    if (violations.length > 0) {
+        throw new Error(`alias route table has out-of-bounds tail-latency defaults: ${violations.join("; ")}`);
+    }
+}
 /**
  * Every alias the table defines.
  *
@@ -74669,6 +76078,8 @@ function resolveChain(alias, options = {}) {
             });
             continue;
         }
+        const routeKey = routeKeyFor(alias, isolated, route.role);
+        const modelClass = route.model_class ?? admission.modelId;
         resolved.push({
             alias,
             isolated,
@@ -74678,13 +76089,67 @@ function resolveChain(alias, options = {}) {
             modelId: admission.modelId,
             lumicModel: route.lumic_model ?? null,
             params: route.params ?? {},
-            routeKey: routeKeyFor(alias, isolated, route.role),
+            routeKey,
             timeoutMs,
-            retriesPerLeg: routeTable.defaults.retries_per_leg,
+            modelClass,
+            latencyClass: definition.latency_class,
+            equivalents: resolveEquivalents(route, {
+                alias,
+                isolated,
+                routeKey,
+                timeoutMs,
+                modelClass,
+                latencyClass: definition.latency_class,
+            }),
         });
     }
     return { alias, isolated, routes: resolved, exclusions };
 }
+/**
+ * Resolve a leg's same-model equivalents that can serve today.
+ *
+ * An equivalent is admitted by the leg's own rules — a confirmed model id and a
+ * live provider account — and inherits the leg's model class, because being the
+ * same model is what makes it an equivalent. One that cannot serve is simply
+ * absent: it is never a reason to skip the leg.
+ *
+ * @param route The authored leg.
+ * @param leg The resolved leg's identity.
+ * @param leg.alias The alias.
+ * @param leg.isolated Whether this is the isolated variant.
+ * @param leg.routeKey The leg's route key.
+ * @param leg.timeoutMs The leg's budget.
+ * @param leg.modelClass The leg's model class.
+ * @param leg.latencyClass The alias's latency class.
+ * @returns The servable equivalents, in table order.
+ */
+function resolveEquivalents(route, leg) {
+    const resolved = [];
+    for (const equivalent of route.equivalents ?? []) {
+        const provider = routeTable.providers[equivalent.provider];
+        if (provider === undefined ||
+            provider.account_status !== "live" ||
+            equivalent.model_id_status !== "confirmed" ||
+            equivalent.model_id === null) {
+            continue;
+        }
+        resolved.push({
+            alias: leg.alias,
+            isolated: leg.isolated,
+            role: route.role,
+            providerName: equivalent.provider,
+            provider,
+            modelId: equivalent.model_id,
+            lumicModel: equivalent.lumic_model ?? null,
+            params: equivalent.params ?? route.params ?? {},
+            routeKey: `${leg.routeKey}${EQUIVALENT_SEPARATOR}${equivalent.provider}`,
+            timeoutMs: leg.timeoutMs,
+            modelClass: leg.modelClass,
+            latencyClass: leg.latencyClass,
+        });
+    }
+    return resolved;
+}
 /**
  * The permanent closed-incumbent leg of an alias (PD-11).
  *
@@ -74713,6 +76178,12 @@ function closedIncumbentLeg(chain) {
  */
 function gatewayModelNameFor(route, chain) {
     const base = `${route.alias}${route.isolated ? ISOLATED_SUFFIX : ""}`;
+    if (route.routeKey.includes(EQUIVALENT_SEPARATOR)) {
+        // The same model at another provider is its own gateway deployment, named
+        // so the gateway serves exactly that deployment and nothing it might fall
+        // back to on its own.
+        return `${base}.${EQUIVALENT_NAMESPACE}.${route.role}.${route.providerName}`;
+    }
     return chain.routes[0]?.routeKey === route.routeKey
         ? base
         : `${base}.fallback.${route.role}`;
@@ -75000,8 +76471,11 @@ async function resolveDefaultDirectCaller() {
  * gateway by its own model name, so the gateway serves one deployment per leg
  * and needs no fallback of its own. A proxy-side fallback inside a leg would
  * spend the leg's budget on a model the chain did not choose and report the
- * answer as the leg's; the served model is read from the response body so such
- * a substitution stays visible while any remains configured.
+ * answer as the leg's; the served model is read from the gateway's own
+ * served-model header, else from the upstream body's `model`, so such a
+ * substitution stays visible while any remains configured. A body `model` that
+ * merely echoes the name the leg was addressed by is the gateway naming its
+ * model GROUP, not the model that answered, and is reported as unknown.
  *
  * The gateway key is read from the environment by NAME at call time and never
  * stored, logged, or included in an error (PD-2). Reading it per call rather
@@ -75017,6 +76491,14 @@ const ERROR_BODY_EXCERPT = 400;
 const RESPONSE_COST_HEADER = "x-litellm-response-cost";
 /** Response header naming the proxy deployment that served the call. */
 const DEPLOYMENT_ID_HEADER = "x-litellm-model-id";
+/**
+ * Response header in which the gateway reports the upstream model that
+ * actually answered. Takes precedence over the body's `model`, which a proxy
+ * may overwrite with the model-group name it was addressed by.
+ */
+const SERVED_MODEL_HEADER = "x-adaptic-served-model";
+/** Response header in which the gateway reports the upstream provider that answered. */
+const SERVED_PROVIDER_HEADER = "x-adaptic-served-provider";
 /**
  * Thrown when the gateway itself is unreachable, as opposed to a provider
  * behind it failing.
@@ -75179,6 +76661,7 @@ function createGatewayTransport(config) {
                 throw new GatewayResponseError(response.status, await response.text());
             }
             const payload = (await response.json());
+            const addressedAs = body.model;
             const choices = payload.choices;
             const message = choices?.[0]?.message;
             // Usage is read before the content is interpreted. The provider billed for
@@ -75191,14 +76674,36 @@ function createGatewayTransport(config) {
                 tool_calls: Array.isArray(message?.tool_calls)
                     ? message.tool_calls
                     : undefined,
-                // The model the provider says answered, which a proxy-side fallback can
-                // make differ from the leg's route model; unreported stays null.
-                servedModel: nonEmptyOrNull(payload.model),
+                // The model that answered, which a proxy-side fallback can make differ
+                // from the leg's route model; unreported (or only the group echo) stays null.
+                servedModel: servedModelOf(response.headers, payload.model, addressedAs),
                 servedDeploymentId: nonEmptyOrNull(response.headers?.get(DEPLOYMENT_ID_HEADER)),
+                servedProvider: nonEmptyOrNull(response.headers?.get(SERVED_PROVIDER_HEADER)),
             };
         },
     };
 }
+/**
+ * The model that answered, as far as the gateway says.
+ *
+ * The gateway's served-model header is authoritative when present. Otherwise
+ * the body's `model` is used — unless it equals the name the leg was addressed
+ * by, which is the proxy echoing its model group rather than naming the
+ * upstream model, and would otherwise read as a confirmed same-model answer.
+ *
+ * @param headers The response headers.
+ * @param bodyModel The body's `model` field.
+ * @param addressedAs The gateway model name the leg was sent to.
+ * @returns The served model, or null when the gateway did not say.
+ */
+function servedModelOf(headers, bodyModel, addressedAs) {
+    const fromHeader = nonEmptyOrNull(headers?.get(SERVED_MODEL_HEADER));
+    if (fromHeader !== null) {
+        return fromHeader;
+    }
+    const fromBody = nonEmptyOrNull(bodyModel);
+    return fromBody === null || fromBody === addressedAs ? null : fromBody;
+}
 /**
  * Compose the message array for a request.
  *
@@ -75262,7 +76767,9 @@ function interpretContent(content, responseFormat, usage) {
  * Every call gets, in order: alias resolution against the canonical route
  * table, per-provider parameter normalisation, a hard per-leg timeout, a
  * per-route circuit breaker, an ordered fallback chain ending at the closed
- * incumbent, and — where the caller supplies a validator — one schema-feedback
+ * incumbent — each leg first hedged and failed over on the SAME model (see
+ * `hedge.ts`), and a different-model leg reached only when the caller's
+ * cross-model policy allows it — and, where the caller supplies a validator, one schema-feedback
  * retry ahead of the chain. The caller's `timeoutMs` is ONE deadline for the
  * whole call: each leg runs for its route budget or for what remains of that
  * deadline, whichever is shorter, so the chain is the single fallback owner and
@@ -75278,6 +76785,34 @@ const GATEWAY_BASE_URL_ENV = "LLM_GATEWAY_BASE_URL";
 const DEFAULT_GATEWAY_KEY_ENV = "LLM_GATEWAY_API_KEY";
 /** Process-wide breaker registry, so route health is shared across call sites. */
 let breakers = new CircuitBreakerRegistry(routeTable.defaults.circuit_breaker);
+/**
+ * Build the process-wide latency tracker from the table's hedging defaults.
+ *
+ * @param now Clock.
+ * @returns The tracker, or undefined when the table configures no hedging.
+ */
+function buildLatencyTracker(now) {
+    const hedging = routeTable.defaults.hedging;
+    if (hedging === undefined) {
+        return undefined;
+    }
+    return new LegLatencyTracker({
+        minSamples: hedging.min_samples,
+        windowSize: hedging.window_size,
+        sampleMaxAgeMs: hedging.sample_max_age_ms,
+        promptTokenBuckets: hedging.prompt_token_buckets,
+    }, now);
+}
+/**
+ * Process-wide healthy-latency evidence, shared across call sites for the same
+ * reason the breakers are: a model's health is one population however many
+ * callers reach it.
+ */
+let latencyTracker = buildLatencyTracker();
+/** Same-model hedging policy from the table, or undefined when none is configured. */
+const hedgingPolicy = routeTable.defaults.hedging === undefined
+    ? undefined
+    : sameModelPolicyFrom(routeTable.defaults.hedging);
 /** Active runtime wiring. */
 let config = {};
 /** Lazily built transports, rebuilt whenever configuration changes. */
@@ -75299,6 +76834,28 @@ function configureLlmClient(next) {
     gatewayTransport = null;
     directTransport = null;
     breakers = new CircuitBreakerRegistry(routeTable.defaults.circuit_breaker, next.now);
+    latencyTracker = buildLatencyTracker(next.now);
+}
+/**
+ * Inspect the healthy-latency evidence the hedging controls read.
+ *
+ * @returns The live tracker, or undefined when the table configures no hedging.
+ */
+function llmLatencyTracker() {
+    return latencyTracker;
+}
+/**
+ * Whether a duplicate attempt on the same provider may start.
+ *
+ * @param route The leg the duplicate would address.
+ * @param reserveFraction Share of the provider's capacity kept free.
+ * @returns Whether it may start.
+ */
+function admitDuplicate(route, reserveFraction) {
+    if (config.duplicateAdmission !== undefined) {
+        return config.duplicateAdmission(route, reserveFraction);
+    }
+    return hasDuplicateHeadroom(route.providerName, route.modelId, reserveFraction);
 }
 /**
  * Inspect route health.
@@ -75371,10 +76928,11 @@ function directFor() {
  * @param options The caller's options.
  * @param responseFormat The requested response shape.
  * @param transport The transport to carry every leg.
+ * @param admitEquivalent Which same-model equivalents this transport can reach.
  * @returns Prepared legs, in chain order.
  */
-function prepareLegs(chain, options, responseFormat, transport) {
-    return chain.routes.map((route) => {
+function prepareLegs(chain, options, responseFormat, transport, admitEquivalent = () => true) {
+    const prepare = (route) => {
         try {
             return {
                 route,
@@ -75388,7 +76946,11 @@ function prepareLegs(chain, options, responseFormat, transport) {
             }
             throw error;
         }
-    });
+    };
+    return chain.routes.map((route) => ({
+        ...prepare(route),
+        equivalents: (route.equivalents ?? []).filter(admitEquivalent).map(prepare),
+    }));
 }
 /**
  * Call a language model by semantic alias.
@@ -75432,6 +76994,26 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
     }
     const gateway = gatewayFor();
     const attemptLog = [];
+    // What every execution of this call shares, whichever transport carries it.
+    // The configured model is the head of the full chain, so the degraded path —
+    // whose legs are only the closed incumbents — still knows that its answer is
+    // a different model from the one configured.
+    const shared = {
+        responseFormat,
+        developerPrompt: options.developerPrompt,
+        context: options.context,
+        breakers,
+        correlationId: options.correlationId,
+        callerSignal: options.signal,
+        deadlineAtMs,
+        now: config.now,
+        onAttempt: (record) => attemptLog.push(record),
+        hedging: hedgingPolicy,
+        latency: latencyTracker,
+        admitDuplicate,
+        crossModelPolicy: options.crossModelPolicy,
+        configuredModelClass: modelClassOf(chain.routes[0]),
+    };
     /**
      * Run the chain, falling back from the gateway to the degraded direct path
      * only when the gateway itself is unreachable.
@@ -75444,17 +77026,9 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
         if (gateway !== null) {
             try {
                 const outcome = await executeChain(options.alias, {
+                    ...shared,
                     legs: prepareLegs(chain, options, responseFormat, gateway),
                     content: boundContent,
-                    responseFormat,
-                    developerPrompt: options.developerPrompt,
-                    context: options.context,
-                    breakers,
-                    correlationId: options.correlationId,
-                    callerSignal: options.signal,
-                    deadlineAtMs,
-                    now: config.now,
-                    onAttempt: (record) => attemptLog.push(record),
                 });
                 return { ...outcome, degraded: false };
             }
@@ -75479,17 +77053,11 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
             });
         }
         const outcome = await executeChain(options.alias, {
-            legs: prepareLegs({ ...chain, routes: closedLegs }, options, responseFormat, direct),
+            ...shared,
+            // The direct transport serves closed vendors only, so only a closed
+            // equivalent can be reached on the degraded path.
+            legs: prepareLegs({ ...chain, routes: closedLegs }, options, responseFormat, direct, (route) => route.provider.tier === "closed"),
             content: boundContent,
-            responseFormat,
-            developerPrompt: options.developerPrompt,
-            context: options.context,
-            breakers,
-            correlationId: options.correlationId,
-            callerSignal: options.signal,
-            deadlineAtMs,
-            now: config.now,
-            onAttempt: (record) => attemptLog.push(record),
         });
         return { ...outcome, degraded: true };
     };
@@ -75504,6 +77072,8 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
             attempts: attemptLog,
             degraded: outcome.degraded,
             totalUsage: outcome.totalUsage,
+            modelClassRelation: outcome.modelClassRelation,
+            hedged: outcome.hedged,
         };
     }
     // A validator is only meaningful against a text prompt, because the retry has
@@ -75521,6 +77091,8 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
                 servedBy: outcome.servedBy,
                 degraded: outcome.degraded,
                 totalUsage: outcome.totalUsage,
+                modelClassRelation: outcome.modelClassRelation,
+                hedged: outcome.hedged,
             };
             return outcome.response;
         },
@@ -75538,6 +77110,8 @@ async function callLLMByAlias(content, responseFormat = "text", options) {
         attempts: attemptLog,
         degraded: routing.degraded,
         totalUsage: validated.totalUsage,
+        modelClassRelation: routing.modelClassRelation,
+        hedged: routing.hedged,
     };
 }
 /**
@@ -80999,13 +82573,17 @@ exports.DEFAULT_TRADING_POLICY = DEFAULT_TRADING_POLICY;
 exports.DataFormatError = DataFormatError;
 exports.DirectTransportRefusedError = DirectTransportRefusedError;
 exports.DuplicateClientOrderIdError = DuplicateClientOrderIdError;
+exports.EQUIVALENT_SEPARATOR = EQUIVALENT_SEPARATOR;
 exports.GatewayResponseError = GatewayResponseError;
 exports.GatewayUnreachableError = GatewayUnreachableError;
 exports.HttpClientError = HttpClientError;
 exports.HttpServerError = HttpServerError;
 exports.KEEP_ALIVE_DEFAULTS = KEEP_ALIVE_DEFAULTS;
+exports.LegLatencyTracker = LegLatencyTracker;
+exports.LlmDeadlineExceededError = LlmDeadlineExceededError;
 exports.LlmResponseFormatError = LlmResponseFormatError;
 exports.MARKET_DATA_API = MARKET_DATA_API;
+exports.MIN_CONVERTED_TRAIL_PERCENT = MIN_CONVERTED_TRAIL_PERCENT;
 exports.MassiveAggregatesResponseSchema = MassiveAggregatesResponseSchema;
 exports.MassiveApiError = MassiveApiError;
 exports.MassiveDailyOpenCloseSchema = MassiveDailyOpenCloseSchema;
@@ -81028,6 +82606,8 @@ exports.RISK_FREE_RATE_TTL_MS = RISK_FREE_RATE_TTL_MS;
 exports.RateGuardTimeoutError = RateGuardTimeoutError;
 exports.RateLimitError = RateLimitError;
 exports.RawMassivePriceDataSchema = RawMassivePriceDataSchema;
+exports.SERVED_MODEL_HEADER = SERVED_MODEL_HEADER;
+exports.SERVED_PROVIDER_HEADER = SERVED_PROVIDER_HEADER;
 exports.SchemaRetryExhaustedError = SchemaRetryExhaustedError;
 exports.StampedeProtectedCache = StampedeProtectedCache;
 exports.StreamProviderError = StreamProviderError;
@@ -81037,6 +82617,7 @@ exports.TimeoutError = TimeoutError;
 exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
 exports.ToolChoiceIgnoredError = ToolChoiceIgnoredError;
 exports.TradeError = TradeError;
+exports.TrailUnitConversionRefusedError = TrailUnitConversionRefusedError;
 exports.TrailingStopValidationError = TrailingStopValidationError;
 exports.USDC_PAIRS = USDC_PAIRS;
 exports.USDT_PAIRS = USDT_PAIRS;
@@ -81122,6 +82703,7 @@ exports.createVerticalSpread = createVerticalSpread$1;
 exports.createVerticalSpreadAdvanced = createVerticalSpread;
 exports.enrichAlpacaError = enrichAlpacaError;
 exports.entryWithPercentStopLoss = entryWithPercentStopLoss;
+exports.estimatePromptTokens = estimatePromptTokens;
 exports.exerciseOption = exerciseOption;
 exports.extractAlpacaBrokerError = extractAlpacaBrokerError;
 exports.extractGreeks = extractGreeks;
@@ -81224,6 +82806,7 @@ exports.groupOrdersByStatus = groupOrdersByStatus;
 exports.groupOrdersBySymbol = groupOrdersBySymbol;
 exports.guardSnapshots = guardSnapshots;
 exports.hasActiveTrailingStop = hasActiveTrailingStop;
+exports.hasDuplicateHeadroom = hasDuplicateHeadroom;
 exports.hasOptionLiquidity = hasGoodLiquidity;
 exports.hasStockLiquidity = hasGoodLiquidity$1;
 exports.hasSufficientVolume = hasSufficientVolume;
@@ -81242,6 +82825,7 @@ exports.isOrderFilled = isOrderFilled;
 exports.isOrderOpen = isOrderOpen;
 exports.isOrderTerminalStatus = isOrderTerminal$1;
 exports.isPendingCancelRejection = isPendingCancelRejection;
+exports.isSameReportedModel = isSameReportedModel;
 exports.isSupportedCryptoPair = isSupportedCryptoPair;
 exports.isTransientNetworkError = isTransientNetworkError;
 exports.legBudgetMs = legBudgetMs;
@@ -81252,6 +82836,9 @@ exports.limitsInventory = limitsInventory;
 exports.listAliases = listAliases;
 exports.llmAliases = llmAliases;
 exports.llmBreakers = llmBreakers;
+exports.llmLatencyTracker = llmLatencyTracker;
+exports.modelClassOf = modelClassOf;
+exports.modelClassRelationOf = modelClassRelationOf;
 exports.normaliseAnthropicStream = normaliseAnthropicStream;
 exports.normaliseOpenAiStream = normaliseOpenAiStream;
 exports.normaliseParams = normaliseParams;
@@ -81266,11 +82853,13 @@ exports.parseOCCSymbol = parseOCCSymbol;
 exports.protectLongPosition = protectLongPosition;
 exports.protectShortPosition = protectShortPosition;
 exports.rateLimiters = rateLimiters$1;
+exports.readTrailUnit = readTrailUnit;
 exports.resetLogger = resetLogger;
 exports.resetProviderGuards = resetProviderGuards;
 exports.resetRiskFreeRateCache = resetRiskFreeRateCache;
 exports.resolveChain = resolveChain;
 exports.resolveDefaultDirectCaller = resolveDefaultDirectCaller;
+exports.resolveReplaceTrail = resolveReplaceTrail;
 exports.risk = riskNs;
 exports.rollOptionPosition = rollOptionPosition;
 exports.roundPriceForAlpaca = roundPriceForAlpaca$3;
@@ -81285,12 +82874,14 @@ exports.sellAllCrypto = sellAllCrypto;
 exports.sellCryptoNotional = sellCryptoNotional;
 exports.sellToClose = sellToClose;
 exports.sellToOpen = sellToOpen;
+exports.servedModelOf = servedModelOf;
 exports.setLogger = setLogger;
 exports.setRiskFreeRate = setRiskFreeRate;
 exports.shortWithStopLoss = shortWithStopLoss;
 exports.sortOrdersByDate = sortOrdersByDate;
 exports.strategy = strategyNs;
 exports.sumUsage = sumUsage;
+exports.tailLatencyViolations = tailLatencyViolations;
 exports.tradingPolicy = index;
 exports.trailingStops = trailingStops;
 exports.unavailableStatistic = unavailableStatistic;