@cohortapp/agent-sdk 2.3.0

package/lib/model-router/catalog.mjs

@@ -0,0 +1,925 @@
+/**
+ * lib/model-router/catalog.mjs — typed model catalog (v2).
+ *
+ * The catalog is the source of truth for every routable model: its identity,
+ * status, context/window limits, $/MTok cost, provenance, wire/compat flags,
+ * tool-reliability grade, and harness affordances. `resolveChain` (the resolve
+ * lane, built in parallel) consults the merged catalog to gate candidates;
+ * `ledger.estimateCost` prices a unit of work from a row's `cost` block.
+ *
+ * Authority merge (highest wins; the pricing cache updates `cost` fields ONLY —
+ * capabilities / compat / tool_reliability / harness are human-curated):
+ *
+ *   0  agent  config/model-routing.yaml  catalog_overrides:     (full row patch)
+ *   1  agent  config/models.local.yaml                          (full row patch)
+ *   2  org    policy overlay  catalog_patch  (TIGHTEN-ONLY:      disable rows /
+ *                                             lower grades; never add providers
+ *                                             nor raise tool_reliability)
+ *   3  state/model-router/pricing-cache.json  (COST FIELDS ONLY, provenance-stamped)
+ *   4  bundled lib/model-router/catalog/*.yaml (ships with @cohortapp/agent-sdk)
+ *
+ * Design constraints (CLAUDE.md / house style — see lib/cadence-bus.mjs,
+ * lib/rate-guard.mjs, lib/model-router.mjs):
+ *   - ESM .mjs, Node 20, near-zero-dep (js-yaml is the one parse dependency).
+ *   - Everything injectable so tests are hermetic: `opts.now`, `opts.bundledDir`,
+ *     `opts.catalogText` (map of provider -> raw YAML), `opts.overlay`,
+ *     `opts.agentConfig`, `opts.localConfig`, `opts.pricingCache` all bypass the FS.
+ *   - NEVER throws on the read path. `loadCatalog` always returns a typed
+ *     result `{ catalog, models, byRef, errors, warnings, sources, loadedAt }`;
+ *     a bad row is dropped with an entry in `errors`, never an exception. A
+ *     corrupt user file degrades to the bundled rows + a warning.
+ *   - mtime-aware hot reload: the process-level cache invalidates when any
+ *     contributing file's mtime advances; SIGHUP forces a full invalidate.
+ *
+ * @module lib/model-router/catalog
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { join, resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// js-yaml is a hard dependency of @cohortapp/agent-sdk (package.json), but we still
+// import it defensively so the read path can degrade rather than crash if the
+// dep tree is ever broken on a machine.
+let yamlParse = null;
+try {
+  const y = await import("js-yaml");
+  yamlParse = (text) => y.load(text);
+} catch {
+  yamlParse = null;
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Vocabulary (capability typo detection is part of strict validation)
+// ---------------------------------------------------------------------------
+
+const VALID_STATUS = new Set(["available", "preview", "deprecated", "disabled"]);
+const VALID_GRADES = new Set(["A", "B", "C"]);
+const GRADE_RANK = { A: 3, B: 2, C: 1 };
+
+const VALID_COMPAT_KEYS = new Set([
+  "cache_control",
+  "max_tokens_field",
+  "thinking_format",
+  "requires_reasoning_echo",
+  "rejects_duplicate_tool_names",
+  "omit_temperature",
+  "supports_prompt_cache_key",
+]);
+const VALID_CACHE_CONTROL = new Set(["anthropic", "implicit", "none"]);
+
+const VALID_HARNESS_KEYS = new Set(["session", "direct", "batch"]);
+
+const VALID_COST_KEYS = new Set([
+  "input",
+  "output",
+  "cache_read",
+  "cache_write",
+  "tiered",
+]);
+
+const COST_FIELDS = ["input", "output", "cache_read", "cache_write"];
+
+// Bundled providers we recognise. The authority-merge rule "never add providers"
+// is enforced for the overlay (tighten-only); agent config MAY introduce a new
+// provider via catalog_overrides (it is the highest authority and the agent owns
+// its own machine), but we surface a warning so a typo'd provider name is loud.
+const BUNDLED_PROVIDERS = new Set([
+  "anthropic",
+  "deepseek",
+  "moonshot",
+  "qwen",
+]);
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+function bundledDir(opts) {
+  if (opts && opts.bundledDir) return resolve(opts.bundledDir);
+  return join(__dirname, "catalog");
+}
+
+function agentRootOf(agentRoot, opts) {
+  return resolve(
+    (opts && opts.agentRoot) ||
+      agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
+function pricingCachePath(root) {
+  return join(root, "state", "model-router", "pricing-cache.json");
+}
+function agentConfigPath(root) {
+  return join(root, "config", "model-routing.yaml");
+}
+function localConfigPath(root) {
+  return join(root, "config", "models.local.yaml");
+}
+
+// ---------------------------------------------------------------------------
+// Safe file IO (never throws; records the failure to a collector)
+// ---------------------------------------------------------------------------
+
+function parseYamlSafe(text, label, errors) {
+  if (text == null) return null;
+  if (!yamlParse) {
+    errors.push({ source: label, error: "js-yaml not installed; cannot parse YAML" });
+    return null;
+  }
+  try {
+    return yamlParse(text);
+  } catch (err) {
+    errors.push({ source: label, error: `parse failed: ${err.message}` });
+    return null;
+  }
+}
+
+function readTextSafe(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function mtimeSafe(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Row normalisation + validation (strict: typos surface, never crash)
+// ---------------------------------------------------------------------------
+
+function normaliseCost(rawCost, errors, label) {
+  const cost = {
+    input: null,
+    output: null,
+    cache_read: null,
+    cache_write: null,
+    tiered: [],
+  };
+  if (rawCost == null) return cost;
+  if (typeof rawCost !== "object") {
+    errors.push({ source: label, error: "cost must be an object" });
+    return cost;
+  }
+  for (const k of Object.keys(rawCost)) {
+    if (!VALID_COST_KEYS.has(k)) {
+      errors.push({ source: label, error: `unknown cost field "${k}"` });
+    }
+  }
+  for (const f of COST_FIELDS) {
+    const v = rawCost[f];
+    if (v == null) {
+      cost[f] = null;
+    } else if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+      cost[f] = v;
+    } else {
+      errors.push({ source: label, error: `cost.${f} must be a non-negative number or null` });
+      cost[f] = null;
+    }
+  }
+  if (Array.isArray(rawCost.tiered)) {
+    cost.tiered = rawCost.tiered.map((t) => ({ ...t }));
+  } else if (rawCost.tiered != null) {
+    errors.push({ source: label, error: "cost.tiered must be an array" });
+  }
+  return cost;
+}
+
+function normaliseCompat(rawCompat, errors, label) {
+  const compat = {};
+  if (rawCompat == null) return compat;
+  if (typeof rawCompat !== "object") {
+    errors.push({ source: label, error: "compat must be an object" });
+    return compat;
+  }
+  for (const [k, v] of Object.entries(rawCompat)) {
+    if (!VALID_COMPAT_KEYS.has(k)) {
+      errors.push({ source: label, error: `unknown compat flag "${k}" (capability typo?)` });
+      continue;
+    }
+    compat[k] = v;
+  }
+  if (compat.cache_control != null && !VALID_CACHE_CONTROL.has(compat.cache_control)) {
+    errors.push({
+      source: label,
+      error: `compat.cache_control "${compat.cache_control}" not in {anthropic,implicit,none}`,
+    });
+  }
+  return compat;
+}
+
+function normaliseHarness(rawHarness, errors, label) {
+  const harness = { session: false, direct: false, batch: false };
+  if (rawHarness == null) return harness;
+  if (typeof rawHarness !== "object") {
+    errors.push({ source: label, error: "harness must be an object" });
+    return harness;
+  }
+  for (const [k, v] of Object.entries(rawHarness)) {
+    if (!VALID_HARNESS_KEYS.has(k)) {
+      errors.push({ source: label, error: `unknown harness key "${k}"` });
+      continue;
+    }
+    harness[k] = v === true;
+  }
+  return harness;
+}
+
+function normaliseProvenance(rawProv) {
+  const p = rawProv && typeof rawProv === "object" ? rawProv : {};
+  return {
+    source: typeof p.source === "string" ? p.source : "unknown",
+    fetched: typeof p.fetched === "string" ? p.fetched : null,
+    volatile: p.volatile === true,
+  };
+}
+
+/**
+ * Validate + normalise one model row. Returns `{ row, ok }`. On a fatal
+ * problem (no id, bad status) `ok:false` and the row is dropped from the
+ * catalog; non-fatal issues are accumulated in `errors` but the row survives.
+ */
+function normaliseRow(provider, rawRow, errors) {
+  const id = rawRow && typeof rawRow.id === "string" ? rawRow.id.trim() : "";
+  const label = `${provider}/${id || "<no-id>"}`;
+  if (!id) {
+    errors.push({ source: provider, error: "model row missing string `id` — dropped" });
+    return { ok: false };
+  }
+  let status = rawRow.status;
+  if (status == null) status = "available";
+  if (!VALID_STATUS.has(status)) {
+    errors.push({
+      source: label,
+      error: `status "${status}" not in {available,preview,deprecated,disabled} — dropped`,
+    });
+    return { ok: false };
+  }
+
+  const tool_reliability = rawRow.tool_reliability;
+  if (tool_reliability != null && !VALID_GRADES.has(tool_reliability)) {
+    errors.push({ source: label, error: `tool_reliability "${tool_reliability}" not in {A,B,C}` });
+  }
+
+  const row = {
+    provider,
+    ref: `${provider}/${id}`,
+    id,
+    status,
+    replaced_by: rawRow.replaced_by ?? null,
+    context_window: numOrNull(rawRow.context_window),
+    context_tokens: numOrNull(rawRow.context_tokens),
+    max_tokens: numOrNull(rawRow.max_tokens),
+    cost: normaliseCost(rawRow.cost, errors, label),
+    cost_provenance: normaliseProvenance(rawRow.cost_provenance),
+    compat: normaliseCompat(rawRow.compat, errors, label),
+    tool_reliability: VALID_GRADES.has(tool_reliability) ? tool_reliability : null,
+    harness: normaliseHarness(rawRow.harness, errors, label),
+    quality: rawRow.quality && typeof rawRow.quality === "object" ? { ...rawRow.quality } : {},
+  };
+  return { ok: true, row };
+}
+
+function numOrNull(v) {
+  if (v == null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+// ---------------------------------------------------------------------------
+// Provider-file parsing → array of normalised rows
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single provider catalog document (the shape of a bundled YAML file)
+ * into normalised rows. Returns `{ provider, auth_env, endpoints,
+ * data_residency, rows: Map<id,row> }` or null on a fatal structural problem.
+ */
+function parseProviderDoc(doc, label, errors) {
+  if (!doc || typeof doc !== "object") {
+    errors.push({ source: label, error: "catalog document is empty or not an object" });
+    return null;
+  }
+  const provider = typeof doc.provider === "string" ? doc.provider.trim() : "";
+  if (!provider) {
+    errors.push({ source: label, error: "catalog document missing string `provider`" });
+    return null;
+  }
+  const rows = new Map();
+  const models = Array.isArray(doc.models) ? doc.models : [];
+  if (!Array.isArray(doc.models)) {
+    errors.push({ source: label, error: "catalog `models` is not an array" });
+  }
+  for (const rawRow of models) {
+    const { ok, row } = normaliseRow(provider, rawRow, errors);
+    if (!ok) continue;
+    // Provider-level metadata is hoisted onto each row so resolveChain has it
+    // in one place (rows carry their own auth_env/endpoints/data_residency).
+    row.auth_env = typeof doc.auth_env === "string" ? doc.auth_env : null;
+    row.endpoints = doc.endpoints && typeof doc.endpoints === "object" ? { ...doc.endpoints } : {};
+    row.data_residency =
+      typeof doc.data_residency === "string" ? doc.data_residency : null;
+    rows.set(row.id, row);
+  }
+  return {
+    provider,
+    auth_env: typeof doc.auth_env === "string" ? doc.auth_env : null,
+    endpoints: doc.endpoints && typeof doc.endpoints === "object" ? { ...doc.endpoints } : {},
+    data_residency: typeof doc.data_residency === "string" ? doc.data_residency : null,
+    rows,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Source gathering (each returns provider docs + records its file mtime)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} CatalogSource
+ * @property {string} layer  "bundled"|"pricing-cache"|"overlay"|"local"|"agent"
+ * @property {string} [path] file path if FS-backed
+ * @property {number} [mtime]
+ * @property {Map<string,object>} providers  provider -> parsed provider doc
+ */
+
+function gatherBundled(opts, errors, mtimes) {
+  const providers = new Map();
+  // Injected text map bypasses the FS entirely (hermetic tests).
+  if (opts && opts.catalogText && typeof opts.catalogText === "object") {
+    for (const [name, text] of Object.entries(opts.catalogText)) {
+      const doc = parseYamlSafe(text, `bundled:${name}`, errors);
+      const parsed = parseProviderDoc(doc, `bundled:${name}`, errors);
+      if (parsed) providers.set(parsed.provider, parsed);
+    }
+    return { layer: "bundled", providers };
+  }
+  const dir = bundledDir(opts);
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+  } catch (err) {
+    errors.push({ source: "bundled", error: `cannot read catalog dir ${dir}: ${err.message}` });
+    return { layer: "bundled", providers };
+  }
+  for (const f of files.sort()) {
+    const path = join(dir, f);
+    const text = readTextSafe(path);
+    if (text == null) continue;
+    mtimes.push(mtimeSafe(path));
+    const doc = parseYamlSafe(text, basename(f), errors);
+    const parsed = parseProviderDoc(doc, basename(f), errors);
+    if (parsed) providers.set(parsed.provider, parsed);
+  }
+  return { layer: "bundled", providers, path: dir };
+}
+
+/**
+ * Read the pricing cache (COST FIELDS ONLY). Shape:
+ *   { "<provider>/<id>": { input, output, cache_read, cache_write, tiered?,
+ *                          provenance:{source,fetched,volatile} }, ... }
+ * Injected via opts.pricingCache (object) or read from
+ * state/model-router/pricing-cache.json.
+ */
+function gatherPricingCache(root, opts, errors, mtimes) {
+  let obj = null;
+  if (opts && opts.pricingCache !== undefined) {
+    obj = opts.pricingCache;
+  } else {
+    const path = pricingCachePath(root);
+    const text = readTextSafe(path);
+    if (text != null) {
+      mtimes.push(mtimeSafe(path));
+      try {
+        obj = JSON.parse(text);
+      } catch (err) {
+        errors.push({ source: "pricing-cache", error: `parse failed: ${err.message}` });
+        return null;
+      }
+    }
+  }
+  if (!obj || typeof obj !== "object") return null;
+  // The cache may wrap entries under a top-level key; accept both `{models:{}}`
+  // and a flat `{ "<ref>": {...} }`.
+  const entries = obj.models && typeof obj.models === "object" ? obj.models : obj;
+  return { layer: "pricing-cache", entries };
+}
+
+function gatherUserConfigPatch(root, opts, key, fileFn, layer, errors, mtimes) {
+  // key = "agentConfig" | "localConfig"; produces a list of catalog_overrides rows.
+  let doc = null;
+  if (opts && opts[key] !== undefined) {
+    doc = opts[key];
+  } else {
+    const path = fileFn(root);
+    const text = readTextSafe(path);
+    if (text != null) {
+      mtimes.push(mtimeSafe(path));
+      doc = parseYamlSafe(text, layer, errors);
+    }
+  }
+  if (!doc || typeof doc !== "object") return null;
+  // Agent config carries the patch under `catalog_overrides`; models.local.yaml
+  // may either be a bare provider doc OR also use `catalog_overrides`.
+  const patch =
+    doc.catalog_overrides !== undefined ? doc.catalog_overrides : doc.providers ?? doc;
+  return { layer, patch };
+}
+
+// ---------------------------------------------------------------------------
+// Merge engine
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply a cost-only patch from the pricing cache onto the working byRef map.
+ * Capabilities/compat/grade are NEVER touched here.
+ */
+function applyPricingCache(byRef, cacheLayer, warnings) {
+  if (!cacheLayer || !cacheLayer.entries) return;
+  for (const [ref, patch] of Object.entries(cacheLayer.entries)) {
+    const row = byRef.get(ref);
+    if (!row) {
+      warnings.push({ source: "pricing-cache", warning: `price for unknown row "${ref}" ignored` });
+      continue;
+    }
+    if (!patch || typeof patch !== "object") continue;
+    for (const f of COST_FIELDS) {
+      if (patch[f] === undefined) continue;
+      const v = patch[f];
+      if (v == null) {
+        row.cost[f] = null;
+      } else if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+        row.cost[f] = v;
+      }
+    }
+    if (Array.isArray(patch.tiered)) row.cost.tiered = patch.tiered.map((t) => ({ ...t }));
+    if (patch.provenance && typeof patch.provenance === "object") {
+      row.cost_provenance = normaliseProvenance(patch.provenance);
+    } else {
+      // A price arrived from the cache; stamp provenance so staleness checks see it.
+      row.cost_provenance = {
+        ...row.cost_provenance,
+        source: "pricing-cache",
+      };
+    }
+  }
+}
+
+/**
+ * Apply the TIGHTEN-ONLY org overlay catalog_patch. May:
+ *   - set status to a more-restrictive value (e.g. -> disabled)
+ *   - LOWER tool_reliability (A->B->C)
+ * May NOT:
+ *   - add a provider/model the bundled+user layers don't define
+ *   - RAISE tool_reliability
+ *   - widen status back to available from disabled (tighten-only)
+ * Violations are recorded as errors and the offending field is left untouched.
+ */
+function applyOverlayPatch(byRef, overlay, errors) {
+  if (!overlay) return;
+  const patch = Array.isArray(overlay.catalog_patch)
+    ? overlay.catalog_patch
+    : Array.isArray(overlay)
+      ? overlay
+      : [];
+  for (const entry of patch) {
+    if (!entry || typeof entry !== "object" || typeof entry.ref !== "string") continue;
+    const row = byRef.get(entry.ref);
+    if (!row) {
+      errors.push({
+        source: "overlay",
+        error: `overlay patch references unknown row "${entry.ref}" — cannot add providers (tighten-only)`,
+      });
+      continue;
+    }
+    if (entry.status !== undefined) {
+      if (!VALID_STATUS.has(entry.status)) {
+        errors.push({ source: "overlay", error: `overlay status "${entry.status}" invalid for ${entry.ref}` });
+      } else if (entry.status === "disabled" || entry.status === "deprecated") {
+        row.status = entry.status; // tightening is allowed
+      } else {
+        errors.push({
+          source: "overlay",
+          error: `overlay cannot widen status of ${entry.ref} to "${entry.status}" (tighten-only)`,
+        });
+      }
+    }
+    if (entry.tool_reliability !== undefined) {
+      if (!VALID_GRADES.has(entry.tool_reliability)) {
+        errors.push({ source: "overlay", error: `overlay grade "${entry.tool_reliability}" invalid for ${entry.ref}` });
+      } else {
+        const cur = row.tool_reliability ? GRADE_RANK[row.tool_reliability] : 0;
+        const next = GRADE_RANK[entry.tool_reliability];
+        if (next <= cur) {
+          row.tool_reliability = entry.tool_reliability; // lowering allowed
+        } else {
+          errors.push({
+            source: "overlay",
+            error: `overlay cannot raise tool_reliability of ${entry.ref} from ${row.tool_reliability} to ${entry.tool_reliability} (tighten-only)`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Apply a user-config patch (agent catalog_overrides / models.local.yaml).
+ * These are the HIGHEST authority and the agent owns its own machine, so a full
+ * row patch is permitted (capabilities, compat, cost, grade). A patch that adds
+ * an entirely new provider is allowed but warned (typo guard).
+ */
+function applyUserPatch(byRef, providersByName, layer, patch, errors, warnings) {
+  if (!patch) return;
+  // Patch may be: an array of partial rows ({ref, ...overrides}),
+  // OR a map provider -> provider-doc, OR a single provider doc.
+  if (Array.isArray(patch)) {
+    for (const entry of patch) {
+      if (!entry || typeof entry !== "object") continue;
+      const ref = typeof entry.ref === "string" ? entry.ref : null;
+      if (!ref) {
+        errors.push({ source: layer, error: "catalog_overrides entry missing `ref`" });
+        continue;
+      }
+      mergePartialRow(byRef, ref, entry, layer, errors, warnings);
+    }
+    return;
+  }
+  if (typeof patch === "object") {
+    // Provider-doc form (bare or under provider keys).
+    const docs =
+      patch.provider !== undefined
+        ? [patch]
+        : Object.values(patch).filter((v) => v && typeof v === "object" && v.provider);
+    for (const doc of docs) {
+      const parsed = parseProviderDoc(doc, layer, errors);
+      if (!parsed) continue;
+      if (!BUNDLED_PROVIDERS.has(parsed.provider) && !providersByName.has(parsed.provider)) {
+        warnings.push({
+          source: layer,
+          warning: `introduces non-bundled provider "${parsed.provider}" (typo? deliberate?)`,
+        });
+      }
+      providersByName.set(parsed.provider, parsed);
+      for (const row of parsed.rows.values()) byRef.set(row.ref, row);
+    }
+  }
+}
+
+function mergePartialRow(byRef, ref, entry, layer, errors, warnings) {
+  const existing = byRef.get(ref);
+  if (!existing) {
+    // Allowed (agent owns the machine) but loud — a typo'd ref would otherwise
+    // silently create a phantom row.
+    warnings.push({ source: layer, warning: `catalog_overrides creates new row "${ref}"` });
+    const [provider, ...idParts] = ref.split("/");
+    const id = idParts.join("/");
+    const { ok, row } = normaliseRow(provider, { ...entry, id }, errors);
+    if (ok) {
+      row.auth_env = entry.auth_env ?? null;
+      row.endpoints = entry.endpoints ?? {};
+      row.data_residency = entry.data_residency ?? null;
+      byRef.set(ref, row);
+    }
+    return;
+  }
+  // Field-wise override on the existing row.
+  if (entry.status !== undefined) {
+    if (VALID_STATUS.has(entry.status)) existing.status = entry.status;
+    else errors.push({ source: layer, error: `override status "${entry.status}" invalid for ${ref}` });
+  }
+  if (entry.tool_reliability !== undefined) {
+    if (VALID_GRADES.has(entry.tool_reliability)) existing.tool_reliability = entry.tool_reliability;
+    else errors.push({ source: layer, error: `override grade "${entry.tool_reliability}" invalid for ${ref}` });
+  }
+  for (const f of ["context_window", "context_tokens", "max_tokens", "replaced_by"]) {
+    if (entry[f] !== undefined) existing[f] = f === "replaced_by" ? entry[f] : numOrNull(entry[f]);
+  }
+  if (entry.cost !== undefined) {
+    const c = normaliseCost(entry.cost, errors, `${layer}:${ref}`);
+    for (const f of COST_FIELDS) if (entry.cost[f] !== undefined) existing.cost[f] = c[f];
+    if (Array.isArray(entry.cost.tiered)) existing.cost.tiered = c.tiered;
+  }
+  if (entry.compat !== undefined) {
+    Object.assign(existing.compat, normaliseCompat(entry.compat, errors, `${layer}:${ref}`));
+  }
+  if (entry.harness !== undefined) {
+    Object.assign(existing.harness, normaliseHarness(entry.harness, errors, `${layer}:${ref}`));
+  }
+  if (entry.cost_provenance !== undefined) {
+    existing.cost_provenance = normaliseProvenance(entry.cost_provenance);
+  }
+  if (entry.auth_env !== undefined) existing.auth_env = entry.auth_env;
+  if (entry.endpoints !== undefined) existing.endpoints = { ...entry.endpoints };
+  if (entry.data_residency !== undefined) existing.data_residency = entry.data_residency;
+  if (entry.quality !== undefined && typeof entry.quality === "object") {
+    Object.assign(existing.quality, entry.quality);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public: loadCatalog
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Catalog
+ * @property {object[]} models                 normalised rows (array, stable order)
+ * @property {Map<string,object>} byRef        "provider/id" -> row
+ * @property {Map<string,object>} providers    provider -> { auth_env, endpoints, data_residency }
+ */
+
+/**
+ * @typedef {Object} CatalogResult
+ * @property {Catalog} catalog
+ * @property {object[]} models                 convenience: catalog.models
+ * @property {Map<string,object>} byRef        convenience: catalog.byRef
+ * @property {{source:string,error:string}[]} errors
+ * @property {{source:string,warning:string}[]} warnings
+ * @property {string[]} sources                layers that contributed
+ * @property {number} loadedAt                 epoch ms
+ */
+
+/**
+ * Load + authority-merge the full catalog. NEVER throws.
+ *
+ * @param {string} [agentRoot]
+ * @param {object} [opts]
+ *   @param {string}  [opts.agentRoot]
+ *   @param {string}  [opts.bundledDir]      override bundled-rows dir
+ *   @param {object}  [opts.catalogText]     { provider: rawYaml } — bypass FS for bundled rows
+ *   @param {object}  [opts.pricingCache]    cost-only patch object (bypass FS)
+ *   @param {object}  [opts.overlay]         signed org overlay (already-verified object)
+ *   @param {object}  [opts.agentConfig]     config/model-routing.yaml doc (bypass FS)
+ *   @param {object}  [opts.localConfig]     config/models.local.yaml doc (bypass FS)
+ *   @param {()=>number} [opts.now]
+ * @returns {CatalogResult}
+ */
+export function loadCatalog(agentRoot, opts = {}) {
+  const now = (opts.now || Date.now)();
+  const root = agentRootOf(agentRoot, opts);
+  const errors = [];
+  const warnings = [];
+  const mtimes = [];
+  const sources = [];
+
+  // Layer 4: bundled rows (the floor).
+  const bundled = gatherBundled(opts, errors, mtimes);
+  sources.push("bundled");
+  const byRef = new Map();
+  const providersByName = new Map();
+  for (const parsed of bundled.providers.values()) {
+    providersByName.set(parsed.provider, parsed);
+    for (const row of parsed.rows.values()) byRef.set(row.ref, row);
+  }
+
+  // Layer 3: pricing cache (COST ONLY).
+  const pricing = gatherPricingCache(root, opts, errors, mtimes);
+  if (pricing) {
+    applyPricingCache(byRef, pricing, warnings);
+    sources.push("pricing-cache");
+  }
+
+  // Layer 2: org overlay catalog_patch (TIGHTEN-ONLY).
+  const overlay = opts.overlay ?? null;
+  if (overlay) {
+    applyOverlayPatch(byRef, overlay, errors);
+    sources.push("overlay");
+  }
+
+  // Layer 1: config/models.local.yaml.
+  const local = gatherUserConfigPatch(root, opts, "localConfig", localConfigPath, "models.local.yaml", errors, mtimes);
+  if (local) {
+    applyUserPatch(byRef, providersByName, "models.local.yaml", local.patch, errors, warnings);
+    sources.push("models.local.yaml");
+  }
+
+  // Layer 0: agent config/model-routing.yaml catalog_overrides (HIGHEST).
+  const agent = gatherUserConfigPatch(root, opts, "agentConfig", agentConfigPath, "model-routing.yaml", errors, mtimes);
+  if (agent) {
+    applyUserPatch(byRef, providersByName, "model-routing.yaml", agent.patch, errors, warnings);
+    sources.push("model-routing.yaml");
+  }
+
+  // Re-validate cross-cutting invariants after merge (e.g. price sanity).
+  for (const row of byRef.values()) {
+    if (row.cost.input != null && row.cost.output != null && row.cost.input > row.cost.output * 5) {
+      warnings.push({
+        source: row.ref,
+        warning: `input price (${row.cost.input}) > 5x output (${row.cost.output}) — suspicious`,
+      });
+    }
+    if (
+      row.context_tokens != null &&
+      row.context_window != null &&
+      row.context_tokens > row.context_window
+    ) {
+      warnings.push({
+        source: row.ref,
+        warning: `context_tokens (${row.context_tokens}) exceeds context_window (${row.context_window})`,
+      });
+    }
+  }
+
+  const models = [...byRef.values()];
+  const providers = new Map();
+  for (const [name, doc] of providersByName) {
+    providers.set(name, {
+      provider: name,
+      auth_env: doc.auth_env,
+      endpoints: doc.endpoints,
+      data_residency: doc.data_residency,
+    });
+  }
+
+  const catalog = { models, byRef, providers };
+  return {
+    catalog,
+    models,
+    byRef,
+    errors,
+    warnings,
+    sources,
+    loadedAt: now,
+    _mtimeKey: maxMtime(mtimes),
+  };
+}
+
+function maxMtime(mtimes) {
+  let m = 0;
+  for (const t of mtimes) if (t > m) m = t;
+  return m;
+}
+
+// ---------------------------------------------------------------------------
+// Public: lookupModel / listModels
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a "provider/model" ref against a loaded catalog. NEVER throws.
+ *
+ * @param {Catalog|CatalogResult} catalog  result of loadCatalog (or its .catalog)
+ * @param {string} ref  "provider/model-id"
+ * @returns {object|null} the normalised row, or null if absent
+ */
+export function lookupModel(catalog, ref) {
+  const byRef = catalog && (catalog.byRef || (catalog.catalog && catalog.catalog.byRef));
+  if (!byRef || typeof ref !== "string") return null;
+  return byRef.get(ref) || null;
+}
+
+/**
+ * List catalog rows matching an optional filter. NEVER throws.
+ *
+ * @param {Catalog|CatalogResult} catalog
+ * @param {object} [filter]
+ *   @param {string}  [filter.provider]
+ *   @param {string|string[]} [filter.status]          default: any
+ *   @param {"A"|"B"|"C"} [filter.minGrade]            tool_reliability >= this
+ *   @param {"session"|"direct"|"batch"} [filter.harness]  harness[x] === true
+ *   @param {boolean} [filter.available]               shorthand for status:"available"
+ * @returns {object[]}
+ */
+export function listModels(catalog, filter = {}) {
+  const models =
+    (catalog && (catalog.models || (catalog.catalog && catalog.catalog.models))) || [];
+  const wantStatus =
+    filter.available === true
+      ? new Set(["available"])
+      : filter.status
+        ? new Set(Array.isArray(filter.status) ? filter.status : [filter.status])
+        : null;
+  const minRank = filter.minGrade ? GRADE_RANK[filter.minGrade] || 0 : 0;
+  return models.filter((row) => {
+    if (filter.provider && row.provider !== filter.provider) return false;
+    if (wantStatus && !wantStatus.has(row.status)) return false;
+    if (minRank > 0) {
+      const r = row.tool_reliability ? GRADE_RANK[row.tool_reliability] : 0;
+      if (r < minRank) return false;
+    }
+    if (filter.harness && row.harness[filter.harness] !== true) return false;
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Hot reload: mtime-aware process cache + SIGHUP invalidate
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, {result: CatalogResult, signature: string}>} */
+const _cache = new Map();
+let _sighupGeneration = 0;
+let _sighupArmed = false;
+
+function armSighup() {
+  if (_sighupArmed) return;
+  _sighupArmed = true;
+  try {
+    process.on("SIGHUP", () => {
+      _sighupGeneration += 1;
+      _cache.clear();
+    });
+  } catch {
+    /* environments without signal support (e.g. some test runners) just skip */
+  }
+}
+
+/**
+ * Compute the mtime signature of every file that could contribute to the
+ * catalog for `root`. Cheap (stat only). Used to decide whether the cached
+ * load is still valid.
+ */
+function mtimeSignature(root, opts) {
+  const parts = [`gen:${_sighupGeneration}`];
+  // Bundled dir: stat each file (its set rarely changes, but a price edit during
+  // dev should hot-reload).
+  if (opts.catalogText) {
+    parts.push("injected-bundled");
+  } else {
+    const dir = bundledDir(opts);
+    try {
+      for (const f of readdirSync(dir).sort()) {
+        if (!/\.ya?ml$/.test(f)) continue;
+        parts.push(`b:${f}:${mtimeSafe(join(dir, f))}`);
+      }
+    } catch {
+      parts.push("b:err");
+    }
+  }
+  for (const [tag, fn, injected] of [
+    ["price", pricingCachePath, opts.pricingCache !== undefined],
+    ["local", localConfigPath, opts.localConfig !== undefined],
+    ["agent", agentConfigPath, opts.agentConfig !== undefined],
+  ]) {
+    if (injected) parts.push(`${tag}:injected`);
+    else parts.push(`${tag}:${mtimeSafe(fn(root))}`);
+  }
+  // Overlay is passed by value (already verified); fold its version in.
+  if (opts.overlay) parts.push(`ovl:${opts.overlay.version || "?"}`);
+  return parts.join("|");
+}
+
+/**
+ * Cached, mtime-aware catalog load. Returns the same `CatalogResult` shape as
+ * `loadCatalog`, but reuses a previously parsed result when no contributing
+ * file's mtime has advanced (and no SIGHUP has fired). NEVER throws.
+ *
+ * Note: when any of the bypass-the-FS injection opts are supplied (catalogText,
+ * pricingCache, overlay, agentConfig, localConfig) the signature folds them in
+ * by identity/version so hermetic tests still behave; pass a unique `cacheKey`
+ * to force isolation between test cases.
+ *
+ * @param {string} [agentRoot]
+ * @param {object} [opts]  same as loadCatalog, plus:
+ *   @param {string} [opts.cacheKey]  override the cache bucket (test isolation)
+ *   @param {boolean} [opts.force]    bypass the cache for this call
+ * @returns {CatalogResult}
+ */
+export function loadCatalogCached(agentRoot, opts = {}) {
+  armSighup();
+  const root = agentRootOf(agentRoot, opts);
+  const bucket = opts.cacheKey || root;
+  const signature = mtimeSignature(root, opts);
+  if (!opts.force) {
+    const hit = _cache.get(bucket);
+    if (hit && hit.signature === signature) return hit.result;
+  }
+  const result = loadCatalog(agentRoot, opts);
+  _cache.set(bucket, { result, signature });
+  return result;
+}
+
+/** Force-invalidate the catalog cache (all buckets, or one). */
+export function invalidateCatalogCache(bucket) {
+  if (bucket) _cache.delete(bucket);
+  else _cache.clear();
+}
+
+export const _internals = {
+  parseProviderDoc,
+  normaliseRow,
+  applyPricingCache,
+  applyOverlayPatch,
+  applyUserPatch,
+  GRADE_RANK,
+  VALID_STATUS,
+  mtimeSignature,
+};
+
+export default { loadCatalog, loadCatalogCached, invalidateCatalogCache, lookupModel, listModels };