@cohortapp/agent-sdk 2.3.0

package/lib/model-router/resolve.mjs

@@ -0,0 +1,1206 @@
+/**
+ * lib/model-router/resolve.mjs — the resolveChain "brain" of the router (v2).
+ *
+ * This is the policy engine that sits on top of the catalog + failover + ledger
+ * substrate (catalog.mjs, taxonomy.mjs, failover.mjs, health.mjs, ledger.mjs).
+ * `resolveChain(request, opts)` is a PURE function of its injected snapshot —
+ * config, catalog, breaker state, budget band, env, clock — so it makes no
+ * network call and (when the snapshot is injected) touches no filesystem. It
+ * returns a `RouteDecision` describing which model/harness to run a unit of work
+ * on, the env to retarget a session spawn, the spawn args, an estimated cost,
+ * the candidates it skipped (with reasons), and a MANDATORY one-line `explain`.
+ *
+ * Routing happens at task-dispatch time, NEVER mid-session. Cache prefixes are
+ * model-scoped; a mid-session switch silently re-bills the entire prefix.
+ *
+ *   resolveChain(req):
+ *     0  MAESTRO_ROUTER_FORCE_ANTHROPIC kill switch → Anthropic-only chain
+ *     1  ensure req.data_class (deny-default "sensitive") + needs_tool_use (W5)
+ *     2  first-match over routing_policy (strict-validated structured features)
+ *     3  rule.chain aliases → catalog rows
+ *     4  gate each candidate IN ORDER, recording rejections in tried[]:
+ *          status ▸ harness ▸ capability/grade ▸ context ▸ data_class
+ *          ▸ credential(auth_env) ▸ breaker(health.isOpen) ▸ budget ladder
+ *     5  affinity pin moved to head when it still passes the gates
+ *     6  fallback_to_anthropic safety net if everything is rejected
+ *     7  build chosen + envForSpawn + spawnArgs + estCostUSD + explain + audit
+ *
+ * House style: ESM .mjs, Node 20, near-zero-dep; mirrors the DI discipline of
+ * lib/resource-governor.mjs / lib/rate-guard.mjs — every external dependency
+ * (catalog, breaker, env, clock, budget band) is injectable. NEVER throws on the
+ * resolve path: a broken snapshot degrades to the Anthropic safety net.
+ *
+ * @module lib/model-router/resolve
+ */
+
+import { loadCatalogCached, lookupModel } from "./catalog.mjs";
+import { estimateCost } from "./ledger.mjs";
+import { keyFor, isOpen as breakerIsOpen } from "./health.mjs";
+import { nextCredential as authNextCredential, available as authAvailable } from "./auth-profiles.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants / vocabulary
+// ---------------------------------------------------------------------------
+
+const GRADE_RANK = { A: 3, B: 2, C: 1 };
+const DATA_CLASSES = new Set(["public", "internal", "sensitive"]);
+const DATA_CLASS_RANK = { public: 1, internal: 2, sensitive: 3 };
+const HARNESSES = new Set(["session", "direct", "batch"]);
+
+// The session-retarget transport: a row whose chosen harness is `session` runs
+// inside `claude` via ANTHROPIC_BASE_URL. Anthropic rows keep the stock CLI/API;
+// third-party rows that expose an `/anthropic` endpoint are "anthropic-native".
+const TRANSPORT = Object.freeze({
+  anthropicCli: "anthropic-cli",
+  anthropicApi: "anthropic-api",
+  anthropicNative: "anthropic-native",
+  anthropicMessages: "anthropic-messages",
+  openaiCompletions: "openai-completions",
+});
+
+// The closed set of routing_policy match keys. A key outside this set is a
+// strict-validation error (W10 — a typo'd safety rule must fail loudly, never
+// silently never-match). All match against STRUCTURED METADATA only — message
+// content never reaches the rule engine (prompt-injection cannot steer T0).
+const VALID_MATCH_KEYS = new Set([
+  // v2 features
+  "task_class",
+  "channel",
+  "source",
+  "data_class",
+  "lane",
+  "priority",
+  "agent_role",
+  "agent_role_in",
+  "needs_tool_use",
+  "needs_thinking",
+  "needs_vision",
+  "needs_long_context",
+  "needs_parallel_tools",
+  "token_estimate_gte",
+  "token_estimate_lt",
+  "budget_band_gte",
+  "pin",
+  // glob-friendly alternates handled by matchValue (task_class supports "*")
+]);
+
+// Default per-task-class maxTurns; falls back to a generic ceiling.
+const DEFAULT_MAX_TURNS = 40;
+const TASK_CLASS_MAX_TURNS = Object.freeze({
+  "classify.inbox": 1,
+  "lookup": 2,
+  "enrich": 3,
+  "voice.brief": 4,
+  "learning.reflect": 6,
+  "learning.curate": 6,
+});
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+
+function nowMs(opts) {
+  return (opts && typeof opts.now === "function" ? opts.now : Date.now)();
+}
+
+function envOf(opts) {
+  return (opts && opts.env) || process.env || {};
+}
+
+function isForceAnthropic(env) {
+  const v = env && env.MAESTRO_ROUTER_FORCE_ANTHROPIC;
+  return v === "1" || v === "true";
+}
+
+/**
+ * A short, sortable, ULID-ish id: 10 chars of base32 time + 8 random base32.
+ * Not a real ULID (no Crockford spec guarantees) but monotonic-ish and unique
+ * enough to join a decision row ↔ ledger row ↔ resume marker.
+ */
+const B32 = "0123456789abcdefghjkmnpqrstvwxyz";
+function ulidish(now, rnd = Math.random) {
+  let t = Math.floor(now);
+  let time = "";
+  for (let i = 0; i < 10; i++) {
+    time = B32[t % 32] + time;
+    t = Math.floor(t / 32);
+  }
+  let rand = "";
+  for (let i = 0; i < 8; i++) rand += B32[Math.floor(rnd() * 32)];
+  return time + rand;
+}
+
+/** Resolve the merged catalog from opts (injected catalog wins; else load). */
+function resolveCatalog(agentRoot, opts) {
+  if (opts && opts.catalog) {
+    // Accept either a CatalogResult or its .catalog
+    return opts.catalog.byRef ? opts.catalog : opts.catalog.catalog || opts.catalog;
+  }
+  return loadCatalogCached(agentRoot, opts || {});
+}
+
+// ---------------------------------------------------------------------------
+// Policy rule matching (structured metadata only)
+// ---------------------------------------------------------------------------
+
+/** Glob match supporting a single trailing/embedded "*" (task_class "lookup.*"). */
+function globMatch(pattern, value) {
+  if (typeof pattern !== "string") return pattern === value;
+  if (!pattern.includes("*")) return pattern === value;
+  const re = new RegExp(
+    "^" + pattern.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+  );
+  return typeof value === "string" && re.test(value);
+}
+
+function matchesRule(match, req) {
+  for (const [key, expected] of Object.entries(match || {})) {
+    switch (key) {
+      case "token_estimate_gte":
+        if ((req.token_estimate ?? 0) < expected) return false;
+        break;
+      case "token_estimate_lt":
+        if ((req.token_estimate ?? 0) >= expected) return false;
+        break;
+      case "budget_band_gte":
+        if ((req.budget_band ?? 0) < expected) return false;
+        break;
+      case "agent_role_in":
+        if (!Array.isArray(expected) || !expected.includes(req.agent_role)) return false;
+        break;
+      case "task_class":
+      case "channel":
+      case "source":
+      case "lane":
+        if (!globMatch(expected, req[key])) return false;
+        break;
+      case "pin":
+        if (Boolean(req.pin) !== Boolean(expected)) return false;
+        break;
+      default:
+        if (req[key] !== expected) return false;
+    }
+  }
+  return true;
+}
+
+/** First-match over routing_policy. Returns { rule, index } or the default. */
+function pickRule(policy, req) {
+  const rules = Array.isArray(policy) ? policy : [];
+  for (let i = 0; i < rules.length; i++) {
+    const rule = rules[i];
+    if (!rule) continue;
+    if (rule.default) return { rule, index: i };
+    if (matchesRule(rule.match || {}, req)) return { rule, index: i };
+  }
+  // No rule matched and no explicit default — synthesize one.
+  return { rule: { default: true, synthesized: true }, index: -1 };
+}
+
+// ---------------------------------------------------------------------------
+// Alias resolution → catalog refs
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a chain of aliases/refs to concrete catalog refs, preserving order.
+ * A "rules" member (the caller's deterministic fallback as a chain member) is
+ * passed through as a sentinel ref so failover.mjs / the caller can treat it as
+ * a terminal candidate. Unknown aliases collapse to null (recorded by caller).
+ */
+function resolveChainRefs(chainSpec, aliases) {
+  const out = [];
+  for (const member of Array.isArray(chainSpec) ? chainSpec : []) {
+    if (member === "rules") {
+      out.push({ ref: "rules", isRules: true, alias: "rules" });
+      continue;
+    }
+    if (typeof member !== "string") continue;
+    // A member may be an alias name OR a literal "provider/model" ref.
+    const ref = aliases && Object.prototype.hasOwnProperty.call(aliases, member)
+      ? aliases[member]
+      : member;
+    out.push({ ref, isRules: false, alias: member === ref ? null : member });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Budget ladder (degrade, never cliff) — operates on the alias list
+// ---------------------------------------------------------------------------
+
+const DEGRADE_ORDER = ["frontier", "default", "fast", "cheap"];
+
+/**
+ * Apply the budget ladder to a resolved chain of alias-tagged refs. Returns a
+ * possibly-reordered/extended ref list + a note for the explain string. Pins
+ * and critical priority are exempt below band 100.
+ */
+function applyBudgetLadder(refs, req, aliases, band) {
+  if (!band || band < 75) return { refs, note: null };
+  const exempt = req.pin || req.priority === "critical";
+  if (exempt) return { refs, note: `band ${band} (exempt: ${req.pin ? "pin" : "critical"})` };
+
+  // Map known aliases to their degrade index; downgrade one tier at >=75.
+  const cheapest = (name) => {
+    const i = DEGRADE_ORDER.indexOf(name);
+    return i === -1 ? name : DEGRADE_ORDER[Math.min(DEGRADE_ORDER.length - 1, i + 1)];
+  };
+
+  if (band >= 90) {
+    // cheap/fast only: drop frontier/default aliases from the head, keep cheap/fast.
+    const kept = refs.filter((r) => r.alias !== "frontier" && r.alias !== "default");
+    const head = kept.length ? kept : refs; // never end up with an empty chain
+    return { refs: head, note: `band ${band} downgraded to cheap/fast lane` };
+  }
+
+  // band >= 75: downgrade one tier where the alias is a known degrade rung.
+  let changed = false;
+  const next = refs.map((r) => {
+    if (r.alias && DEGRADE_ORDER.includes(r.alias)) {
+      const downAlias = cheapest(r.alias);
+      if (downAlias !== r.alias && aliases[downAlias]) {
+        changed = true;
+        return { ref: aliases[downAlias], isRules: false, alias: downAlias };
+      }
+    }
+    return r;
+  });
+  return { refs: next, note: changed ? `band ${band} downgraded one tier` : `band ${band}` };
+}
+
+// ---------------------------------------------------------------------------
+// Per-candidate gating
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the credential a row needs, honoring an optional pooled auth-profile
+ * set (OpenClaw auth-profile rotation). ADDITIVE + FAIL-OPEN:
+ *   - No pool wired (ctx.authProfiles absent) OR provider not pooled (<=1 key) →
+ *     fall back to the single env var exactly as before (token = env[auth_env]).
+ *   - Pooled (>1 key) → pick the next non-cooled credential round-robin; if every
+ *     key is cooling, return { token:null, poolExhausted:true } so the gate skips
+ *     this backend with `missing_credential` (the pool looks dry — failover moves
+ *     on, the per-key cooldowns self-heal independently).
+ *
+ * Returns { token: string|null, pooled: boolean, fingerprint: string|null,
+ *           poolExhausted: boolean }.
+ */
+function resolveRowCredential(row, ctx) {
+  const authEnv = row.auth_env;
+  if (!authEnv) return { token: null, pooled: false, fingerprint: null, poolExhausted: false };
+
+  const profiles = ctx && ctx.authProfiles;
+  const provider = row.provider;
+  const pooled =
+    profiles && typeof profiles.isPooled === "function" && profiles.isPooled(provider);
+
+  // Single-key (or no pool): preserve today's behavior exactly.
+  if (!pooled) {
+    const v = ctx.env[authEnv];
+    const token = typeof v === "string" && v.trim() !== "" ? v : null;
+    return { token, pooled: false, fingerprint: null, poolExhausted: false };
+  }
+
+  // Pooled: pick the next non-cooled credential. The pick advances the cursor
+  // (persisted under the ledger lock) so repeated resolves rotate.
+  const pick = authNextCredential(provider, {
+    profiles,
+    now: ctx.now,
+    deps: ctx.authProfileDeps,
+  });
+  if (pick && pick.key) {
+    return { token: pick.key, pooled: true, fingerprint: pick.fingerprint, poolExhausted: false };
+  }
+  // Every key in the pool is cooling — the backend is effectively credential-less
+  // for now. Surface as missing_credential so the gate skips it.
+  return { token: null, pooled: true, fingerprint: null, poolExhausted: true };
+}
+
+/**
+ * Run a candidate row through the ordered gate. Returns { ok:true } or
+ * { ok:false, reason } where reason is one of the tried[] reason strings.
+ */
+function gateCandidate(row, req, ctx) {
+  // 1. status — only `available` rows are routable.
+  if (row.status !== "available") {
+    return { ok: false, reason: `status_${row.status}` };
+  }
+
+  // 2. harness — the requested harness must be offered by the row.
+  const harness = ctx.harness;
+  if (harness && row.harness && row.harness[harness] !== true) {
+    return { ok: false, reason: `harness_unavailable:${harness}` };
+  }
+
+  // 3. capability + tool-reliability grade.
+  //    A session that needs tool use requires grade A (§6.6) — grade B/C rows
+  //    are structurally unreachable for sessions.
+  if (req.needs_tool_use && harness === "session") {
+    const rank = row.tool_reliability ? GRADE_RANK[row.tool_reliability] : 0;
+    if (rank < GRADE_RANK.A) {
+      return { ok: false, reason: "grade_too_low" };
+    }
+  }
+  // Explicit grade floor from the rule (minGrade).
+  if (ctx.minGrade) {
+    const rank = row.tool_reliability ? GRADE_RANK[row.tool_reliability] : 0;
+    if (rank < (GRADE_RANK[ctx.minGrade] || 0)) {
+      return { ok: false, reason: "grade_too_low" };
+    }
+  }
+
+  // 4. context — token_estimate must fit the row's effective runtime cap.
+  if (req.token_estimate != null && row.context_tokens != null) {
+    if (req.token_estimate > row.context_tokens) {
+      return { ok: false, reason: "context_overflow" };
+    }
+  }
+
+  // 5. data_class — deny-by-default. The provider's allowed_data_classes
+  //    (config backends ∩ overlay max) must include the request's data_class.
+  const allowed = ctx.allowedDataClasses[row.provider];
+  if (allowed && !allowed.has(req.data_class)) {
+    return { ok: false, reason: "data_class_denied" };
+  }
+  // Even without a backends entry, anything but Anthropic is deny-by-default for
+  // non-public classes unless the config explicitly allows it.
+  if (!allowed && row.provider !== "anthropic" && req.data_class !== "public") {
+    return { ok: false, reason: "data_class_denied" };
+  }
+
+  // 6. credential — auth_env must be present & non-empty (key-absence-as-
+  //    enforcement, §7.1). EXCEPTION: an Anthropic SESSION candidate rides the
+  //    stock `claude` CLI / keychain-OAuth (or a Console key the spawner owns),
+  //    so it never needs ANTHROPIC_API_KEY injected — the v1 resolver treated
+  //    anthropic-cli the same way. Direct-api Anthropic and ALL third-party rows
+  //    require their credential or they are structurally unreachable.
+  const sessionAnthropic = row.provider === "anthropic" && harness === "session";
+  if (row.auth_env && !sessionAnthropic) {
+    const cred = resolveRowCredential(row, ctx);
+    if (!cred.token) {
+      return { ok: false, reason: "missing_credential" };
+    }
+  }
+
+  // 7. breaker — the per-backend AND per-backend:model breaker must be closed.
+  const backendKey = keyFor(row.provider);
+  const modelKey = keyFor(row.provider, modelClassOf(row));
+  if (ctx.isOpen(backendKey).open) return { ok: false, reason: "breaker_open" };
+  if (ctx.isOpen(modelKey).open) return { ok: false, reason: "breaker_open" };
+
+  return { ok: true };
+}
+
+/**
+ * The model-class segment for the breaker key. We use the bare id; callers that
+ * want coarser bucketing (sonnet/haiku) can override via catalog, but the id is
+ * the stable, collision-free default.
+ */
+function modelClassOf(row) {
+  return row.id;
+}
+
+// ---------------------------------------------------------------------------
+// envForSpawn / transport / wire derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the env to retarget a `claude` SESSION spawn onto a row's backend.
+ * - Anthropic rows: no retarget (stock CLI/OAuth or Console key the caller owns).
+ * - Third-party rows with an /anthropic endpoint: ANTHROPIC_BASE_URL retarget +
+ *   ANTHROPIC_AUTH_TOKEN from auth_env + ANTHROPIC_API_KEY="" (so Claude Code
+ *   does NOT fall back to keychain OAuth) + ANTHROPIC_MODEL.
+ * Returns {} for non-session harnesses (direct-api builds its own request).
+ */
+function buildEnvForSpawn(row, harness, env, config, credCtx) {
+  if (harness !== "session") return {};
+  if (row.provider === "anthropic") return {};
+
+  const baseUrl = row.endpoints && row.endpoints.anthropic;
+  if (!baseUrl) return {}; // not session-capable on the anthropic wire; caller falls back
+
+  const out = {
+    ANTHROPIC_BASE_URL: baseUrl,
+    ANTHROPIC_API_KEY: "", // explicit empty string — NOT unset (W: keychain fallthrough)
+    ANTHROPIC_MODEL: row.id,
+    ANTHROPIC_SMALL_FAST_MODEL: row.id,
+  };
+  // Auth token: a pooled auth-profile set picks the next non-cooled credential
+  // (additive — a single-key setup falls through to env[auth_env] exactly as
+  // before). credCtx carries { authProfiles, authProfileDeps, now, env }.
+  if (row.auth_env) {
+    const cred = credCtx ? resolveRowCredential(row, credCtx) : null;
+    if (cred && cred.pooled && cred.token) {
+      out.ANTHROPIC_AUTH_TOKEN = cred.token;
+    } else if (typeof env[row.auth_env] === "string") {
+      out.ANTHROPIC_AUTH_TOKEN = env[row.auth_env];
+    }
+  }
+  if (!config || config.strip_attribution_header !== false) {
+    out.CLAUDE_CODE_ATTRIBUTION_HEADER = "0";
+  }
+  if (!config || config.disable_experimental_betas !== false) {
+    out.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1";
+  }
+  return out;
+}
+
+function transportFor(row, harness) {
+  if (harness === "session") {
+    if (row.provider === "anthropic") return TRANSPORT.anthropicApi;
+    return TRANSPORT.anthropicNative;
+  }
+  // direct-api / batch
+  if (row.provider === "anthropic") return TRANSPORT.anthropicMessages;
+  return TRANSPORT.openaiCompletions;
+}
+
+function wireFor(row, harness) {
+  // The wire dialect the direct-api path speaks. Session spawns ride `claude`,
+  // so the wire is informational there.
+  if (row.provider === "anthropic") return "anthropic";
+  // A row routed on the anthropic-native session transport still speaks the
+  // anthropic wire; a direct-api third-party call uses the openai wire.
+  if (harness === "session") return "anthropic";
+  return "openai";
+}
+
+function modelFlagFor(row) {
+  // For Anthropic the CLI accepts the shorthand; for others Claude Code passes
+  // ANTHROPIC_MODEL through, so the flag is the concrete id either way.
+  return row.id;
+}
+
+function maxTurnsFor(taskClass) {
+  if (!taskClass) return DEFAULT_MAX_TURNS;
+  if (TASK_CLASS_MAX_TURNS[taskClass] != null) return TASK_CLASS_MAX_TURNS[taskClass];
+  // Prefix match (e.g. "lookup.gmail" → "lookup").
+  const head = String(taskClass).split(".")[0];
+  if (TASK_CLASS_MAX_TURNS[head] != null) return TASK_CLASS_MAX_TURNS[head];
+  return DEFAULT_MAX_TURNS;
+}
+
+// ---------------------------------------------------------------------------
+// data_class resolution from config + overlay
+// ---------------------------------------------------------------------------
+
+/**
+ * Build provider -> Set(allowed data classes), intersecting config backends with
+ * the overlay's allowed_data_classes_max (tighten-only).
+ */
+function buildAllowedDataClasses(config, overlay) {
+  const out = {};
+  const backends = (config && config.backends) || {};
+  for (const [name, b] of Object.entries(backends)) {
+    const adc = Array.isArray(b && b.allowed_data_classes) ? b.allowed_data_classes : null;
+    if (adc) out[name] = new Set(adc.filter((c) => DATA_CLASSES.has(c)));
+  }
+  // Anthropic defaults to all classes if unspecified.
+  if (!out.anthropic) out.anthropic = new Set(["public", "internal", "sensitive"]);
+
+  const max = overlay && overlay.constraints && overlay.constraints.allowed_data_classes_max;
+  if (max && typeof max === "object") {
+    for (const [name, list] of Object.entries(max)) {
+      if (!Array.isArray(list)) continue;
+      const cap = new Set(list.filter((c) => DATA_CLASSES.has(c)));
+      out[name] = out[name] ? intersect(out[name], cap) : cap;
+    }
+  }
+  return out;
+}
+
+function intersect(a, b) {
+  const out = new Set();
+  for (const x of a) if (b.has(x)) out.add(x);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// resolveChain — the public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} RouteDecision
+ * @property {string} decision_id
+ * @property {Array<{ref,harness,transport}>} chain
+ * @property {{provider,model,harness,transport,wire,catalogRow}} chosen
+ * @property {object} envForSpawn
+ * @property {{modelFlag,maxTurns,effort,maxBudgetUsd,agentsJson,bare}} spawnArgs
+ * @property {string} lane
+ * @property {string} cacheAffinityKey
+ * @property {string} cache_ttl
+ * @property {number|null} estCostUSD
+ * @property {Array<{ref,ok:false,reason}>} tried
+ * @property {string} explain   MANDATORY one-line human string
+ * @property {{rule,fallback_reason,config_source,overlay_version,catalog_provenance}} audit
+ */
+
+/**
+ * Resolve a RouteRequest to a RouteDecision. NEVER throws — a broken snapshot
+ * degrades to an Anthropic safety-net decision (or, under the kill switch, an
+ * Anthropic-only chain).
+ *
+ * @param {object} request  RouteRequest (§4.3)
+ * @param {object} [opts]
+ *   @param {string} [opts.agentRoot]
+ *   @param {object} [opts.config]     normalised routing config (v2)
+ *   @param {object} [opts.catalog]    CatalogResult (injected; else loaded)
+ *   @param {object} [opts.overlay]    org policy overlay (already verified)
+ *   @param {object} [opts.env]        env for credential + kill-switch checks
+ *   @param {(key:string)=>{open:boolean,until,reason,strikes}} [opts.isOpen]
+ *                                     breaker probe (defaults to health.isOpen)
+ *   @param {()=>number} [opts.now]
+ *   @param {(n)=>number} [opts.rng]
+ * @returns {RouteDecision}
+ */
+export function resolveChain(request = {}, opts = {}) {
+  const env = envOf(opts);
+  const now = nowMs(opts);
+  const agentRoot = opts.agentRoot;
+  const config = opts.config || null;
+  const overlay = opts.overlay || (config && config.overlay) || null;
+
+  // Breaker probe: injectable; defaults to the on-disk health.mjs breaker.
+  const isOpen = typeof opts.isOpen === "function"
+    ? (key) => opts.isOpen(key, now)
+    : (key) => breakerIsOpen(key, now, opts.breakerDeps || { agentRoot });
+
+  // 1. Normalise the request (deny-default data_class; W5 needs_tool_use).
+  const req = normaliseRequest(request, config);
+
+  const catalogResult = safe(() => resolveCatalog(agentRoot, opts), null);
+  const catalog = catalogResult && (catalogResult.byRef ? catalogResult : catalogResult.catalog)
+    ? catalogResult
+    : null;
+
+  const tried = [];
+  const audit = {
+    rule: null,
+    fallback_reason: null,
+    config_source: (config && config.source_path) || (catalogResult && catalogResult.sources && catalogResult.sources.join("+")) || null,
+    overlay_version: (overlay && overlay.version) || null,
+    catalog_provenance: catalogProvenanceTag(catalog),
+  };
+
+  // 0. Kill switch — force an Anthropic-only chain regardless of policy.
+  if (isForceAnthropic(env)) {
+    return forceAnthropicDecision(catalog, req, { now, opts, audit, reason: "kill_switch" });
+  }
+
+  // No config at all → inert v2 path: an Anthropic safety-net decision so the
+  // caller always has a usable chosen (matching the "collapse to today" rule).
+  if (!config || (config.schema_version !== 2 && !Array.isArray(config.routing_policy))) {
+    return forceAnthropicDecision(catalog, req, { now, opts, audit, reason: "no_v2_config" });
+  }
+
+  const aliases = (config.aliases && typeof config.aliases === "object") ? config.aliases : {};
+  const allowedDataClasses = buildAllowedDataClasses(config, overlay);
+
+  // 2. First-match rule.
+  const { rule, index } = pickRule(config.routing_policy, req);
+  audit.rule = rule.default ? (rule.synthesized ? "<synthesized-default>" : "<default>") : (rule.match ? JSON.stringify(rule.match) : `rule[${index}]`);
+
+  // Rule-level overrides.
+  const ruleHarness = rule.harness || req.harness_hint || (req.lane === "batch" ? "batch" : "session");
+  const harness = HARNESSES.has(ruleHarness) ? ruleHarness : "session";
+  // A rule may opt out of tool use explicitly (classify/lookup are tool-less).
+  if (rule.needs_tool_use === false) req.needs_tool_use = false;
+  const minGrade = rule.minGrade || null;
+  const lane = req.lane || (harness === "batch" ? "batch" : "realtime");
+
+  // 3. Alias chain → refs, then budget ladder.
+  let refs = resolveChainRefs(rule.chain, aliases);
+  const ladder = applyBudgetLadder(refs, req, aliases, req.budget_band);
+  refs = ladder.refs;
+
+  // 4. Gate each candidate; first survivor is chosen.
+  const ctx = {
+    env,
+    harness,
+    minGrade,
+    allowedDataClasses,
+    isOpen,
+    // Auth-profile rotation context (additive; absent ⇒ single-key behavior).
+    authProfiles: opts.authProfiles || null,
+    authProfileDeps: opts.authProfileDeps || (agentRoot ? { agentRoot } : undefined),
+    now,
+  };
+
+  let chosenRow = null;
+  let chosenHarness = harness;
+  const chainOut = [];
+  const explainSkips = [];
+
+  for (const member of refs) {
+    if (member.isRules) {
+      // The deterministic-fallback sentinel: a terminal candidate the caller
+      // owns. It always "passes" (no model gate) but is never the chosen row
+      // unless nothing else survived — record it on the chain and continue.
+      chainOut.push({ ref: "rules", harness: "direct", transport: "rules" });
+      if (!chosenRow) {
+        // Keep walking; a real model later in the chain is preferred. We only
+        // fall to "rules" if no model survives (handled after the loop).
+      }
+      continue;
+    }
+    const row = catalog ? lookupModel(catalog, member.ref) : null;
+    if (!row) {
+      tried.push({ ref: member.ref, ok: false, reason: "unknown_ref" });
+      explainSkips.push(`${member.ref} (unknown_ref)`);
+      continue;
+    }
+    const gate = gateCandidate(row, req, ctx);
+    if (!gate.ok) {
+      tried.push({ ref: member.ref, ok: false, reason: gate.reason });
+      explainSkips.push(`${member.ref} (${gate.reason})`);
+      continue;
+    }
+    // Survivor. Record it on the visible chain.
+    chainOut.push({
+      ref: row.ref,
+      harness: chosenHarness,
+      transport: transportFor(row, chosenHarness),
+    });
+    if (!chosenRow) {
+      chosenRow = row;
+      // Continue building the rest of the chain (the failover tail) from the
+      // remaining members so spawnRouted has somewhere to go.
+    }
+  }
+
+  // 4b. If no model survived but the chain had a "rules" sentinel, the caller's
+  //     deterministic fallback is the answer (direct, no model).
+  const hasRules = refs.some((m) => m.isRules);
+
+  // 5. Affinity pin — if a live pin for the session_key passes the gates, move
+  //    it to the head; a pin that fails the gates emits pin_overridden.
+  let affinityNote = null;
+  if (req.pin && req.pin.ref && catalog) {
+    const pinRow = lookupModel(catalog, req.pin.ref);
+    if (pinRow) {
+      const g = gateCandidate(pinRow, req, ctx);
+      if (g.ok) {
+        chosenRow = pinRow;
+        chosenHarness = harness;
+        // Move/insert the pin at the chain head.
+        const head = { ref: pinRow.ref, harness, transport: transportFor(pinRow, harness) };
+        const rest = chainOut.filter((c) => c.ref !== pinRow.ref);
+        chainOut.length = 0;
+        chainOut.push(head, ...rest);
+        affinityNote = `pin ${pinRow.ref}`;
+      } else {
+        tried.push({ ref: pinRow.ref, ok: false, reason: `pin_overridden:${g.reason}` });
+        affinityNote = `pin_overridden (${g.reason})`;
+      }
+    }
+  }
+
+  // 6. Fallback to the Anthropic safety net when nothing survived.
+  if (!chosenRow) {
+    if (hasRules) {
+      return rulesDecision(req, { now, opts, audit, tried, chainOut, lane, explainSkips });
+    }
+    if (config.fallback_to_anthropic !== false) {
+      audit.fallback_reason = "no_compatible_candidate";
+      return forceAnthropicDecision(catalog, req, {
+        now, opts, audit, tried, reason: "no_compatible_candidate", harness, lane,
+        explainSkips,
+      });
+    }
+    // No fallback declared — return an explicit no-route decision.
+    return noRouteDecision(req, { now, opts, audit, tried, explainSkips, lane });
+  }
+
+  // 7. Build the decision.
+  return buildDecision({
+    catalog,
+    row: chosenRow,
+    harness: chosenHarness,
+    req,
+    config,
+    env,
+    now,
+    opts,
+    rule,
+    audit,
+    tried,
+    chain: chainOut,
+    lane,
+    ladderNote: ladder.note,
+    affinityNote,
+    explainSkips,
+    credCtx: ctx,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Request normalisation
+// ---------------------------------------------------------------------------
+
+function normaliseRequest(request, config) {
+  const req = { ...request };
+  // data_class deny-default.
+  if (!DATA_CLASSES.has(req.data_class)) {
+    const dflt = (config && config.defaults && config.defaults.data_class) || "sensitive";
+    req.data_class = DATA_CLASSES.has(dflt) ? dflt : "sensitive";
+  }
+  // needs_tool_use default-true for SESSION work (W5), unless explicitly set.
+  const sessionDefaultTools =
+    !config || !config.defaults || config.defaults.needs_tool_use_for_sessions !== false;
+  if (req.needs_tool_use === undefined) {
+    const willBeSession = (req.harness_hint || (req.lane === "batch" ? "batch" : "session")) === "session";
+    req.needs_tool_use = willBeSession && sessionDefaultTools;
+  }
+  return req;
+}
+
+// ---------------------------------------------------------------------------
+// Decision builders
+// ---------------------------------------------------------------------------
+
+function buildDecision({ catalog, row, harness, req, config, env, now, opts, rule, audit, tried, chain, lane, ladderNote, affinityNote, explainSkips, credCtx }) {
+  const decision_id = ulidish(now, opts.rng);
+  const transport = transportFor(row, harness);
+  const envForSpawn = buildEnvForSpawn(row, harness, env, config, credCtx);
+
+  const cache_ttl =
+    (config && config.defaults && config.defaults.cache_ttl) ||
+    (lane === "realtime" ? "1h" : "1h");
+
+  const cacheAffinityKey = req.session_key
+    ? `${req.session_key}:${row.ref}`
+    : `${req.task_class || "task"}:${row.ref}`;
+
+  // Estimate cost (budget projection: volatile rows at steady-state).
+  const tokenIn = req.token_estimate ?? 0;
+  const tokenOut = req.token_estimate_out ?? Math.floor(tokenIn * 0.4);
+  const est = estimateCost(catalog, {
+    ref: row.ref,
+    inputTokens: tokenIn,
+    outputTokens: tokenOut,
+    cacheReadTokens: req.cache_read_estimate ?? 0,
+    budget: true,
+  });
+
+  const spawnArgs = {
+    modelFlag: modelFlagFor(row),
+    maxTurns: maxTurnsFor(req.task_class),
+    effort: rule && rule.effort ? rule.effort : null,
+    maxBudgetUsd: rule && rule.max_budget_usd != null ? rule.max_budget_usd : null,
+    agentsJson: rule && rule.agents_json ? rule.agents_json : null,
+    bare: true,
+  };
+
+  const explain = buildExplain({
+    req, rule, row, harness, ladderNote, affinityNote, explainSkips, est,
+  });
+
+  return {
+    decision_id,
+    chain,
+    chosen: {
+      provider: row.provider,
+      model: row.id,
+      harness,
+      transport,
+      wire: wireFor(row, harness),
+      catalogRow: row,
+    },
+    envForSpawn,
+    spawnArgs,
+    lane,
+    cacheAffinityKey,
+    cache_ttl,
+    estCostUSD: est.usd,
+    tried,
+    explain,
+    audit,
+  };
+}
+
+/**
+ * The Anthropic-only / safety-net decision. Used by the kill switch, the
+ * no-v2-config inert path, and the "nothing survived the gates" fallback. Picks
+ * the best available Anthropic row for the request's needs.
+ */
+function forceAnthropicDecision(catalog, req, { now, opts, audit, tried = [], reason, harness = "session", lane = "realtime", explainSkips = [] }) {
+  const row = pickAnthropicRow(catalog, req);
+  const decision_id = ulidish(now, opts && opts.rng);
+  const env = envOf(opts);
+
+  if (!row) {
+    // No catalog at all — degrade to a synthetic chosen so the caller still has
+    // a usable model flag (stock `claude` defaults to its account model).
+    const synthetic = {
+      provider: "anthropic",
+      id: req.needs_thinking || req.priority === "critical" ? "claude-opus-4-8" : "claude-sonnet-4-6",
+      ref: "anthropic/claude-sonnet-4-6",
+      status: "available",
+      auth_env: null,
+      endpoints: {},
+      cost: {},
+      cost_provenance: {},
+      compat: {},
+      harness: { session: true, direct: true, batch: true },
+      tool_reliability: "A",
+      context_tokens: null,
+    };
+    return synthDecision(synthetic, req, { now, opts, audit, tried, reason, harness, lane, explainSkips, env, catalog });
+  }
+  return synthDecision(row, req, { now, opts, audit, tried, reason, harness, lane, explainSkips, env, catalog });
+}
+
+function synthDecision(row, req, { now, opts, audit, tried, reason, harness, lane, explainSkips, env, catalog }) {
+  const decision_id = ulidish(now, opts && opts.rng);
+  const transport = transportFor(row, harness);
+  const est = catalog ? estimateCost(catalog, {
+    ref: row.ref,
+    inputTokens: req.token_estimate ?? 0,
+    outputTokens: req.token_estimate_out ?? Math.floor((req.token_estimate ?? 0) * 0.4),
+    budget: true,
+  }) : { usd: null };
+  audit.fallback_reason = audit.fallback_reason || reason;
+
+  const explainBase =
+    reason === "kill_switch"
+      ? "kill switch (MAESTRO_ROUTER_FORCE_ANTHROPIC) → Anthropic-only"
+      : reason === "no_v2_config"
+        ? "no v2 routing config → Anthropic safety net"
+        : `${req.task_class || "task"} → Anthropic safety net (${reason})`;
+  const skipNote = explainSkips && explainSkips.length ? `; skipped ${explainSkips.join(", ")}` : "";
+
+  return {
+    decision_id,
+    chain: [{ ref: row.ref, harness, transport }],
+    chosen: {
+      provider: "anthropic",
+      model: row.id,
+      harness,
+      transport,
+      wire: "anthropic",
+      catalogRow: row,
+    },
+    envForSpawn: {}, // Anthropic session: stock CLI/Console key, no retarget
+    spawnArgs: {
+      modelFlag: row.id,
+      maxTurns: maxTurnsFor(req.task_class),
+      effort: null,
+      maxBudgetUsd: null,
+      agentsJson: null,
+      bare: true,
+    },
+    lane,
+    cacheAffinityKey: req.session_key ? `${req.session_key}:${row.ref}` : `${req.task_class || "task"}:${row.ref}`,
+    cache_ttl: "1h",
+    estCostUSD: est.usd,
+    tried,
+    explain: `${explainBase}: ${row.ref}${skipNote}`,
+    audit,
+  };
+}
+
+/** The deterministic-fallback ("rules") decision — no model, caller-owned. */
+function rulesDecision(req, { now, opts, audit, tried, chainOut, lane, explainSkips }) {
+  const decision_id = ulidish(now, opts && opts.rng);
+  audit.fallback_reason = audit.fallback_reason || "rules_fallback";
+  const skipNote = explainSkips && explainSkips.length ? ` (skipped ${explainSkips.join(", ")})` : "";
+  return {
+    decision_id,
+    chain: chainOut,
+    chosen: {
+      provider: "rules",
+      model: "rules",
+      harness: "direct",
+      transport: "rules",
+      wire: "none",
+      catalogRow: null,
+    },
+    envForSpawn: {},
+    spawnArgs: { modelFlag: null, maxTurns: 1, effort: null, maxBudgetUsd: null, agentsJson: null, bare: true },
+    lane,
+    cacheAffinityKey: null,
+    cache_ttl: "0",
+    estCostUSD: 0,
+    tried,
+    explain: `${req.task_class || "task"} → deterministic rules fallback${skipNote}`,
+    audit,
+  };
+}
+
+/** No-route decision when no model survives and fallback_to_anthropic is off. */
+function noRouteDecision(req, { now, opts, audit, tried, explainSkips, lane }) {
+  const decision_id = ulidish(now, opts && opts.rng);
+  audit.fallback_reason = "no_route";
+  return {
+    decision_id,
+    chain: [],
+    chosen: null,
+    envForSpawn: {},
+    spawnArgs: { modelFlag: null, maxTurns: 0, effort: null, maxBudgetUsd: null, agentsJson: null, bare: true },
+    lane,
+    cacheAffinityKey: null,
+    cache_ttl: "0",
+    estCostUSD: null,
+    tried,
+    explain: `${req.task_class || "task"} → NO ROUTE (no compatible candidate, fallback disabled); skipped ${(explainSkips || []).join(", ")}`,
+    audit,
+  };
+}
+
+/**
+ * Pick the best available Anthropic row from the catalog for a request:
+ * frontier (opus) for thinking/critical, else the default workhorse (sonnet),
+ * else any available anthropic row.
+ */
+function pickAnthropicRow(catalog, req) {
+  if (!catalog) return null;
+  const wantFrontier = req.needs_thinking || req.priority === "critical" || req.agent_role === "regulatory";
+  const order = wantFrontier
+    ? ["anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5"]
+    : ["anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-opus-4-8"];
+  for (const ref of order) {
+    const row = lookupModel(catalog, ref);
+    if (row && row.status === "available") {
+      // Context gate: if the request is too big for this row, try the next.
+      if (req.token_estimate != null && row.context_tokens != null && req.token_estimate > row.context_tokens) continue;
+      return row;
+    }
+  }
+  // Any available anthropic row.
+  const models = (catalog.models || (catalog.catalog && catalog.catalog.models)) || [];
+  return models.find((r) => r.provider === "anthropic" && r.status === "available") || null;
+}
+
+// ---------------------------------------------------------------------------
+// Explain string (mandatory, one line)
+// ---------------------------------------------------------------------------
+
+function buildExplain({ req, rule, row, harness, ladderNote, affinityNote, explainSkips, est }) {
+  const parts = [];
+  parts.push(`${req.task_class || req.source || "task"} →`);
+  const ruleLabel = rule.default
+    ? (rule.synthesized ? "synthesized-default" : "default")
+    : (rule.match ? `rule ${shortMatch(rule.match)}` : "rule");
+  parts.push(ruleLabel);
+  if (ladderNote) parts.push(`[${ladderNote}]`);
+  if (affinityNote) parts.push(`[${affinityNote}]`);
+  if (explainSkips && explainSkips.length) {
+    parts.push(`skipped ${explainSkips.join(", ")} →`);
+  } else {
+    parts.push("→");
+  }
+  parts.push(`${row.provider}/${row.id} (${harness})`);
+  if (est && est.usd != null) parts.push(`~$${est.usd}`);
+  return parts.join(" ");
+}
+
+function shortMatch(match) {
+  const keys = Object.keys(match);
+  if (!keys.length) return "{}";
+  const k = keys[0];
+  const v = match[k];
+  return `${k}=${Array.isArray(v) ? `[${v.length}]` : v}${keys.length > 1 ? "…" : ""}`;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog provenance tag (for the audit + doctor staleness ladder)
+// ---------------------------------------------------------------------------
+
+function catalogProvenanceTag(catalog) {
+  if (!catalog) return null;
+  const models = (catalog.models || (catalog.catalog && catalog.catalog.models)) || [];
+  let oldest = null;
+  let anyVolatile = false;
+  for (const r of models) {
+    const p = r.cost_provenance || {};
+    if (p.volatile) anyVolatile = true;
+    if (p.fetched && (oldest == null || p.fetched < oldest)) oldest = p.fetched;
+  }
+  return { oldestFetched: oldest, anyVolatile };
+}
+
+function safe(fn, dflt) {
+  try {
+    return fn();
+  } catch {
+    return dflt;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// validateRoutingConfig — strict v2 config validation (W10/W8/G14)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a v2 routing config against the catalog (+ optional overlay). Returns
+ * `{ errors:[], warnings:[] }`. NEVER throws. Surfaces:
+ *   - unknown match keys (capability typos)
+ *   - unknown aliases referenced in a chain
+ *   - chain refs not present in the catalog
+ *   - auth_env unset for a referenced (non-anthropic) provider (warning — the
+ *     key may live in .env which we don't load here)
+ *   - attempts to widen tool_reliability or add a provider via the overlay
+ *   - invalid harness / data_class / budget bands
+ *
+ * @param {object} config   normalised v2 routing config
+ * @param {object} [deps]
+ *   @param {object} [deps.catalog]  CatalogResult (or .catalog)
+ *   @param {object} [deps.overlay]
+ *   @param {object} [deps.env]      env for the auth_env presence check
+ * @returns {{errors:Array<{where:string,error:string}>, warnings:Array<{where:string,warning:string}>}}
+ */
+export function validateRoutingConfig(config, deps = {}) {
+  const errors = [];
+  const warnings = [];
+  const env = deps.env || process.env || {};
+  const catalog = deps.catalog && (deps.catalog.byRef ? deps.catalog : deps.catalog.catalog || deps.catalog);
+  const overlay = deps.overlay || null;
+
+  if (!config || typeof config !== "object") {
+    errors.push({ where: "config", error: "config is empty or not an object" });
+    return { errors, warnings };
+  }
+
+  // Only v2 configs are strict-validated here; v1 configs flow through the v1
+  // loader's own normalisation.
+  if (config.schema_version !== 2) {
+    return { errors, warnings };
+  }
+
+  const aliases = (config.aliases && typeof config.aliases === "object") ? config.aliases : {};
+
+  // Aliases must resolve to a catalog ref (or be a literal ref).
+  for (const [name, ref] of Object.entries(aliases)) {
+    if (typeof ref !== "string") {
+      errors.push({ where: `aliases.${name}`, error: "alias target must be a string ref" });
+      continue;
+    }
+    if (catalog && !lookupModel(catalog, ref)) {
+      errors.push({ where: `aliases.${name}`, error: `alias points at unknown catalog row "${ref}"` });
+    }
+  }
+
+  // backends data-class sanity.
+  for (const [name, b] of Object.entries(config.backends || {})) {
+    if (b && b.allowed_data_classes) {
+      if (!Array.isArray(b.allowed_data_classes)) {
+        errors.push({ where: `backends.${name}`, error: "allowed_data_classes must be an array" });
+      } else {
+        for (const c of b.allowed_data_classes) {
+          if (!DATA_CLASSES.has(c)) errors.push({ where: `backends.${name}`, error: `unknown data_class "${c}"` });
+        }
+      }
+    }
+  }
+
+  // routing_policy rules.
+  const rules = Array.isArray(config.routing_policy) ? config.routing_policy : [];
+  if (!rules.length) {
+    warnings.push({ where: "routing_policy", warning: "no routing rules — every request falls to the Anthropic safety net" });
+  }
+  let sawDefault = false;
+  rules.forEach((rule, i) => {
+    if (!rule || typeof rule !== "object") {
+      errors.push({ where: `routing_policy[${i}]`, error: "rule is not an object" });
+      return;
+    }
+    if (rule.default) sawDefault = true;
+    // match keys.
+    if (rule.match && typeof rule.match === "object") {
+      for (const key of Object.keys(rule.match)) {
+        if (!VALID_MATCH_KEYS.has(key)) {
+          errors.push({ where: `routing_policy[${i}].match`, error: `unknown match key "${key}" (typo?)` });
+        }
+      }
+    }
+    // harness.
+    if (rule.harness !== undefined && !HARNESSES.has(rule.harness)) {
+      errors.push({ where: `routing_policy[${i}]`, error: `unknown harness "${rule.harness}"` });
+    }
+    // minGrade.
+    if (rule.minGrade !== undefined && !GRADE_RANK[rule.minGrade]) {
+      errors.push({ where: `routing_policy[${i}]`, error: `unknown minGrade "${rule.minGrade}"` });
+    }
+    // chain refs.
+    const chain = rule.chain;
+    if (!rule.default && !Array.isArray(chain)) {
+      errors.push({ where: `routing_policy[${i}]`, error: "non-default rule has no chain[]" });
+    }
+    if (Array.isArray(chain)) {
+      for (const member of chain) {
+        if (member === "rules") continue;
+        if (typeof member !== "string") {
+          errors.push({ where: `routing_policy[${i}].chain`, error: "chain member must be a string alias/ref" });
+          continue;
+        }
+        const ref = Object.prototype.hasOwnProperty.call(aliases, member) ? aliases[member] : member;
+        if (!Object.prototype.hasOwnProperty.call(aliases, member) && !member.includes("/")) {
+          errors.push({ where: `routing_policy[${i}].chain`, error: `"${member}" is neither a known alias nor a "provider/model" ref` });
+          continue;
+        }
+        if (catalog && !lookupModel(catalog, ref)) {
+          errors.push({ where: `routing_policy[${i}].chain`, error: `chain ref "${ref}" not in catalog` });
+        } else if (catalog) {
+          // Credential presence (warning only — keys often live in .env, which
+          // doctor/the daemon load at spawn time). Skip Anthropic: a session
+          // candidate rides keychain OAuth, so a missing ANTHROPIC_API_KEY is
+          // not a routing blocker the way a missing third-party key is.
+          const row = lookupModel(catalog, ref);
+          if (
+            row && row.auth_env && row.provider !== "anthropic" &&
+            (typeof env[row.auth_env] !== "string" || env[row.auth_env].trim() === "")
+          ) {
+            warnings.push({ where: `routing_policy[${i}].chain`, warning: `${ref} needs ${row.auth_env} — unset in this env (key-absence enforcement will skip it)` });
+          }
+        }
+      }
+    }
+  });
+  if (rules.length && !sawDefault) {
+    warnings.push({ where: "routing_policy", warning: "no default rule — unmatched requests fall to the Anthropic safety net" });
+  }
+
+  // budget_ladder bands.
+  if (config.budget_ladder && typeof config.budget_ladder === "object") {
+    for (const band of Object.keys(config.budget_ladder)) {
+      if (!/^\d+$/.test(band)) {
+        warnings.push({ where: "budget_ladder", warning: `band key "${band}" is not numeric` });
+      }
+    }
+  }
+
+  // Overlay tighten-only widening attempts (provider add / grade raise) are
+  // caught by catalog.mjs at merge; surface a duplicate guard here against the
+  // CONFIG (an agent config cannot widen what the overlay tightened).
+  if (overlay && overlay.constraints) {
+    const allowed = Array.isArray(overlay.constraints.backends_allowed)
+      ? new Set(overlay.constraints.backends_allowed)
+      : null;
+    if (allowed) {
+      for (const name of Object.keys(config.backends || {})) {
+        if (!allowed.has(name) && name !== "anthropic") {
+          errors.push({ where: `backends.${name}`, error: `backend "${name}" is not in the org overlay's backends_allowed (tighten-only — cannot add)` });
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export const _internals = {
+  matchesRule,
+  pickRule,
+  resolveChainRefs,
+  applyBudgetLadder,
+  gateCandidate,
+  buildEnvForSpawn,
+  buildAllowedDataClasses,
+  resolveRowCredential,
+  ulidish,
+  pickAnthropicRow,
+  GRADE_RANK,
+  VALID_MATCH_KEYS,
+};
+
+export default { resolveChain, validateRoutingConfig };