@bitbaum/ai-kit 0.6.2

package/dist-cjs/grounding/verify.js

@@ -0,0 +1,376 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAnswer = verifyAnswer;
+exports.buildRepairPrompt = buildRepairPrompt;
+/**
+ * Groundedness verifier — MIRRORED MODULE (see core/README.md).
+ *
+ * Runs on the generated answer and reports claims the fact set does not support.
+ * Deliberately deterministic: no second model call, no embedding round-trip, no
+ * added cost or latency. That is a requirement, not a shortcut — this must run
+ * on every turn including the free-tier ones, and a verifier that costs a
+ * frontier call is one that gets disabled exactly where it is needed most.
+ *
+ * The insight that makes a cheap check work: fabrication is overwhelmingly
+ * NOMINAL. Models invent organisations, titles, people, file paths, phone
+ * numbers and dates — tokens that are mechanically recognisable and that must,
+ * if genuine, have appeared in the retrieved records or in what the user said.
+ * Grammar and hedging are hard to check; proper nouns and digits are easy.
+ *
+ * Scored against the real failure this was built from, every fabricated claim
+ * is caught by the proper-noun or numeric rule:
+ *
+ *   "Ilya Druzhnikov (UZH)"                    → UZH: novel acronym
+ *   "Accelerator & Bridge Program Manager"     → novel proper-noun run
+ *   "University of Liechtenstein", "START Summit" → novel proper-noun runs
+ *   "/opt/fleetcrown/runner/.env"              → novel path
+ *
+ * while the true parts ("Elena Weber SINGA Switzerland", "+41774730093") appear
+ * verbatim in the records and pass clean.
+ */
+const facts_js_1 = require("./facts.js");
+/**
+ * Words that are capitalised for reasons other than being a proper noun, or
+ * that are part of this system's own vocabulary. Kept deliberately small —
+ * every entry is a hole in the check, so add only what demonstrably causes
+ * false positives, never to silence a true one.
+ */
+const COMMON = new Set([
+    // Sentence/structural
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "but",
+    "if",
+    "then",
+    "so",
+    "because",
+    "not",
+    "this",
+    "that",
+    "these",
+    "those",
+    "it",
+    "its",
+    "your",
+    "you",
+    "i",
+    "we",
+    "there",
+    "here",
+    "what",
+    "which",
+    "who",
+    "when",
+    "where",
+    "why",
+    "how",
+    "no",
+    "yes",
+    "none",
+    "nothing",
+    "today",
+    "tomorrow",
+    "yesterday",
+    "now",
+    "next",
+    "last",
+    "first",
+    "one",
+    "two",
+    "three",
+    "primary",
+    "focus",
+    "task",
+    "tasks",
+    "outreach",
+    "note",
+    "notes",
+    "summary",
+    "status",
+    "update",
+    // Days / months — real words, never evidence of a fabricated entity
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+    "january",
+    "february",
+    "march",
+    "april",
+    "may",
+    "june",
+    "july",
+    "august",
+    "september",
+    "october",
+    "november",
+    "december",
+    // This system's own nouns
+    "loki",
+    "cat",
+    "fleetcrown",
+    "orangecat",
+    "not",
+    "recorded",
+].map((w) => w.toLowerCase()));
+/** Normalise for containment tests: casefold, collapse punctuation and space. */
+function norm(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9+]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Everything the model was legitimately given this turn: record values, record
+ * subjects, and the user's own message (a name the user typed is fair to
+ * repeat). This is the corpus a claim must be traceable to.
+ */
+function buildEvidence(facts, userMessage, extra) {
+    const parts = [userMessage, ...extra];
+    for (const f of facts) {
+        parts.push(f.subject, f.kind, f.source);
+        for (const v of Object.values(f.fields))
+            if (v)
+                parts.push(v);
+    }
+    return norm(parts.join(" "));
+}
+/**
+ * Lowercase words that legitimately sit INSIDE a proper name and must not break
+ * it up: "University of Zurich", "Bank für Handel", "Institute for the Study of
+ * Complexity". Without these, the run splits at the connector and the check
+ * only ever sees the harmless halves ("University", "Zurich") while the actual
+ * fabricated entity slips through unnamed.
+ */
+const NAME_CONNECTORS = new Set([
+    "of",
+    "the",
+    "for",
+    "and",
+    "de",
+    "der",
+    "des",
+    "van",
+    "von",
+    "du",
+    "da",
+    "di",
+    "für",
+    "el",
+    "al",
+]);
+/**
+ * Named-entity candidates: ALL-CAPS acronyms, capitalised words, and the
+ * multi-word runs they form (connectors allowed strictly between two
+ * capitalised tokens, never at an edge).
+ *
+ * Both the run AND its individual tokens are emitted, deliberately. The run
+ * catches composite inventions ("University of Zurich") that no single token
+ * reveals; the individual tokens catch an invented acronym sitting next to a
+ * real name ("Druzhnikov UZH"), where reporting only the run would name the
+ * real person in the violation and produce a repair prompt that deletes the
+ * true claim along with the false one.
+ *
+ * Sentence-initial single words are skipped — otherwise "Rotate the key" flags
+ * "Rotate". That costs a little recall at sentence starts and removes the
+ * dominant source of false positives; a fabricated name at a sentence start is
+ * still caught by its remaining tokens.
+ */
+function properNounRuns(text) {
+    const out = [];
+    // Strip fenced and inline code — quoted identifiers are usually the user's
+    // own or a literal under discussion, not a claim about the world.
+    const prose = text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+    for (const sentence of prose.split(/(?<=[.!?:\n])\s+/)) {
+        const tokens = sentence.match(/[A-Za-z][A-Za-z0-9&.'’-]*/g) ?? [];
+        let run = [];
+        const flush = () => {
+            // Trim trailing connectors so "University of" never stands as a run.
+            while (run.length > 0 && NAME_CONNECTORS.has((run[run.length - 1] ?? "").toLowerCase()))
+                run.pop();
+            if (run.length > 1)
+                out.push(run.join(" "));
+            run = [];
+        };
+        tokens.forEach((tok, i) => {
+            const bare = tok.replace(/[.'’-]+$/, "");
+            const isAcronym = /^[A-Z]{2,}$/.test(bare);
+            const isCapitalised = /^[A-Z][a-z]/.test(bare);
+            const isConnector = NAME_CONNECTORS.has(bare.toLowerCase());
+            if (isAcronym || (isCapitalised && i > 0)) {
+                run.push(bare);
+                out.push(bare); // individually checkable
+                return;
+            }
+            // A connector only continues a run that has already started.
+            if (isConnector && run.length > 0) {
+                run.push(bare);
+                return;
+            }
+            flush();
+        });
+        flush();
+    }
+    return out;
+}
+/** Digit groups worth checking: phone numbers, years, percentages, counts ≥ 2 digits. */
+function numericClaims(text) {
+    const prose = text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+    return (prose.match(/\+?\d[\d\s().-]{3,}\d|\b\d{2,}%?\b/g) ?? []).map((s) => s.trim());
+}
+/**
+ * File and path references — a favourite fabrication, and an unusually
+ * damaging one because naming a file implies the model READ it.
+ *
+ * Covers absolute paths (`/opt/fleetcrown/runner/.env`), relative paths
+ * (`data/contact-resolver.json`), and bare filenames with a data/config
+ * extension. The relative form matters: when challenged on the UZH claim, the
+ * model "corrected" itself by asserting what `data/contact-resolver.json`
+ * contained — a file it was never given. That reads as citing a source, which
+ * is precisely why an unverified correction is more corrosive than the
+ * original error: it spends the credibility the user was trying to restore.
+ */
+function pathClaims(text) {
+    const patterns = [
+        /(?:^|[\s("'`])(\/[A-Za-z0-9_.\-/]{4,})/g, // absolute
+        /(?:^|[\s("'`])([A-Za-z0-9_.-]+\/[A-Za-z0-9_.\-/]*[A-Za-z0-9_-]\.[a-z]{2,5})/g, // relative w/ extension
+        /(?:^|[\s("'`])([A-Za-z0-9_-]+\.(?:json|env|ya?ml|sql|toml|ini|conf|log))\b/g, // bare config filename
+    ];
+    const out = new Set();
+    for (const re of patterns) {
+        for (const m of text.matchAll(re))
+            if (m[1])
+                out.add(m[1]);
+    }
+    return [...out];
+}
+/** Does this sentence talk about one of the user's own records? */
+function mentionsSubject(sentence, subjects) {
+    const s = norm(sentence);
+    return subjects.some((sub) => {
+        const n = norm(sub);
+        return n.length > 2 && s.includes(n);
+    });
+}
+/**
+ * Verify an answer against the facts it was supposed to come from.
+ *
+ * `extraEvidence` lets a caller admit sources outside the fact set — computed
+ * directive output, a tool result the model legitimately saw this turn.
+ * Anything not in facts, the user's message, or extraEvidence is unsupported
+ * by construction.
+ *
+ * `subjects` (entity-attribution mode) names the user's own records, so the
+ * check can tell "your contact Elena works at X" from "Lightning is instant".
+ */
+function verifyAnswer(input) {
+    const { answer, facts, userMessage } = input;
+    const mode = input.mode ?? "closed-world";
+    const subjects = input.subjects ?? facts.map((f) => f.subject);
+    const evidence = buildEvidence(facts, userMessage, input.extraEvidence ?? []);
+    const legalIds = new Set([
+        ...facts.map((f) => f.id.toUpperCase()),
+        ...(input.extraCitationIds ?? []).map((id) => id.toUpperCase()),
+    ]);
+    const violations = [];
+    /**
+     * In entity-attribution mode, only sentences about the user's own records are
+     * subject to the name check. Built once so the per-token loop stays cheap.
+     */
+    const attributionScope = mode === "entity-attribution"
+        ? answer
+            .split(/(?<=[.!?:\n])\s+/)
+            .filter((s) => mentionsSubject(s, subjects))
+            .join(" ")
+        : answer;
+    // 1. Citations must resolve. A citation to a record that does not exist is
+    //    the strongest possible signal of fabrication — it invents its own proof.
+    for (const cite of answer.match(/\[[FD]\d+\]/g) ?? []) {
+        const id = cite.slice(1, -1).toUpperCase();
+        if (!legalIds.has(id)) {
+            violations.push({
+                kind: "unknown-citation",
+                text: cite,
+                detail: `${cite} is not a record in this turn's context. Cite only ids that were provided, or say there is no record.`,
+            });
+        }
+    }
+    // 2. Named entities must be traceable. This is the anti-"UZH" rule.
+    const seen = new Set();
+    for (const run of properNounRuns(attributionScope)) {
+        const n = norm(run);
+        if (!n || seen.has(n))
+            continue;
+        seen.add(n);
+        // Single common words are noise; multi-word runs always checked.
+        const words = n.split(" ");
+        if (words.length === 1 && (COMMON.has(words[0] ?? "") || (words[0] ?? "").length < 2))
+            continue;
+        if (words.every((w) => COMMON.has(w)))
+            continue;
+        if (evidence.includes(n))
+            continue;
+        // A multi-word run whose every word is individually attested is fine —
+        // it is a rephrasing, not a new entity.
+        if (words.length > 1 && words.every((w) => COMMON.has(w) || evidence.includes(w)))
+            continue;
+        violations.push({
+            kind: "novel-proper-noun",
+            text: run,
+            detail: `"${run}" does not appear in any record or in the operator's message. If it is an organisation, role, or place you associated with someone, the relevant field is ${facts_js_1.NOT_RECORDED} — remove the claim.`,
+        });
+    }
+    // 3. Numbers must be traceable — invented phone numbers and dates read as
+    //    authoritative precisely because they are specific.
+    for (const num of numericClaims(answer)) {
+        const n = norm(num);
+        if (!n || n.length < 2)
+            continue;
+        if (evidence.includes(n))
+            continue;
+        // Compare digits-only too: "+41 77 473 00 93" vs stored "+41774730093".
+        const digits = num.replace(/\D/g, "");
+        if (digits.length >= 4 && evidence.replace(/\D/g, "").includes(digits))
+            continue;
+        if (digits.length < 4)
+            continue; // small counts ("3 tasks") are rhetorical
+        violations.push({
+            kind: "novel-number",
+            text: num,
+            detail: `The number "${num}" is not in any record. Do not state contact details, dates, or metrics that were not provided.`,
+        });
+    }
+    // 4. Paths — "update the key in /opt/fleetcrown/runner/.env" was invented
+    //    wholesale, and its specificity is what made it convincing.
+    for (const p of pathClaims(answer)) {
+        if (evidence.includes(norm(p)))
+            continue;
+        violations.push({
+            kind: "novel-path",
+            text: p,
+            detail: `The path "${p}" is not in any record. Do not state file locations you were not given.`,
+        });
+    }
+    return { ok: violations.length === 0, violations };
+}
+/**
+ * Turn violations into a repair instruction. One cheap retry with this appended
+ * fixes most turns, because the model is not being asked to know more — only to
+ * delete claims it cannot support.
+ */
+function buildRepairPrompt(violations, noBasisPhrase) {
+    return [
+        "Your previous answer contained claims not supported by the records. Rewrite it.",
+        "",
+        ...violations.map((v) => `- ${v.detail}`),
+        "",
+        `Remove every unsupported claim. Where removing one empties a requested item, write "${noBasisPhrase}" for that item instead of substituting something else. Keep everything that was supported, unchanged.`,
+    ].join("\n");
+}

package/dist-cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist-cjs/registry.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * The model REGISTRY — one SSOT for every model id an app may call.
+ *
+ * This module exists because the fleet paid for its absence twice, in two
+ * different currencies:
+ *
+ *   OUTAGE — on 2026-08-18 Groq removed `llama-3.3-70b-versatile` and one app
+ *   kept asking for it for eight days. A rot checker already existed, but it
+ *   probed only the chains it knew about; the id that died was pinned
+ *   elsewhere. A checker that does not enumerate its subjects cannot report
+ *   the one it never knew about. The registry IS the enumeration: a model id
+ *   is callable only if it appears here, and the catalog check walks exactly
+ *   this list.
+ *
+ *   MONEY — three apps silently billed real money on fallback, because the
+ *   only thing separating the free variant from the paid one was a `:free`
+ *   suffix on the id string. A billing boundary that lives in a naming
+ *   convention is one typo away from a paid call. Here it is a FIELD, and the
+ *   validator refuses an entry whose flag contradicts its own cost or suffix —
+ *   so the contradiction is a build failure, not an invoice.
+ *
+ * What deliberately does NOT live here: which model to PREFER (that is the
+ * chain's job), UI presentation (labels, badges — app concern), and anything
+ * that knows where data lives. Same boundary as the rest of this package:
+ * meaning in core, adapters in the app.
+ *
+ * ── Vendor vs author ─────────────────────────────────────────────────────────
+ * A registry row is a CALLABLE id at a VENDOR — the place a request goes —
+ * because that is the unit that rots, meters, and bills. The AUTHOR (who
+ * trained it) is metadata. The two were conflated in one app's registry
+ * ("provider: Anthropic" on a row served by OpenRouter), which made "who do we
+ * pay" unanswerable by query. Here they are separate fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineRegistry = defineRegistry;
+exports.freeOnly = freeOnly;
+exports.toolCapable = toolCapable;
+/** A `:free`-suffixed id claiming to be paid, or a "free" entry with a price —
+ *  each one is the 2026 billing incident waiting to recur. */
+function validateEntry(e) {
+    if (!e.id.trim())
+        return "entry has an empty id";
+    if (!e.vendor.trim())
+        return `"${e.id}": empty vendor`;
+    const cost = (e.inputCostPer1M ?? 0) + (e.outputCostPer1M ?? 0);
+    if (!e.paid && cost > 0) {
+        return `"${e.id}": declared free but carries a cost (${cost}/1M) — the flag or the price is lying`;
+    }
+    if (e.paid && e.id.endsWith(":free")) {
+        return `"${e.id}": declared paid but the id says :free — the flag or the id is lying`;
+    }
+    return null;
+}
+/**
+ * Build a registry from entries. Throws on the first contradiction — a
+ * registry that loads is a registry whose billing boundary can be trusted.
+ */
+function defineRegistry(entries) {
+    const seen = new Set();
+    for (const e of entries) {
+        const problem = validateEntry(e);
+        if (problem)
+            throw new Error(`ai-kit registry: ${problem}`);
+        const key = `${e.vendor}:${e.id}`;
+        if (seen.has(key)) {
+            throw new Error(`ai-kit registry: duplicate entry ${key} — two rows for one callable id is two sources of truth`);
+        }
+        seen.add(key);
+    }
+    const frozen = Object.freeze(entries.map((e) => ({ ...e })));
+    const find = (id, vendor) => frozen.find((e) => e.id === id && (vendor === undefined || e.vendor === vendor));
+    return {
+        entries: frozen,
+        find,
+        require(id, vendor) {
+            const hit = find(id, vendor);
+            if (!hit) {
+                const scope = vendor ? ` at ${vendor}` : "";
+                throw new Error(`ai-kit registry: "${id}"${scope} is not registered — a model id is callable only if it appears in the registry (add it with its paid flag, or stop calling it)`);
+            }
+            return hit;
+        },
+        idsForVendor: (vendor) => frozen.filter((e) => e.vendor === vendor).map((e) => e.id),
+        vendors: () => [...new Set(frozen.map((e) => e.vendor))],
+        freeEntries: () => frozen.filter((e) => !e.paid),
+        paidEntries: () => frozen.filter((e) => e.paid),
+    };
+}
+/**
+ * The platform-key guard: the ids from `requested` that a platform-funded
+ * call may serve. Registered-and-free passes; paid is dropped; an UNKNOWN id
+ * is dropped too — an id nobody registered has an unknown price, and "unknown"
+ * spends someone's money only when a person decides it does.
+ *
+ * Returns the dropped ids alongside, because a silently narrowed chain reads
+ * as "covered everything" when it didn't.
+ */
+function freeOnly(registry, requested) {
+    const allowed = [];
+    const dropped = [];
+    for (const id of requested) {
+        const entry = registry.find(id);
+        if (!entry)
+            dropped.push({ id, why: "unregistered" });
+        else if (entry.paid)
+            dropped.push({ id, why: "paid" });
+        else
+            allowed.push(id);
+    }
+    return { allowed, dropped };
+}
+/**
+ * A tool-driving chain may only contain models that can drive a tool loop.
+ * "unprobed" entries are reported, not silently trusted — the probe table is
+ * one `npm run probe:models` away, and a chain built on guesses loses turns
+ * exactly on the models most likely to serve free traffic.
+ */
+function toolCapable(registry, requested) {
+    const usable = [];
+    const refused = [];
+    for (const id of requested) {
+        const entry = registry.find(id);
+        const protocol = entry?.toolProtocol ?? "unprobed";
+        if (protocol === "native" || protocol === "text")
+            usable.push(id);
+        else
+            refused.push({ id, protocol });
+    }
+    return { usable, refused };
+}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@bitbaum/ai-kit",
+  "version": "0.6.2",
+  "description": "One install for the AI layer of an app: which model to call, what to do when the vendor retires it, how to walk the fallback chain and know when none of it worked, how to read the three kinds of 429, a fair daily budget across users, headless AI form filling — and now the model registry (one SSOT for every callable id, with the paid/free boundary as a field) and the grounding harness (facts, contract, deterministic fabrication check).",
+  "license": "MIT",
+  "author": "Mao Nakamoto",
+  "homepage": "https://github.com/bitbaum/ai-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitbaum/ai-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bitbaum/ai-kit/issues"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "form-fill",
+    "fallback",
+    "failover",
+    "health-check",
+    "free-tier",
+    "rate-limit",
+    "quota",
+    "fair-share",
+    "groq",
+    "openrouter"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "dist-cjs",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./forms": {
+      "types": "./dist/forms.d.ts",
+      "default": "./dist/forms.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "require": "./dist-cjs/registry.js",
+      "default": "./dist/registry.js"
+    },
+    "./grounding": {
+      "types": "./dist/grounding/index.d.ts",
+      "require": "./dist-cjs/grounding/index.js",
+      "default": "./dist/grounding/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist-cjs/package.json', JSON.stringify({type:'commonjs'})+'\\n')\"",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.js",
+    "check:catalog": "npm run build && node scripts/check-catalog.mjs",
+    "verify": "npm run format:check && npm run lint && npm run typecheck && npm run build && npm test",
+    "prepare": "npm run build",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.4.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
+    "prettier": "3.9.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.68.0"
+  },
+  "dependencies": {
+    "ai-forms": "^0.1.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/attempt.ts

@@ -0,0 +1,82 @@
+/**
+ * Walk a chain, never own the fetch.
+ *
+ * `usableChain`/`chainFrom` (chain.ts) already answer WHICH links exist and in
+ * what order. What was still missing — in every app that hand-rolled it, and
+ * inconsistently — is the loop that tries link one, and on failure tries link
+ * two, rather than picking the first link and calling it once. A chain nobody
+ * walks is a list, not a fallback: it was found sitting unused next to a
+ * single-shot caller in the same app that this package's `freeChain` already
+ * protected from a retired model but not from a dead key, because ordering the
+ * links and walking them were still two different jobs and only one had a
+ * home.
+ *
+ * This still ships no HTTP client. `attempt` is supplied by the caller and
+ * does the actual request; this only decides which link goes next, and
+ * records the outcome if a `HealthTracker` is given.
+ */
+
+import type { Link } from "./chain.js";
+import type { HealthTracker } from "./health.js";
+
+export interface ChainAttemptFailure {
+  link: Link;
+  message: string;
+}
+
+/** Every link in the chain was tried and failed (or the chain was empty). */
+export class ChainExhaustedError extends Error {
+  readonly failures: ChainAttemptFailure[];
+
+  constructor(failures: ChainAttemptFailure[]) {
+    super(
+      failures.length === 0
+        ? "No usable link in the chain — every provider is missing its key, or has no models configured."
+        : `All ${failures.length} link(s) failed — ${failures
+            .map((f) => `${f.link.provider.id}/${f.link.model}: ${f.message}`)
+            .join("; ")}`,
+    );
+    this.name = "ChainExhaustedError";
+    this.failures = failures;
+  }
+}
+
+export interface TryChainOptions<T> {
+  /** Makes the actual call for one link. Throw to demote to the next link. */
+  attempt: (link: Link) => Promise<T>;
+  /** Records one success or one failure for the WHOLE walk, not per link. */
+  health?: HealthTracker;
+  /** Called on each link's failure, before moving to the next — e.g. to log it. */
+  onLinkFailure?: (link: Link, error: unknown) => void;
+}
+
+/**
+ * Try each link in order; return the first success.
+ *
+ * Health is recorded once per call — a success on link two is still a success
+ * for the app, and a health check that flagged it "degraded" because the FIRST
+ * link failed would be reporting its own fallback working as a problem.
+ *
+ * Throws `ChainExhaustedError` (carrying every link's failure) when none
+ * succeed, so a caller can log exactly what was tried rather than only the
+ * last error — the failure that matters is often not the last one.
+ */
+export async function tryChain<T>(chain: Link[], options: TryChainOptions<T>): Promise<T> {
+  const failures: ChainAttemptFailure[] = [];
+
+  for (const link of chain) {
+    try {
+      const result = await options.attempt(link);
+      options.health?.recordSuccess();
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push({ link, message });
+      options.onLinkFailure?.(link, error);
+    }
+  }
+
+  const exhausted = new ChainExhaustedError(failures);
+  options.health?.recordFailure(exhausted);
+  throw exhausted;
+}