@bitbaum/ai-kit 1.4.2 → 1.6.0

package/dist/catalog-fetch.d.ts

@@ -0,0 +1,77 @@
+/**
+ * One GET /models, parsed once, for everything that needs to know what a vendor
+ * currently offers.
+ *
+ * `catalog.ts` already fetched this list to answer "has a pinned id rotted".
+ * `resolve.ts` needs the SAME request to answer "what else is on the shelf, and
+ * what does the vendor say about it" — and the ids alone cannot answer that.
+ *
+ * Rather than issue a second, slightly different GET (the exact failure
+ * catalog.ts's own header complains about — "the app that wrote its own first
+ * wrote it slightly differently"), both read this.
+ *
+ * ── Two vendors, two schemas, one shape ──────────────────────────────────────
+ * Verified against live responses on 2026-09-13, and they do NOT agree:
+ *
+ *   OpenRouter  architecture.output_modalities   supported_parameters: ["tools"]
+ *   Groq        output_modalities (top level)    supported_features:   ["json_mode"]
+ *
+ * So a reader that knows only OpenRouter's shape reports every Groq model as
+ * having no text output and no tools — which, in a filter, silently removes a
+ * working vendor. Normalising here means each consumer states its requirement
+ * once instead of learning both schemas.
+ *
+ * ── Unknown is a value, not a default ────────────────────────────────────────
+ * Every normalised field is nullable, and null means "the vendor did not say".
+ * That is deliberately distinct from false. A filter that treats "did not say"
+ * as "does not support" narrows silently as vendors change their schemas; one
+ * that treats it as "supports" invents capability. Callers must choose, and the
+ * choice is visible at the call site because the type forces it.
+ */
+/** What a vendor's catalogue says about one model, in one shape. */
+export type ModelRecord = {
+    id: string;
+    /** Output modalities, or null when the vendor does not publish them. */
+    outputModalities: string[] | null;
+    /**
+     * True only when the vendor publishes a price and every component is zero.
+     * Null when it publishes no price at all.
+     *
+     * Not the same question as "does the `:free` suffix appear". Checked live on
+     * 2026-09-13: OpenRouter lists 19 ids ending `:free` and 22 priced at zero —
+     * and the three zero-priced ids WITHOUT the suffix include `openrouter/free`,
+     * the auto-router that is the most rot-resistant entry in the whole chain.
+     * A suffix check misses it. Price is the vendor telling you who pays.
+     */
+    costsNothing: boolean | null;
+    /** True when the vendor declares tool/function calling. Null when unstated. */
+    tools: boolean | null;
+    /** Vendor-declared context window, when published. */
+    contextLength: number | null;
+    /**
+     * Date the vendor says this id stops working (ISO yyyy-mm-dd), when it says so.
+     *
+     * Rare but real: of 445 OpenRouter models on 2026-09-13, five carried one, and
+     * one of those was a FREE model expiring in 17 days. Where present this turns
+     * rot from something detected afterwards into something known in advance, so
+     * it is worth surfacing even though most models omit it.
+     */
+    expiresOn: string | null;
+};
+export type FetchCatalogOptions = {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/**
+ * Every model one vendor lists, normalised — or NULL when the catalogue could
+ * not be read.
+ *
+ * Null covers no key, a network failure, a non-200, an unparseable body, and a
+ * body that parses but lists nothing. It never means "this vendor has no
+ * models", and the distinction is not academic: while building this, a local
+ * checkout missing GROQ_API_KEY answered 401, and a reader that collapsed that
+ * into an empty list reported BOTH live Groq models as retired. Had resolution
+ * trusted it, an expired key would have emptied the chain rather than failing a
+ * single call.
+ */
+export declare function fetchCatalog(baseUrl: string, key: string | undefined, opts?: FetchCatalogOptions): Promise<ModelRecord[] | null>;

package/dist/catalog-fetch.js

@@ -0,0 +1,109 @@
+/**
+ * One GET /models, parsed once, for everything that needs to know what a vendor
+ * currently offers.
+ *
+ * `catalog.ts` already fetched this list to answer "has a pinned id rotted".
+ * `resolve.ts` needs the SAME request to answer "what else is on the shelf, and
+ * what does the vendor say about it" — and the ids alone cannot answer that.
+ *
+ * Rather than issue a second, slightly different GET (the exact failure
+ * catalog.ts's own header complains about — "the app that wrote its own first
+ * wrote it slightly differently"), both read this.
+ *
+ * ── Two vendors, two schemas, one shape ──────────────────────────────────────
+ * Verified against live responses on 2026-09-13, and they do NOT agree:
+ *
+ *   OpenRouter  architecture.output_modalities   supported_parameters: ["tools"]
+ *   Groq        output_modalities (top level)    supported_features:   ["json_mode"]
+ *
+ * So a reader that knows only OpenRouter's shape reports every Groq model as
+ * having no text output and no tools — which, in a filter, silently removes a
+ * working vendor. Normalising here means each consumer states its requirement
+ * once instead of learning both schemas.
+ *
+ * ── Unknown is a value, not a default ────────────────────────────────────────
+ * Every normalised field is nullable, and null means "the vendor did not say".
+ * That is deliberately distinct from false. A filter that treats "did not say"
+ * as "does not support" narrows silently as vendors change their schemas; one
+ * that treats it as "supports" invents capability. Callers must choose, and the
+ * choice is visible at the call site because the type forces it.
+ */
+function asStringArray(v) {
+    if (!Array.isArray(v))
+        return null;
+    const out = v.filter((x) => typeof x === "string");
+    return out.length > 0 ? out : null;
+}
+/** Zero only when a price is published AND every numeric component is zero. */
+function priceIsZero(pricing) {
+    if (!pricing || typeof pricing !== "object")
+        return null;
+    const entries = Object.entries(pricing);
+    const numbers = entries
+        .map(([, v]) => (typeof v === "string" || typeof v === "number" ? Number(v) : NaN))
+        .filter((n) => Number.isFinite(n));
+    if (numbers.length === 0)
+        return null;
+    return numbers.every((n) => n === 0);
+}
+/** Tool support as DECLARED by the vendor, across both known schemas. */
+function declaresTools(m) {
+    const params = asStringArray(m.supported_parameters);
+    if (params)
+        return params.includes("tools");
+    const features = asStringArray(m.supported_features);
+    if (features)
+        return features.some((f) => f === "tools" || f === "tool_use");
+    return null;
+}
+function normalise(m) {
+    const id = typeof m.id === "string" ? m.id : "";
+    if (!id)
+        return null;
+    const arch = (m.architecture ?? {});
+    const expires = m.expiration_date;
+    return {
+        id,
+        outputModalities: asStringArray(arch.output_modalities) ?? asStringArray(m.output_modalities),
+        costsNothing: priceIsZero(m.pricing),
+        tools: declaresTools(m),
+        contextLength: typeof m.context_length === "number" ? m.context_length : null,
+        expiresOn: typeof expires === "string" && expires.trim() ? expires.trim() : null,
+    };
+}
+/**
+ * Every model one vendor lists, normalised — or NULL when the catalogue could
+ * not be read.
+ *
+ * Null covers no key, a network failure, a non-200, an unparseable body, and a
+ * body that parses but lists nothing. It never means "this vendor has no
+ * models", and the distinction is not academic: while building this, a local
+ * checkout missing GROQ_API_KEY answered 401, and a reader that collapsed that
+ * into an empty list reported BOTH live Groq models as retired. Had resolution
+ * trusted it, an expired key would have emptied the chain rather than failing a
+ * single call.
+ */
+export async function fetchCatalog(baseUrl, key, opts = {}) {
+    if (!key?.trim())
+        return null;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/models`, {
+            headers: { Authorization: `Bearer ${key.trim()}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!Array.isArray(body?.data))
+            return null;
+        const records = body.data
+            .map((m) => normalise((m ?? {})))
+            .filter((m) => m !== null);
+        return records.length > 0 ? records : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/catalog.js

@@ -22,29 +22,23 @@
  * costs real tokens and cannot run on a timer; existence can.
  */
 import { providerModels } from "./chain.js";
-/** Ids listed by one provider, or null when the catalogue could not be read. */
+import { fetchCatalog } from "./catalog-fetch.js";
+/**
+ * Ids listed by one provider, or null when the catalogue could not be read.
+ *
+ * The request itself now lives in catalog-fetch.ts, because `resolve.ts` needs
+ * the SAME GET and the ids alone cannot tell it what a model costs or can do.
+ * Two near-identical fetches drifting apart is the failure this module's own
+ * header objects to; one fetch, two readers.
+ *
+ * Every null case is preserved exactly — no key, network failure, non-200,
+ * unparseable body, and a body that parses but lists nothing (a malformed
+ * answer, not a vendor with no models: refusing it keeps a bad response from
+ * reading as total rot).
+ */
 async function liveIds(provider, key, fetchImpl, timeoutMs) {
-    try {
-        const res = await fetchImpl(`${provider.baseUrl.replace(/\/$/, "")}/models`, {
-            headers: { Authorization: `Bearer ${key}` },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!res.ok)
-            return null;
-        const body = (await res.json());
-        if (!Array.isArray(body?.data))
-            return null;
-        const ids = body.data
-            .map((m) => (typeof m?.id === "string" ? m.id : ""))
-            .filter((id) => id.length > 0);
-        // A catalogue that parses but lists nothing is a malformed answer, not a
-        // vendor with no models. Refusing it keeps a bad response from reading as
-        // total rot.
-        return ids.length > 0 ? ids : null;
-    }
-    catch {
-        return null;
-    }
+    const records = await fetchCatalog(provider.baseUrl, key, { fetchImpl, timeoutMs });
+    return records ? records.map((r) => r.id) : null;
 }
 /**
  * Check every model a chain would try against what its vendor still lists.

package/dist/index.d.ts

@@ -51,12 +51,14 @@
  */
 export { type Provider, type Env, type Link, type CostVerdict, providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
 export { type CatalogVerdict, type CheckCatalogOptions, checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
+export { type ModelRecord, type FetchCatalogOptions, fetchCatalog } from "./catalog-fetch.js";
+export { type Requirements, type ResolveOptions, type ProviderResolution, resolveChain, applyResolution, routedAroundRot, emptyProviders, resolutionReport, } from "./resolve.js";
 export { type ChainAttemptFailure, type TryChainOptions, ChainExhaustedError, tryChain, } from "./attempt.js";
 export { type ChatMessage, type ContentPart, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
 export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthTracker, createHealthTracker, } from "./health.js";
 export { type LivenessResult, type LivenessOptions, type LivenessProbe, type AiHealthHandlerOptions, createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { type RateLimitKind, classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
-export { type QuotaScope, type QuotaWindow, type QuotaReading, type HeaderBag, readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
+export { type QuotaScope, type QuotaWindow, type QuotaReading, type HeaderBag, readQuota, readingFromRefusal, readingFromRefusalBody, parseResetAt, answersRemaining, } from "./meter.js";
 export { type ParsedToolCall, TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { type PoolId, type RungId, type TierPolicy, type AiPolicy, type UserState, type WallOption, type Wall, type Decision, DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, type ShareInput, type ShareReason, type ShareDecision, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/index.js

@@ -51,12 +51,17 @@
  */
 export { providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
 export { checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
+export { fetchCatalog } from "./catalog-fetch.js";
+// Resolution is the answer to the question `catalog` only asks. checkCatalog
+// REPORTS that a pinned id is gone; resolveChain drops it and calls the next
+// one, so a vendor retirement stops needing a pull request to survive.
+export { resolveChain, applyResolution, routedAroundRot, emptyProviders, resolutionReport, } from "./resolve.js";
 export { ChainExhaustedError, tryChain, } from "./attempt.js";
 export { LinkFailure, complete, linkId, } from "./complete.js";
 export { createHealthTracker, } from "./health.js";
 export { createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
-export { readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
+export { readQuota, readingFromRefusal, readingFromRefusalBody, parseResetAt, answersRemaining, } from "./meter.js";
 export { TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/meter.d.ts

@@ -102,6 +102,7 @@ export declare function readQuota(headers: HeaderBag, link: Link, now?: number):
  * disagreeing with it.
  */
 export declare function readingFromRefusal(link: Link, retryAfterSec: number | null, scope?: QuotaScope, now?: number): QuotaReading;
+export declare function readingFromRefusalBody(link: Link, body: string, retryAfterSec?: number | null, now?: number): QuotaReading | null;
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *

package/dist/meter.js

@@ -196,6 +196,64 @@ export function readingFromRefusal(link, retryAfterSec, scope = "requests", now
         observedAt: now,
     };
 }
+/**
+ * The counter a vendor discloses ONLY when it refuses.
+ *
+ * ── WHY A BODY PARSER EARNS ITS KEEP ─────────────────────────────────────────
+ *
+ * Headers do not describe every limit a vendor enforces. Groq publishes its
+ * per-minute token window and its per-day REQUEST count as headers, and meters
+ * a third limit — tokens per DAY — that appears in no header at all. It is
+ * stated once, in prose, in the body of the 429 that enforces it:
+ *
+ *   Rate limit reached for model `openai/gpt-oss-20b` in organization `org_…`
+ *   service tier `on_demand` on tokens per day (TPD): Limit 200000,
+ *   Used 199773, Requested 571. Please try again in 2m28.608s.
+ *
+ * Observed on production 2026-09-13. Every header the same response carried
+ * looked healthy — 2,672 of 8,000 tokens left this minute, 999 of 1,000
+ * requests left today — while the account was locked out of the model for the
+ * rest of the day. A dashboard fed only by headers therefore reported a
+ * working provider throughout an outage, which is precisely the failure the
+ * top of this file exists to prevent, arriving through a door it left open.
+ *
+ * ── STILL NEVER INVENTS ──────────────────────────────────────────────────────
+ *
+ * Returns null unless the body states the numbers. An unparsed refusal is the
+ * "did not say" state, and the caller should fall back to `readingFromRefusal`,
+ * which records the one fact a 429 always carries: spent, now.
+ */
+const REFUSAL_COUNTER = /on\s+(tokens|requests)\s+per\s+(minute|day)\s*\([^)]*\)\s*:\s*Limit\s+(\d+)\s*,\s*Used\s+(\d+)/i;
+export function readingFromRefusalBody(link, body, retryAfterSec = null, now = Date.now()) {
+    const m = REFUSAL_COUNTER.exec(body);
+    if (!m)
+        return null;
+    const [, rawScope, rawWindow, rawLimit, rawUsed] = m;
+    if (!rawScope || !rawWindow || !rawLimit || !rawUsed)
+        return null;
+    const scope = rawScope.toLowerCase();
+    const window = rawWindow.toLowerCase();
+    const limit = Number(rawLimit);
+    const used = Number(rawUsed);
+    if (!Number.isFinite(limit) || !Number.isFinite(used))
+        return null;
+    return {
+        provider: link.provider.id,
+        model: link.model,
+        scope,
+        // Straight from the vendor's own sentence, so unlike a header name this
+        // window is not a guess and must not be overridden by the provider profile.
+        window,
+        limit,
+        // The refusal names what was consumed, not what is left. Clamped because a
+        // vendor counting a rejected request against the total would otherwise
+        // produce a negative "remaining" and a dashboard that renders nonsense.
+        remaining: Math.max(0, limit - used),
+        resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+        source: "429-body",
+        observedAt: now,
+    };
+}
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *

package/dist/resolve.d.ts

@@ -0,0 +1,159 @@
+/**
+ * resolve — stop writing model ids down.
+ *
+ * ── The problem the chain did not solve ──────────────────────────────────────
+ * `chain.ts` replaced one pinned model with a list of pinned models, and says so
+ * itself: "a single pinned free model is not a configuration, it is a scheduled
+ * outage." `catalog.ts` then noticed the list rots too, and added a check. But a
+ * check only produces a SENTENCE. Somebody still has to read it, edit a file,
+ * open a pull request, wait for CI, and deploy — and until they do, the app is
+ * handing users a model that answers 404.
+ *
+ * That round trip is not hypothetical, it is this module's origin. On
+ * 2026-09-13 a freshly scheduled health check alerted within minutes of its
+ * first run: two ids in a consumer's registry were gone from OpenRouter. The
+ * alert was correct, fast, and completely dependent on a human being available
+ * to act on it. The vendor had published the truth the whole time.
+ *
+ * So: keep the declared list, but treat it as a PREFERENCE, and let the vendor's
+ * own catalogue decide what is actually callable. A retirement stops being an
+ * incident and becomes a no-op.
+ *
+ * ── Three rules, each paid for by a real failure ─────────────────────────────
+ *
+ * 1. NEVER SHRINK ON IGNORANCE. An unreadable catalogue leaves the declared
+ *    list exactly as written and sets `unverified`. While building this, a
+ *    checkout without GROQ_API_KEY got a 401, and the first draft of the probe
+ *    printed "GONE" for both Groq models — both of which were live. Resolution
+ *    that trusted that would let an expired key empty the chain.
+ *
+ * 2. DISCOVERY EXTENDS THE TAIL, NEVER THE HEAD. Declared ids were curated —
+ *    in this package's case probed with a real tool call, because five of nine
+ *    free models turned out to emit tool calls only as text. A discovered id
+ *    has no such evidence behind it, so it may be a last resort and never a
+ *    first choice.
+ *
+ * 3. DISCOVER ONLY WHAT THE VENDOR CALLS FREE, AND ONLY WHAT IT CALLS USABLE.
+ *    Both halves matter, and both are read from the vendor rather than guessed:
+ *
+ *      - Price. Not the `:free` suffix — the published number. Checked live on
+ *        2026-09-13, OpenRouter listed 19 ids ending `:free` and 22 priced at
+ *        zero. Groq publishes prices too, and NONE of its models are zero, so
+ *        discovery there correctly finds nothing and that vendor stays curated.
+ *        A suffix heuristic would have gone looking for `:free` at a vendor
+ *        that does not use the convention; a price check just declines.
+ *
+ *      - Suitability. Of the 19 free OpenRouter ids, one was
+ *        `nemotron-3.5-content-safety` — a classifier, and the only one of the
+ *        19 declaring `tools: false`. Two more zero-priced ids were
+ *        `lyria-3-*`, which emit AUDIO. Adding all zero-priced models to a chat
+ *        chain would have put a safety classifier and a music generator in
+ *        front of a user asking a question. Requiring text output and declared
+ *        tool support removes exactly those three and nothing else.
+ *
+ * ── What this is worth ───────────────────────────────────────────────────────
+ * Measured against the live catalogue on 2026-09-13: `freeChain()` names five
+ * OpenRouter ids by hand; nineteen zero-priced, text-out, tool-capable ids were
+ * available. Same key, same account, no human — a free pool nearly four times
+ * larger, which grows when the vendor adds models and shrinks when it removes
+ * them, without anyone being told.
+ *
+ * ── What this is NOT ─────────────────────────────────────────────────────────
+ * Presence in a catalogue is not proof a model works. This package already
+ * records two counter-examples: an id that answered "Provider returned error"
+ * on probe, and one that returned HTTP 200 with EMPTY content. Resolution fixes
+ * "the id does not exist"; it cannot fix "the id exists and misbehaves." That
+ * is what the chain's own fallback, and observed health, are for. Declared
+ * capability is a starting hypothesis — traffic is the evidence.
+ */
+import { type Env, type Provider } from "./chain.js";
+/** What a discovered model must prove about itself before it joins the tail. */
+export type Requirements = {
+    /** Vendor must publish a price and it must be zero. Default true. */
+    free?: boolean;
+    /** Vendor must declare text as its only output modality. Default true. */
+    textOnly?: boolean;
+    /** Vendor must declare tool/function calling. Default true. */
+    tools?: boolean;
+    /** Minimum published context window, when the vendor publishes one. */
+    minContext?: number;
+};
+export type ResolveOptions = {
+    env?: Env;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /**
+     * Append live models the declaration never named. Default true — that is the
+     * half that makes the pool GROW without a human. Set false to verify the
+     * declared list against the catalogue and nothing more.
+     */
+    discover?: boolean;
+    /** What a discovered model must declare. See Requirements. */
+    require?: Requirements;
+    /**
+     * Cap on discovered ids appended per provider. Default 10.
+     *
+     * A cap, not a preference: the chain is walked in order on failure, so an
+     * unbounded tail turns one bad minute at a vendor into dozens of sequential
+     * requests before the caller sees an error.
+     */
+    maxDiscovered?: number;
+    /** Clock injection for tests. Default `Date.now`. */
+    now?: () => number;
+};
+export type ProviderResolution = {
+    provider: string;
+    /** The ids to actually try, in order: kept declarations, then discovered. */
+    models: string[];
+    /** Declared ids the vendor still lists. */
+    kept: string[];
+    /**
+     * Declared ids the vendor no longer lists. Dropped from `models` — this is
+     * the rot, already routed around rather than merely reported.
+     */
+    dropped: string[];
+    /** Live ids the declaration never named, appended after the kept ones. */
+    discovered: string[];
+    /**
+     * True when the catalogue could not be read, so `models` is the declaration
+     * verbatim and NOTHING here was verified. `dropped` is empty because no id
+     * was confirmed gone — not because none is.
+     */
+    unverified: boolean;
+    /** Ids in `models` the vendor says will stop working, with the date. */
+    expiring: Array<{
+        model: string;
+        on: string;
+    }>;
+};
+/**
+ * Resolve one chain against what its vendors currently offer.
+ *
+ * Costs one GET /models per provider and ZERO tokens — the same property that
+ * made the catalogue check schedulable makes this callable on a warm path, and
+ * consumers are expected to cache the result rather than resolve per request.
+ */
+export declare function resolveChain(chain: Provider[], opts?: ResolveOptions): Promise<ProviderResolution[]>;
+/**
+ * Fold a resolution back into providers, ready for `usableChain`.
+ *
+ * A provider whose every model resolved away is left with an EMPTY model list
+ * rather than being dropped from the chain. `usableChain` already skips links
+ * with nothing to try, and keeping the row means the vendor still appears in
+ * reports — a silently vanished provider is how a chain quietly becomes a
+ * single point of failure without anyone noticing.
+ */
+export declare function applyResolution(chain: Provider[], resolved: ProviderResolution[]): Provider[];
+/** True when any declared id was confirmed gone and routed around. */
+export declare function routedAroundRot(resolved: ProviderResolution[]): boolean;
+/**
+ * Providers left with nothing to try, despite a readable catalogue.
+ *
+ * Kept separate from "could not look" on purpose: a vendor whose catalogue
+ * answered and contained none of our models is a real lost link, while an
+ * unreadable one is an unknown. Collapsing them produces either a false alarm
+ * every time a key expires, or silence when a vendor actually goes away.
+ */
+export declare function emptyProviders(resolved: ProviderResolution[]): string[];
+/** Human-readable report. Could-not-look stays visibly distinct from a pass. */
+export declare function resolutionReport(resolved: ProviderResolution[]): string;

package/dist/resolve.js

@@ -0,0 +1,218 @@
+/**
+ * resolve — stop writing model ids down.
+ *
+ * ── The problem the chain did not solve ──────────────────────────────────────
+ * `chain.ts` replaced one pinned model with a list of pinned models, and says so
+ * itself: "a single pinned free model is not a configuration, it is a scheduled
+ * outage." `catalog.ts` then noticed the list rots too, and added a check. But a
+ * check only produces a SENTENCE. Somebody still has to read it, edit a file,
+ * open a pull request, wait for CI, and deploy — and until they do, the app is
+ * handing users a model that answers 404.
+ *
+ * That round trip is not hypothetical, it is this module's origin. On
+ * 2026-09-13 a freshly scheduled health check alerted within minutes of its
+ * first run: two ids in a consumer's registry were gone from OpenRouter. The
+ * alert was correct, fast, and completely dependent on a human being available
+ * to act on it. The vendor had published the truth the whole time.
+ *
+ * So: keep the declared list, but treat it as a PREFERENCE, and let the vendor's
+ * own catalogue decide what is actually callable. A retirement stops being an
+ * incident and becomes a no-op.
+ *
+ * ── Three rules, each paid for by a real failure ─────────────────────────────
+ *
+ * 1. NEVER SHRINK ON IGNORANCE. An unreadable catalogue leaves the declared
+ *    list exactly as written and sets `unverified`. While building this, a
+ *    checkout without GROQ_API_KEY got a 401, and the first draft of the probe
+ *    printed "GONE" for both Groq models — both of which were live. Resolution
+ *    that trusted that would let an expired key empty the chain.
+ *
+ * 2. DISCOVERY EXTENDS THE TAIL, NEVER THE HEAD. Declared ids were curated —
+ *    in this package's case probed with a real tool call, because five of nine
+ *    free models turned out to emit tool calls only as text. A discovered id
+ *    has no such evidence behind it, so it may be a last resort and never a
+ *    first choice.
+ *
+ * 3. DISCOVER ONLY WHAT THE VENDOR CALLS FREE, AND ONLY WHAT IT CALLS USABLE.
+ *    Both halves matter, and both are read from the vendor rather than guessed:
+ *
+ *      - Price. Not the `:free` suffix — the published number. Checked live on
+ *        2026-09-13, OpenRouter listed 19 ids ending `:free` and 22 priced at
+ *        zero. Groq publishes prices too, and NONE of its models are zero, so
+ *        discovery there correctly finds nothing and that vendor stays curated.
+ *        A suffix heuristic would have gone looking for `:free` at a vendor
+ *        that does not use the convention; a price check just declines.
+ *
+ *      - Suitability. Of the 19 free OpenRouter ids, one was
+ *        `nemotron-3.5-content-safety` — a classifier, and the only one of the
+ *        19 declaring `tools: false`. Two more zero-priced ids were
+ *        `lyria-3-*`, which emit AUDIO. Adding all zero-priced models to a chat
+ *        chain would have put a safety classifier and a music generator in
+ *        front of a user asking a question. Requiring text output and declared
+ *        tool support removes exactly those three and nothing else.
+ *
+ * ── What this is worth ───────────────────────────────────────────────────────
+ * Measured against the live catalogue on 2026-09-13: `freeChain()` names five
+ * OpenRouter ids by hand; nineteen zero-priced, text-out, tool-capable ids were
+ * available. Same key, same account, no human — a free pool nearly four times
+ * larger, which grows when the vendor adds models and shrinks when it removes
+ * them, without anyone being told.
+ *
+ * ── What this is NOT ─────────────────────────────────────────────────────────
+ * Presence in a catalogue is not proof a model works. This package already
+ * records two counter-examples: an id that answered "Provider returned error"
+ * on probe, and one that returned HTTP 200 with EMPTY content. Resolution fixes
+ * "the id does not exist"; it cannot fix "the id exists and misbehaves." That
+ * is what the chain's own fallback, and observed health, are for. Declared
+ * capability is a starting hypothesis — traffic is the evidence.
+ */
+import { providerModels } from "./chain.js";
+import { fetchCatalog } from "./catalog-fetch.js";
+const DEFAULTS = {
+    free: true,
+    textOnly: true,
+    tools: true,
+};
+/**
+ * Does this record satisfy the requirement, reading "the vendor did not say" as
+ * a failure?
+ *
+ * Silence is refused rather than assumed. A model that does not declare a price
+ * might be free; if it is not, discovery has quietly started spending money,
+ * which is the one failure here with a bill attached. The cost of being wrong is
+ * asymmetric, so the default leans to declining.
+ */
+function meets(m, req) {
+    const want = { ...DEFAULTS, ...req };
+    if (want.free && m.costsNothing !== true)
+        return false;
+    if (want.textOnly && !(m.outputModalities?.length === 1 && m.outputModalities[0] === "text"))
+        return false;
+    if (want.tools && m.tools !== true)
+        return false;
+    if (req.minContext !== undefined && (m.contextLength ?? 0) < req.minContext)
+        return false;
+    return true;
+}
+/** Has the vendor's own stated end-date already passed? */
+function expired(m, now) {
+    if (!m.expiresOn)
+        return false;
+    const t = Date.parse(`${m.expiresOn}T23:59:59Z`);
+    return Number.isFinite(t) && t < now;
+}
+/**
+ * Resolve one chain against what its vendors currently offer.
+ *
+ * Costs one GET /models per provider and ZERO tokens — the same property that
+ * made the catalogue check schedulable makes this callable on a warm path, and
+ * consumers are expected to cache the result rather than resolve per request.
+ */
+export async function resolveChain(chain, opts = {}) {
+    const env = opts.env ?? process.env;
+    const discover = opts.discover ?? true;
+    const req = opts.require ?? {};
+    const maxDiscovered = opts.maxDiscovered ?? 10;
+    const now = (opts.now ?? Date.now)();
+    const out = [];
+    for (const provider of chain) {
+        const declared = providerModels(provider, env);
+        const records = await fetchCatalog(provider.baseUrl, env[provider.keyEnv], {
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.timeoutMs,
+        });
+        // Rule 1. Could not look ⇒ change nothing, and say so.
+        if (!records) {
+            out.push({
+                provider: provider.id,
+                models: declared,
+                kept: [],
+                dropped: [],
+                discovered: [],
+                unverified: true,
+                expiring: [],
+            });
+            continue;
+        }
+        const byId = new Map(records.map((r) => [r.id, r]));
+        const kept = declared.filter((m) => {
+            const rec = byId.get(m);
+            return rec !== undefined && !expired(rec, now);
+        });
+        const dropped = declared.filter((m) => !kept.includes(m));
+        // Rule 2. Discovered ids go after the curated ones, never before.
+        const discovered = discover
+            ? records
+                .filter((r) => !declared.includes(r.id) && !expired(r, now) && meets(r, req))
+                .map((r) => r.id)
+                .sort()
+                .slice(0, maxDiscovered)
+            : [];
+        const models = [...kept, ...discovered];
+        const expiring = models
+            .map((m) => ({ model: m, on: byId.get(m)?.expiresOn ?? null }))
+            .filter((e) => e.on !== null);
+        out.push({
+            provider: provider.id,
+            models,
+            kept,
+            dropped,
+            discovered,
+            unverified: false,
+            expiring,
+        });
+    }
+    return out;
+}
+/**
+ * Fold a resolution back into providers, ready for `usableChain`.
+ *
+ * A provider whose every model resolved away is left with an EMPTY model list
+ * rather than being dropped from the chain. `usableChain` already skips links
+ * with nothing to try, and keeping the row means the vendor still appears in
+ * reports — a silently vanished provider is how a chain quietly becomes a
+ * single point of failure without anyone noticing.
+ */
+export function applyResolution(chain, resolved) {
+    const byId = new Map(resolved.map((r) => [r.provider, r]));
+    return chain.map((p) => {
+        const r = byId.get(p.id);
+        return r ? { ...p, models: r.models } : p;
+    });
+}
+/** True when any declared id was confirmed gone and routed around. */
+export function routedAroundRot(resolved) {
+    return resolved.some((r) => r.dropped.length > 0);
+}
+/**
+ * Providers left with nothing to try, despite a readable catalogue.
+ *
+ * Kept separate from "could not look" on purpose: a vendor whose catalogue
+ * answered and contained none of our models is a real lost link, while an
+ * unreadable one is an unknown. Collapsing them produces either a false alarm
+ * every time a key expires, or silence when a vendor actually goes away.
+ */
+export function emptyProviders(resolved) {
+    return resolved.filter((r) => !r.unverified && r.models.length === 0).map((r) => r.provider);
+}
+/** Human-readable report. Could-not-look stays visibly distinct from a pass. */
+export function resolutionReport(resolved) {
+    const lines = [];
+    for (const r of resolved) {
+        if (r.unverified) {
+            lines.push(`? ${r.provider}: catalogue unreadable — using the declared ${r.models.length} id(s) UNVERIFIED`);
+            continue;
+        }
+        lines.push(`  ${r.provider}: ${r.models.length} model(s) — ${r.kept.length} declared, ${r.discovered.length} discovered`);
+        for (const m of r.dropped)
+            lines.push(`    GONE, routed around: ${m}`);
+        for (const m of r.discovered)
+            lines.push(`    + ${m}`);
+        for (const e of r.expiring)
+            lines.push(`    ! ${e.model} — vendor says it ends ${e.on}`);
+    }
+    const empty = emptyProviders(resolved);
+    if (empty.length)
+        lines.push(`\nNothing left to try at: ${empty.join(", ")} — that vendor is gone from the chain.`);
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",

package/src/catalog-fetch.ts

@@ -0,0 +1,146 @@
+/**
+ * One GET /models, parsed once, for everything that needs to know what a vendor
+ * currently offers.
+ *
+ * `catalog.ts` already fetched this list to answer "has a pinned id rotted".
+ * `resolve.ts` needs the SAME request to answer "what else is on the shelf, and
+ * what does the vendor say about it" — and the ids alone cannot answer that.
+ *
+ * Rather than issue a second, slightly different GET (the exact failure
+ * catalog.ts's own header complains about — "the app that wrote its own first
+ * wrote it slightly differently"), both read this.
+ *
+ * ── Two vendors, two schemas, one shape ──────────────────────────────────────
+ * Verified against live responses on 2026-09-13, and they do NOT agree:
+ *
+ *   OpenRouter  architecture.output_modalities   supported_parameters: ["tools"]
+ *   Groq        output_modalities (top level)    supported_features:   ["json_mode"]
+ *
+ * So a reader that knows only OpenRouter's shape reports every Groq model as
+ * having no text output and no tools — which, in a filter, silently removes a
+ * working vendor. Normalising here means each consumer states its requirement
+ * once instead of learning both schemas.
+ *
+ * ── Unknown is a value, not a default ────────────────────────────────────────
+ * Every normalised field is nullable, and null means "the vendor did not say".
+ * That is deliberately distinct from false. A filter that treats "did not say"
+ * as "does not support" narrows silently as vendors change their schemas; one
+ * that treats it as "supports" invents capability. Callers must choose, and the
+ * choice is visible at the call site because the type forces it.
+ */
+
+/** What a vendor's catalogue says about one model, in one shape. */
+export type ModelRecord = {
+  id: string;
+  /** Output modalities, or null when the vendor does not publish them. */
+  outputModalities: string[] | null;
+  /**
+   * True only when the vendor publishes a price and every component is zero.
+   * Null when it publishes no price at all.
+   *
+   * Not the same question as "does the `:free` suffix appear". Checked live on
+   * 2026-09-13: OpenRouter lists 19 ids ending `:free` and 22 priced at zero —
+   * and the three zero-priced ids WITHOUT the suffix include `openrouter/free`,
+   * the auto-router that is the most rot-resistant entry in the whole chain.
+   * A suffix check misses it. Price is the vendor telling you who pays.
+   */
+  costsNothing: boolean | null;
+  /** True when the vendor declares tool/function calling. Null when unstated. */
+  tools: boolean | null;
+  /** Vendor-declared context window, when published. */
+  contextLength: number | null;
+  /**
+   * Date the vendor says this id stops working (ISO yyyy-mm-dd), when it says so.
+   *
+   * Rare but real: of 445 OpenRouter models on 2026-09-13, five carried one, and
+   * one of those was a FREE model expiring in 17 days. Where present this turns
+   * rot from something detected afterwards into something known in advance, so
+   * it is worth surfacing even though most models omit it.
+   */
+  expiresOn: string | null;
+};
+
+type RawModel = Record<string, unknown>;
+
+function asStringArray(v: unknown): string[] | null {
+  if (!Array.isArray(v)) return null;
+  const out = v.filter((x): x is string => typeof x === "string");
+  return out.length > 0 ? out : null;
+}
+
+/** Zero only when a price is published AND every numeric component is zero. */
+function priceIsZero(pricing: unknown): boolean | null {
+  if (!pricing || typeof pricing !== "object") return null;
+  const entries = Object.entries(pricing as Record<string, unknown>);
+  const numbers = entries
+    .map(([, v]) => (typeof v === "string" || typeof v === "number" ? Number(v) : NaN))
+    .filter((n) => Number.isFinite(n));
+  if (numbers.length === 0) return null;
+  return numbers.every((n) => n === 0);
+}
+
+/** Tool support as DECLARED by the vendor, across both known schemas. */
+function declaresTools(m: RawModel): boolean | null {
+  const params = asStringArray(m.supported_parameters);
+  if (params) return params.includes("tools");
+  const features = asStringArray(m.supported_features);
+  if (features) return features.some((f) => f === "tools" || f === "tool_use");
+  return null;
+}
+
+function normalise(m: RawModel): ModelRecord | null {
+  const id = typeof m.id === "string" ? m.id : "";
+  if (!id) return null;
+  const arch = (m.architecture ?? {}) as RawModel;
+  const expires = m.expiration_date;
+  return {
+    id,
+    outputModalities: asStringArray(arch.output_modalities) ?? asStringArray(m.output_modalities),
+    costsNothing: priceIsZero(m.pricing),
+    tools: declaresTools(m),
+    contextLength: typeof m.context_length === "number" ? m.context_length : null,
+    expiresOn: typeof expires === "string" && expires.trim() ? expires.trim() : null,
+  };
+}
+
+export type FetchCatalogOptions = {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+};
+
+/**
+ * Every model one vendor lists, normalised — or NULL when the catalogue could
+ * not be read.
+ *
+ * Null covers no key, a network failure, a non-200, an unparseable body, and a
+ * body that parses but lists nothing. It never means "this vendor has no
+ * models", and the distinction is not academic: while building this, a local
+ * checkout missing GROQ_API_KEY answered 401, and a reader that collapsed that
+ * into an empty list reported BOTH live Groq models as retired. Had resolution
+ * trusted it, an expired key would have emptied the chain rather than failing a
+ * single call.
+ */
+export async function fetchCatalog(
+  baseUrl: string,
+  key: string | undefined,
+  opts: FetchCatalogOptions = {},
+): Promise<ModelRecord[] | null> {
+  if (!key?.trim()) return null;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 20_000;
+  try {
+    const res = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/models`, {
+      headers: { Authorization: `Bearer ${key.trim()}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { data?: unknown };
+    if (!Array.isArray(body?.data)) return null;
+    const records = body.data
+      .map((m) => normalise((m ?? {}) as RawModel))
+      .filter((m): m is ModelRecord => m !== null);
+    return records.length > 0 ? records : null;
+  } catch {
+    return null;
+  }
+}

package/src/catalog.ts

@@ -23,6 +23,7 @@
  */
 
 import { providerModels, type Env, type Provider } from "./chain.js";
+import { fetchCatalog } from "./catalog-fetch.js";
 
 export type CatalogVerdict = {
   provider: string;
@@ -50,31 +51,27 @@ export type CheckCatalogOptions = {
   timeoutMs?: number;
 };
 
-/** Ids listed by one provider, or null when the catalogue could not be read. */
+/**
+ * Ids listed by one provider, or null when the catalogue could not be read.
+ *
+ * The request itself now lives in catalog-fetch.ts, because `resolve.ts` needs
+ * the SAME GET and the ids alone cannot tell it what a model costs or can do.
+ * Two near-identical fetches drifting apart is the failure this module's own
+ * header objects to; one fetch, two readers.
+ *
+ * Every null case is preserved exactly — no key, network failure, non-200,
+ * unparseable body, and a body that parses but lists nothing (a malformed
+ * answer, not a vendor with no models: refusing it keeps a bad response from
+ * reading as total rot).
+ */
 async function liveIds(
   provider: Provider,
   key: string,
   fetchImpl: typeof fetch,
   timeoutMs: number,
 ): Promise<string[] | null> {
-  try {
-    const res = await fetchImpl(`${provider.baseUrl.replace(/\/$/, "")}/models`, {
-      headers: { Authorization: `Bearer ${key}` },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!res.ok) return null;
-    const body = (await res.json()) as { data?: Array<{ id?: unknown }> };
-    if (!Array.isArray(body?.data)) return null;
-    const ids = body.data
-      .map((m) => (typeof m?.id === "string" ? m.id : ""))
-      .filter((id): id is string => id.length > 0);
-    // A catalogue that parses but lists nothing is a malformed answer, not a
-    // vendor with no models. Refusing it keeps a bad response from reading as
-    // total rot.
-    return ids.length > 0 ? ids : null;
-  } catch {
-    return null;
-  }
+  const records = await fetchCatalog(provider.baseUrl, key, { fetchImpl, timeoutMs });
+  return records ? records.map((r) => r.id) : null;
 }
 
 /**

package/src/index.ts

@@ -75,6 +75,22 @@ export {
   catalogReport,
 } from "./catalog.js";
 
+export { type ModelRecord, type FetchCatalogOptions, fetchCatalog } from "./catalog-fetch.js";
+
+// Resolution is the answer to the question `catalog` only asks. checkCatalog
+// REPORTS that a pinned id is gone; resolveChain drops it and calls the next
+// one, so a vendor retirement stops needing a pull request to survive.
+export {
+  type Requirements,
+  type ResolveOptions,
+  type ProviderResolution,
+  resolveChain,
+  applyResolution,
+  routedAroundRot,
+  emptyProviders,
+  resolutionReport,
+} from "./resolve.js";
+
 export {
   type ChainAttemptFailure,
   type TryChainOptions,
@@ -125,6 +141,7 @@ export {
   type HeaderBag,
   readQuota,
   readingFromRefusal,
+  readingFromRefusalBody,
   parseResetAt,
   answersRemaining,
 } from "./meter.js";

package/src/meter.ts

@@ -248,6 +248,72 @@ export function readingFromRefusal(
   };
 }
 
+/**
+ * The counter a vendor discloses ONLY when it refuses.
+ *
+ * ── WHY A BODY PARSER EARNS ITS KEEP ─────────────────────────────────────────
+ *
+ * Headers do not describe every limit a vendor enforces. Groq publishes its
+ * per-minute token window and its per-day REQUEST count as headers, and meters
+ * a third limit — tokens per DAY — that appears in no header at all. It is
+ * stated once, in prose, in the body of the 429 that enforces it:
+ *
+ *   Rate limit reached for model `openai/gpt-oss-20b` in organization `org_…`
+ *   service tier `on_demand` on tokens per day (TPD): Limit 200000,
+ *   Used 199773, Requested 571. Please try again in 2m28.608s.
+ *
+ * Observed on production 2026-09-13. Every header the same response carried
+ * looked healthy — 2,672 of 8,000 tokens left this minute, 999 of 1,000
+ * requests left today — while the account was locked out of the model for the
+ * rest of the day. A dashboard fed only by headers therefore reported a
+ * working provider throughout an outage, which is precisely the failure the
+ * top of this file exists to prevent, arriving through a door it left open.
+ *
+ * ── STILL NEVER INVENTS ──────────────────────────────────────────────────────
+ *
+ * Returns null unless the body states the numbers. An unparsed refusal is the
+ * "did not say" state, and the caller should fall back to `readingFromRefusal`,
+ * which records the one fact a 429 always carries: spent, now.
+ */
+const REFUSAL_COUNTER =
+  /on\s+(tokens|requests)\s+per\s+(minute|day)\s*\([^)]*\)\s*:\s*Limit\s+(\d+)\s*,\s*Used\s+(\d+)/i;
+
+export function readingFromRefusalBody(
+  link: Link,
+  body: string,
+  retryAfterSec: number | null = null,
+  now = Date.now(),
+): QuotaReading | null {
+  const m = REFUSAL_COUNTER.exec(body);
+  if (!m) return null;
+
+  const [, rawScope, rawWindow, rawLimit, rawUsed] = m;
+  if (!rawScope || !rawWindow || !rawLimit || !rawUsed) return null;
+
+  const scope = rawScope.toLowerCase() as QuotaScope;
+  const window = rawWindow.toLowerCase() as QuotaWindow;
+  const limit = Number(rawLimit);
+  const used = Number(rawUsed);
+  if (!Number.isFinite(limit) || !Number.isFinite(used)) return null;
+
+  return {
+    provider: link.provider.id,
+    model: link.model,
+    scope,
+    // Straight from the vendor's own sentence, so unlike a header name this
+    // window is not a guess and must not be overridden by the provider profile.
+    window,
+    limit,
+    // The refusal names what was consumed, not what is left. Clamped because a
+    // vendor counting a rejected request against the total would otherwise
+    // produce a negative "remaining" and a dashboard that renders nonsense.
+    remaining: Math.max(0, limit - used),
+    resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+    source: "429-body",
+    observedAt: now,
+  };
+}
+
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *

package/src/resolve.ts

@@ -0,0 +1,294 @@
+/**
+ * resolve — stop writing model ids down.
+ *
+ * ── The problem the chain did not solve ──────────────────────────────────────
+ * `chain.ts` replaced one pinned model with a list of pinned models, and says so
+ * itself: "a single pinned free model is not a configuration, it is a scheduled
+ * outage." `catalog.ts` then noticed the list rots too, and added a check. But a
+ * check only produces a SENTENCE. Somebody still has to read it, edit a file,
+ * open a pull request, wait for CI, and deploy — and until they do, the app is
+ * handing users a model that answers 404.
+ *
+ * That round trip is not hypothetical, it is this module's origin. On
+ * 2026-09-13 a freshly scheduled health check alerted within minutes of its
+ * first run: two ids in a consumer's registry were gone from OpenRouter. The
+ * alert was correct, fast, and completely dependent on a human being available
+ * to act on it. The vendor had published the truth the whole time.
+ *
+ * So: keep the declared list, but treat it as a PREFERENCE, and let the vendor's
+ * own catalogue decide what is actually callable. A retirement stops being an
+ * incident and becomes a no-op.
+ *
+ * ── Three rules, each paid for by a real failure ─────────────────────────────
+ *
+ * 1. NEVER SHRINK ON IGNORANCE. An unreadable catalogue leaves the declared
+ *    list exactly as written and sets `unverified`. While building this, a
+ *    checkout without GROQ_API_KEY got a 401, and the first draft of the probe
+ *    printed "GONE" for both Groq models — both of which were live. Resolution
+ *    that trusted that would let an expired key empty the chain.
+ *
+ * 2. DISCOVERY EXTENDS THE TAIL, NEVER THE HEAD. Declared ids were curated —
+ *    in this package's case probed with a real tool call, because five of nine
+ *    free models turned out to emit tool calls only as text. A discovered id
+ *    has no such evidence behind it, so it may be a last resort and never a
+ *    first choice.
+ *
+ * 3. DISCOVER ONLY WHAT THE VENDOR CALLS FREE, AND ONLY WHAT IT CALLS USABLE.
+ *    Both halves matter, and both are read from the vendor rather than guessed:
+ *
+ *      - Price. Not the `:free` suffix — the published number. Checked live on
+ *        2026-09-13, OpenRouter listed 19 ids ending `:free` and 22 priced at
+ *        zero. Groq publishes prices too, and NONE of its models are zero, so
+ *        discovery there correctly finds nothing and that vendor stays curated.
+ *        A suffix heuristic would have gone looking for `:free` at a vendor
+ *        that does not use the convention; a price check just declines.
+ *
+ *      - Suitability. Of the 19 free OpenRouter ids, one was
+ *        `nemotron-3.5-content-safety` — a classifier, and the only one of the
+ *        19 declaring `tools: false`. Two more zero-priced ids were
+ *        `lyria-3-*`, which emit AUDIO. Adding all zero-priced models to a chat
+ *        chain would have put a safety classifier and a music generator in
+ *        front of a user asking a question. Requiring text output and declared
+ *        tool support removes exactly those three and nothing else.
+ *
+ * ── What this is worth ───────────────────────────────────────────────────────
+ * Measured against the live catalogue on 2026-09-13: `freeChain()` names five
+ * OpenRouter ids by hand; nineteen zero-priced, text-out, tool-capable ids were
+ * available. Same key, same account, no human — a free pool nearly four times
+ * larger, which grows when the vendor adds models and shrinks when it removes
+ * them, without anyone being told.
+ *
+ * ── What this is NOT ─────────────────────────────────────────────────────────
+ * Presence in a catalogue is not proof a model works. This package already
+ * records two counter-examples: an id that answered "Provider returned error"
+ * on probe, and one that returned HTTP 200 with EMPTY content. Resolution fixes
+ * "the id does not exist"; it cannot fix "the id exists and misbehaves." That
+ * is what the chain's own fallback, and observed health, are for. Declared
+ * capability is a starting hypothesis — traffic is the evidence.
+ */
+
+import { providerModels, type Env, type Provider } from "./chain.js";
+import { fetchCatalog, type ModelRecord } from "./catalog-fetch.js";
+
+/** What a discovered model must prove about itself before it joins the tail. */
+export type Requirements = {
+  /** Vendor must publish a price and it must be zero. Default true. */
+  free?: boolean;
+  /** Vendor must declare text as its only output modality. Default true. */
+  textOnly?: boolean;
+  /** Vendor must declare tool/function calling. Default true. */
+  tools?: boolean;
+  /** Minimum published context window, when the vendor publishes one. */
+  minContext?: number;
+};
+
+export type ResolveOptions = {
+  env?: Env;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  /**
+   * Append live models the declaration never named. Default true — that is the
+   * half that makes the pool GROW without a human. Set false to verify the
+   * declared list against the catalogue and nothing more.
+   */
+  discover?: boolean;
+  /** What a discovered model must declare. See Requirements. */
+  require?: Requirements;
+  /**
+   * Cap on discovered ids appended per provider. Default 10.
+   *
+   * A cap, not a preference: the chain is walked in order on failure, so an
+   * unbounded tail turns one bad minute at a vendor into dozens of sequential
+   * requests before the caller sees an error.
+   */
+  maxDiscovered?: number;
+  /** Clock injection for tests. Default `Date.now`. */
+  now?: () => number;
+};
+
+export type ProviderResolution = {
+  provider: string;
+  /** The ids to actually try, in order: kept declarations, then discovered. */
+  models: string[];
+  /** Declared ids the vendor still lists. */
+  kept: string[];
+  /**
+   * Declared ids the vendor no longer lists. Dropped from `models` — this is
+   * the rot, already routed around rather than merely reported.
+   */
+  dropped: string[];
+  /** Live ids the declaration never named, appended after the kept ones. */
+  discovered: string[];
+  /**
+   * True when the catalogue could not be read, so `models` is the declaration
+   * verbatim and NOTHING here was verified. `dropped` is empty because no id
+   * was confirmed gone — not because none is.
+   */
+  unverified: boolean;
+  /** Ids in `models` the vendor says will stop working, with the date. */
+  expiring: Array<{ model: string; on: string }>;
+};
+
+const DEFAULTS: Required<Omit<Requirements, "minContext">> = {
+  free: true,
+  textOnly: true,
+  tools: true,
+};
+
+/**
+ * Does this record satisfy the requirement, reading "the vendor did not say" as
+ * a failure?
+ *
+ * Silence is refused rather than assumed. A model that does not declare a price
+ * might be free; if it is not, discovery has quietly started spending money,
+ * which is the one failure here with a bill attached. The cost of being wrong is
+ * asymmetric, so the default leans to declining.
+ */
+function meets(m: ModelRecord, req: Requirements): boolean {
+  const want = { ...DEFAULTS, ...req };
+  if (want.free && m.costsNothing !== true) return false;
+  if (want.textOnly && !(m.outputModalities?.length === 1 && m.outputModalities[0] === "text"))
+    return false;
+  if (want.tools && m.tools !== true) return false;
+  if (req.minContext !== undefined && (m.contextLength ?? 0) < req.minContext) return false;
+  return true;
+}
+
+/** Has the vendor's own stated end-date already passed? */
+function expired(m: ModelRecord, now: number): boolean {
+  if (!m.expiresOn) return false;
+  const t = Date.parse(`${m.expiresOn}T23:59:59Z`);
+  return Number.isFinite(t) && t < now;
+}
+
+/**
+ * Resolve one chain against what its vendors currently offer.
+ *
+ * Costs one GET /models per provider and ZERO tokens — the same property that
+ * made the catalogue check schedulable makes this callable on a warm path, and
+ * consumers are expected to cache the result rather than resolve per request.
+ */
+export async function resolveChain(
+  chain: Provider[],
+  opts: ResolveOptions = {},
+): Promise<ProviderResolution[]> {
+  const env = opts.env ?? process.env;
+  const discover = opts.discover ?? true;
+  const req = opts.require ?? {};
+  const maxDiscovered = opts.maxDiscovered ?? 10;
+  const now = (opts.now ?? Date.now)();
+
+  const out: ProviderResolution[] = [];
+  for (const provider of chain) {
+    const declared = providerModels(provider, env);
+    const records = await fetchCatalog(provider.baseUrl, env[provider.keyEnv], {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs,
+    });
+
+    // Rule 1. Could not look ⇒ change nothing, and say so.
+    if (!records) {
+      out.push({
+        provider: provider.id,
+        models: declared,
+        kept: [],
+        dropped: [],
+        discovered: [],
+        unverified: true,
+        expiring: [],
+      });
+      continue;
+    }
+
+    const byId = new Map(records.map((r) => [r.id, r]));
+    const kept = declared.filter((m) => {
+      const rec = byId.get(m);
+      return rec !== undefined && !expired(rec, now);
+    });
+    const dropped = declared.filter((m) => !kept.includes(m));
+
+    // Rule 2. Discovered ids go after the curated ones, never before.
+    const discovered = discover
+      ? records
+          .filter((r) => !declared.includes(r.id) && !expired(r, now) && meets(r, req))
+          .map((r) => r.id)
+          .sort()
+          .slice(0, maxDiscovered)
+      : [];
+
+    const models = [...kept, ...discovered];
+    const expiring = models
+      .map((m) => ({ model: m, on: byId.get(m)?.expiresOn ?? null }))
+      .filter((e): e is { model: string; on: string } => e.on !== null);
+
+    out.push({
+      provider: provider.id,
+      models,
+      kept,
+      dropped,
+      discovered,
+      unverified: false,
+      expiring,
+    });
+  }
+  return out;
+}
+
+/**
+ * Fold a resolution back into providers, ready for `usableChain`.
+ *
+ * A provider whose every model resolved away is left with an EMPTY model list
+ * rather than being dropped from the chain. `usableChain` already skips links
+ * with nothing to try, and keeping the row means the vendor still appears in
+ * reports — a silently vanished provider is how a chain quietly becomes a
+ * single point of failure without anyone noticing.
+ */
+export function applyResolution(chain: Provider[], resolved: ProviderResolution[]): Provider[] {
+  const byId = new Map(resolved.map((r) => [r.provider, r]));
+  return chain.map((p) => {
+    const r = byId.get(p.id);
+    return r ? { ...p, models: r.models } : p;
+  });
+}
+
+/** True when any declared id was confirmed gone and routed around. */
+export function routedAroundRot(resolved: ProviderResolution[]): boolean {
+  return resolved.some((r) => r.dropped.length > 0);
+}
+
+/**
+ * Providers left with nothing to try, despite a readable catalogue.
+ *
+ * Kept separate from "could not look" on purpose: a vendor whose catalogue
+ * answered and contained none of our models is a real lost link, while an
+ * unreadable one is an unknown. Collapsing them produces either a false alarm
+ * every time a key expires, or silence when a vendor actually goes away.
+ */
+export function emptyProviders(resolved: ProviderResolution[]): string[] {
+  return resolved.filter((r) => !r.unverified && r.models.length === 0).map((r) => r.provider);
+}
+
+/** Human-readable report. Could-not-look stays visibly distinct from a pass. */
+export function resolutionReport(resolved: ProviderResolution[]): string {
+  const lines: string[] = [];
+  for (const r of resolved) {
+    if (r.unverified) {
+      lines.push(
+        `? ${r.provider}: catalogue unreadable — using the declared ${r.models.length} id(s) UNVERIFIED`,
+      );
+      continue;
+    }
+    lines.push(
+      `  ${r.provider}: ${r.models.length} model(s) — ${r.kept.length} declared, ${r.discovered.length} discovered`,
+    );
+    for (const m of r.dropped) lines.push(`    GONE, routed around: ${m}`);
+    for (const m of r.discovered) lines.push(`    + ${m}`);
+    for (const e of r.expiring) lines.push(`    ! ${e.model} — vendor says it ends ${e.on}`);
+  }
+  const empty = emptyProviders(resolved);
+  if (empty.length)
+    lines.push(
+      `\nNothing left to try at: ${empty.join(", ")} — that vendor is gone from the chain.`,
+    );
+  return lines.join("\n");
+}