lynkr 9.14.2 → 9.14.7

package/src/routing/capabilities.js

@@ -0,0 +1,88 @@
+/**
+ * Capability requirement vector (item 1: HyDRA port, phase 1).
+ *
+ * Maps the existing 15-dim weighted analysis (complexity-analyzer.js
+ * calculateWeightedScore dimensions, each 0-100) onto 4 independent
+ * capability heads in [0,1]:
+ *
+ *   - reasoning : multi-step / planning / tradeoff analysis load
+ *   - codegen   : code-writing demand (generation + technical + tool depth)
+ *   - debugging : diagnostic load (analysis + technical + domain breadth)
+ *   - tool_use  : tool-orchestration load (count, complexity, chaining, history)
+ *
+ * Deliberately decoupled from the model catalog: this module never names a
+ * provider/model/tier. Model capabilities live in
+ * config/model-capabilities.json and matching lives in shortfall.js, so a
+ * catalog change is a config edit with zero retraining.
+ *
+ * Deliberately excludes risk/agentic overrides: risk-high forces REASONING
+ * and AUTONOMOUS sets a REASONING floor upstream (routing/index.js). Those
+ * stay as deterministic post-passes (like HyDRA's health veto), not as
+ * learned heads — keeping this predictor language- and catalog-invariant.
+ * The agentic flag only floors tool_use (agentic work always needs tools),
+ * it never lowers a requirement.
+ *
+ * Pure function, no I/O. Never throws: bad input yields the neutral prior
+ * (all 0.2 ≈ trivial) so callers fail open to cheap routing.
+ */
+
+const HEADS = ['reasoning', 'codegen', 'debugging', 'tool_use'];
+
+function _clamp01(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+
+function _dim01(dimensions, name) {
+  const v = Number(dimensions?.[name]);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(1, v / 100));
+}
+
+/**
+ * @param {object} args
+ * @param {object} [args.dimensions] — calculateWeightedScore dimensions (0-100 each)
+ * @param {object} [args.agenticResult] — { isAgentic } (floors tool_use only)
+ * @returns {{ reasoning:number, codegen:number, debugging:number, tool_use:number }}
+ */
+function buildRequirementVector({ dimensions = {}, agenticResult = null } = {}) {
+  try {
+    const d = (name) => _dim01(dimensions, name);
+
+    let reasoning = d('multiStepReasoning') * 0.4
+      + d('analysisDepth') * 0.4
+      + d('promptComplexity') * 0.2;
+
+    let codegen = d('codeGeneration') * 0.5
+      + d('technicalDepth') * 0.3
+      + d('toolComplexity') * 0.2;
+
+    let debugging = d('analysisDepth') * 0.3
+      + d('technicalDepth') * 0.2
+      + d('domainSpecificity') * 0.3
+      + d('promptComplexity') * 0.2;
+
+    let toolUse = d('toolCount') * 0.3
+      + d('toolComplexity') * 0.3
+      + d('toolChainPotential') * 0.2
+      + d('priorToolUsage') * 0.2;
+
+    // Agentic work always needs tool orchestration — floor only, never lower.
+    if (agenticResult?.isAgentic) {
+      toolUse = Math.max(toolUse, 0.6);
+    }
+
+    const round3 = (v) => Math.round(_clamp01(v) * 1000) / 1000;
+    return {
+      reasoning: round3(reasoning),
+      codegen: round3(codegen),
+      debugging: round3(debugging),
+      tool_use: round3(toolUse),
+    };
+  } catch {
+    return { reasoning: 0.2, codegen: 0.2, debugging: 0.2, tool_use: 0.2 };
+  }
+}
+
+module.exports = { HEADS, buildRequirementVector };

package/src/routing/capability-seeds/benchmarks-dir.js

@@ -0,0 +1,58 @@
+/**
+ * Drop-in benchmark directory loader: data/capability-benchmarks/*.json.
+ *
+ * For leaderboards with no stable raw endpoint (TerminalBench, LiveCodeBench
+ * snapshots, Artificial Analysis exports): download the export once, drop it
+ * here, and the seed script picks it up. Format per file:
+ *
+ *   { "source": "terminalbench-2.1", "scale": "percent",
+ *     "results": { "Kimi K2.5": 42.1, "GPT 5.2": 38.0 } }
+ *
+ * scale "percent" (0-100) or "fraction" (0-1). Model names are cleaned with
+ * the SWE-bench cleaner and family-mapped in normalize.js; unmapped names
+ * surface for review instead of being silently seeded. Directory absent or
+ * empty → { files: [] } (not an error).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { cleanName } = require('./swebench');
+
+const BENCHMARKS_DIR = path.join(__dirname, '../../../data/capability-benchmarks');
+
+function loadBenchmarksDir(dir = BENCHMARKS_DIR) {
+  try {
+    if (!fs.existsSync(dir)) return { files: [] };
+    const files = [];
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+        if (!raw || typeof raw !== 'object' || !raw.results || typeof raw.results !== 'object') {
+          files.push({ file: name, status: 'skipped', reason: 'missing results object' });
+          continue;
+        }
+        const entries = [];
+        for (const [modelName, score] of Object.entries(raw.results)) {
+          const cleaned = cleanName(modelName);
+          const s = Number(score);
+          if (cleaned && Number.isFinite(s)) entries.push({ name: cleaned, score: s });
+        }
+        files.push({
+          file: name,
+          status: 'ok',
+          source: String(raw.source || name.replace(/\.json$/, '')),
+          scale: raw.scale === 'fraction' ? 'fraction' : 'percent',
+          entries,
+        });
+      } catch (err) {
+        files.push({ file: name, status: 'skipped', reason: err.message });
+      }
+    }
+    return { files };
+  } catch (err) {
+    return { files: [], error: err.message };
+  }
+}
+
+module.exports = { loadBenchmarksDir, BENCHMARKS_DIR };

package/src/routing/capability-seeds/family-heuristics.js

@@ -0,0 +1,77 @@
+/**
+ * Family-ladder heuristics: zero-network capability estimates from model
+ * family names. Vendors ship in ladders (haiku<sonnet<opus, mini<full,
+ * flash<pro, air<max, 7b<32b<70b), so an unknown model usually reveals its
+ * rung by name. Deliberately pessimistic: heuristics never claim frontier
+ * (cap 0.85) — exact seeds do that. Returns null when nothing matches, so
+ * the resolver falls through to tier-slot caps (today's behavior).
+ *
+ * Tilts: coder-named models get +codegen, reasoner-named +reasoning.
+ * Everything rounded to 3 decimals. Pure, no I/O, never throws.
+ */
+
+const CAP = 0.85;
+const FLOOR = 0.15;
+
+// Ordered: first match wins. Frontier names before size rules (a bare
+// "deepseek-r1" carries no size suffix but is strong).
+const LADDER = [
+  // Frontier (0.80)
+  { re: /^(gpt-5(\.|$)|o1(-pro)?$|o3($|-)|claude-opus-4|gemini-2\.5-pro|deepseek-r1$|deepseek-reasoner|glm-5\.|kimi-k3($|-)|grok-4|llama-3\.1-405b|qwen3-max|qwen3-235b|doubao-seed-1\.6|minimax-m2($|-)|gpt-5\.2|gpt-5\.3|gpt-5\.4)/, base: 0.8 },
+  // Strong (0.65)
+  { re: /(sonnet|gpt-4o$|gpt-4-turbo|gpt-5-mini|gpt-5-nano$|gemini-2\.[05].*pro|qwen3-3[02]b|qwen2\.5-3[23]b|deepseek-v3|glm-4\.7|glm-4\.6|glm-4\.5($|-)|kimi-k2($|-)|mistral-large|codestral|gpt-oss-120b|llama-3\.3-70b|qwen3-30b-a3b|devstral-large|kimi-k2\.5|gemini-3-pro|claude-4\.5)/, base: 0.65 },
+  // Mid (0.50)
+  { re: /(gpt-4o-mini|haiku|o4-mini|qwen3-(4b|8b|14b)|qwen2\.5-(7b|14b)|gemma-3-27b|phi-4|mistral-small|ministral|glm-4-flash|glm-4\.5-air|-lite$|-air$|devstral-small|qwen3-4b|gpt-5\.1)/, base: 0.5 },
+  // Small (0.30)
+  { re: /(-7b|-8b|-9b|^.*[^0-9](7|8|9)b$|mini|nano|gemma-?2|phi-3|llama-3\.2|flash-lite)/, base: 0.3 },
+  // Tiny (0.20)
+  { re: /(-1b|-2b|-3b|-0\.5b|-1\.5b|tiny$|gpt-3\.5)/, base: 0.2 },
+];
+
+const CODER_RE = /(coder|codestral|starcoder|qwen3-coder|devstral)/;
+const REASONER_RE = /(reason|r1$|qwq|\bo1\b|\bo3\b|thinking)/;
+
+function _sizeBase(family) {
+  const m = String(family || '').match(/(\d+(?:\.\d+)?)\s*b(?:$|-)/);
+  if (!m) return null;
+  const gb = Number(m[1]);
+  if (!Number.isFinite(gb)) return null;
+  if (gb >= 100) return 0.8;
+  if (gb >= 30) return 0.65;
+  if (gb >= 10) return 0.5;
+  if (gb >= 4) return 0.35;
+  return 0.25;
+}
+
+/**
+ * @param {string} family — normalized family id (see family.js)
+ * @returns {null | { reasoning:number, codegen:number, debugging:number, tool_use:number }}
+ */
+function heuristicCaps(family) {
+  try {
+    const f = String(family || '').toLowerCase().trim();
+    if (!f || f === 'unknown') return null;
+    let base = null;
+    for (const { re, base: b } of LADDER) {
+      if (re.test(f)) {
+        base = b;
+        break;
+      }
+    }
+    if (base === null) base = _sizeBase(f);
+    if (base === null) return null;
+    const round3 = (v) => Math.max(FLOOR, Math.min(CAP, Math.round(v * 1000) / 1000));
+    const codegen = base + (CODER_RE.test(f) ? 0.05 : 0);
+    const reasoning = base + (REASONER_RE.test(f) ? 0.05 : 0);
+    return {
+      reasoning: round3(reasoning),
+      codegen: round3(codegen),
+      debugging: round3(base),
+      tool_use: round3(base),
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { heuristicCaps };

package/src/routing/capability-seeds/family.js

@@ -0,0 +1,105 @@
+/**
+ * Model-family normalization for capability seeding.
+ *
+ * Capability is a property of the MODEL (weights), not the provider serving
+ * it: zai:glm-5.2, baidu:glm-5.2 and ollama:glm-5.2 must resolve to one
+ * family id ("glm-5.2") and therefore identical caps. Provider stays on the
+ * cost/invocation path only.
+ *
+ * Normalization (order matters):
+ *   1. lowercase + trim, drop @digest suffixes
+ *   2. last `/`-segment wins (strips org prefixes: zai-org/glm-5.2,
+ *      openai/gpt-4o-mini, anthropic/claude-...)
+ *   3. Ollama `:tag` becomes `-tag` (tags often carry SIZE: qwen2.5-coder:7b
+ *      → qwen2.5-coder-7b; :latest/:cloud are noise but harmless post-strip)
+ *   4. strip serving prefixes (databricks-, anthropic., bedrock/)
+ *   5. `_` → `-`, digit-dash-digit → digit.dot.digit
+ *      (gpt-3-5-turbo → gpt-3.5-turbo, llama-3-1-70b → llama-3.1-70b),
+ *      collapse repeats
+ *
+ * Quantization is detected, not normalized away: Q4_K_M / gguf / int4 / awq
+ * style markers set quant:true so the resolver can apply the small
+ * same-brain-smaller-body haircut. Full-precision self-hosted hits the same
+ * caps as the API.
+ *
+ * Pure functions, no I/O. Never throws.
+ */
+
+const SERVING_PREFIXES = ['databricks-', 'anthropic.', 'bedrock/'];
+
+// Quant markers: matched against the full "model:tag" string BEFORE tag
+// folding, and against the folded family after (tags like Q4_K_M survive as
+// -q4-k-m, so one pass after folding suffices — but pre-tag names like
+// "model-Q4" exist too, hence match post-fold only, on the whole string).
+const QUANT_RE = /(q[23468](_|-|$)|_k_[sm]|[-_]q8_0|gguf|int[48]|fp[148]|awq|gptq|bnb|mlx|quantized)/i;
+
+// Tags that carry no signal even as suffixes.
+const NOISE_TAGS = new Set(['latest', 'cloud', 'instruct']);
+
+function detectQuant(s) {
+  try {
+    return QUANT_RE.test(String(s || ''));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} provider
+ * @param {string} model
+ * @returns {{ family:string, quant:boolean }}
+ */
+function normalizeFamily(provider, model) {
+  try {
+    let s = `${String(model || '').trim()}`;
+    // @sha256:... digests
+    s = s.split('@')[0];
+    // org prefix: last segment wins
+    if (s.includes('/')) s = s.split('/').pop();
+    const quant = detectQuant(`${provider || ''}/${model || ''}`) || detectQuant(s);
+    // Ollama :tag → -tag (size tags preserved: :7b → -7b)
+    if (s.includes(':')) {
+      const [base, ...tags] = s.split(':');
+      const kept = tags
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t && !NOISE_TAGS.has(t));
+      s = kept.length > 0 ? `${base}-${kept.join('-')}` : base;
+    }
+    s = s.toLowerCase().trim();
+    for (const p of SERVING_PREFIXES) {
+      if (s.startsWith(p)) {
+        s = s.slice(p.length);
+        break;
+      }
+    }
+    s = s.replace(/_/g, '-');
+    // digit-dash-digit → digit.dot.digit, but only for version runs: the
+    // second digit must be followed by another dash or end-of-string, so
+    // size suffixes survive (llama-3-1-70b → llama-3.1-70b, but
+    // qwen3-32b and gemma-3-27b keep their dash).
+    s = s.replace(/(\d)-(?=\d(?:-|$))/g, '$1.');
+    s = s.replace(/-+/g, '-').replace(/^-|-$/g, '');
+    return { family: s || 'unknown', quant };
+  } catch {
+    return { family: 'unknown', quant: false };
+  }
+}
+
+/**
+ * Quant haircut: same brain, smaller body. Applied by the resolver to
+ * seed/family/tier caps — never to explicit operator overrides (an exact
+ * provider:model override wins verbatim).
+ */
+const QUANT_HAIRCUT = 0.02;
+const QUANT_FLOOR = 0.1;
+
+function applyQuantHaircut(caps) {
+  const out = {};
+  for (const [k, v] of Object.entries(caps || {})) {
+    const n = Number(v);
+    out[k] = Number.isFinite(n) ? Math.max(QUANT_FLOOR, Math.round((n - QUANT_HAIRCUT) * 1000) / 1000) : v;
+  }
+  return out;
+}
+
+module.exports = { normalizeFamily, detectQuant, applyQuantHaircut, QUANT_HAIRCUT };

package/src/routing/capability-seeds/models-dev.js

@@ -0,0 +1,64 @@
+/**
+ * models.dev adapter: boolean capability flags per model (tool_call,
+ * vision/image input, reasoning, context window). Same public endpoint the
+ * pricing registry already consumes (https://models.dev/api.json), same
+ * shape ({ providerId: { models: { modelId: {...} } } }).
+ *
+ * Flags don't set caps — they GATE them: a model with tool_call=false gets
+ * tool_use capped (it can still drive tools via XML extraction, which is why
+ * this is a cap, not a zero). Everything else passes through as provenance
+ * for operator review.
+ *
+ * Fail-soft: { status:'skipped', reason } on any problem.
+ */
+
+const { fetchJson, getCached, setCached, skipped } = require('./sources');
+const { normalizeFamily } = require('./family');
+
+const MODELS_DEV_URL = 'https://models.dev/api.json';
+
+// Conservative ceiling for models without function-calling. XML-extracted
+// tool calls (see xml-tool-extractor.js) keep them usable, hence 0.4 not 0.
+const NO_TOOLCALL_TOOL_USE_CAP = 0.4;
+
+/**
+ * @param {object} [opts] — { refresh:boolean }
+ * @returns {Promise<{ status, flags?:Object<family,{toolCall,vision,reasoning,context}>, reason? }>}
+ */
+async function fetchModelsDevFlags({ refresh = true } = {}) {
+  const parse = (data) => {
+    const out = {};
+    for (const [providerId, providerData] of Object.entries(data || {})) {
+      if (!providerData?.models) continue;
+      for (const [modelId, info] of Object.entries(providerData.models)) {
+        if (!info || typeof info !== 'object') continue;
+        const { family } = normalizeFamily(providerId, modelId);
+        if (family === 'unknown' || out[family]) continue; // first provider wins
+        out[family] = {
+          toolCall: info.tool_call ?? null,
+          vision: Array.isArray(info.input) ? info.input.includes('image') : null,
+          reasoning: info.reasoning ?? null,
+          context: Number(info.context) || null,
+        };
+      }
+    }
+    return out;
+  };
+
+  if (!refresh) {
+    const cached = getCached('modelsdev');
+    if (cached) return { status: 'ok', flags: cached, cached: true };
+    return skipped('no cache (run with --refresh)');
+  }
+  try {
+    const flags = parse(await fetchJson(MODELS_DEV_URL));
+    setCached('modelsdev', flags);
+    return { status: 'ok', flags };
+  } catch (err) {
+    const cached = getCached('modelsdev');
+    if (cached) return { status: 'ok', flags: cached, cached: true, stale: err.message };
+    return skipped(`fetch failed and no cache: ${err.message}`);
+  }
+}
+
+module.exports = { fetchModelsDevFlags, MODELS_DEV_URL, NO_TOOLCALL_TOOL_USE_CAP };

package/src/routing/capability-seeds/normalize.js

@@ -0,0 +1,160 @@
+/**
+ * Score → capability-cap normalization + leaderboard-name → family mapping.
+ *
+ * Anchors (fixed permanently — τ absorbs residual error, consistency matters
+ * more than precision): benchmark fraction 0.8 (≈ flagship SWE-Verified
+ * territory) → caps 0.9; fraction 0 → 0.15 (never zero: even weak models do
+ * trivial turns). Linear between, clamped to [0.15, 0.9].
+ *
+ * Per-head source weights (v1 heuristic, documented):
+ *   debugging = 0.6·swe + 0.4·terminal
+ *   codegen   = 0.5·livecode + 0.3·swe + 0.2·arena
+ *   reasoning = 0.5·swe + 0.3·arena + 0.2·livecode
+ *   tool_use  = 0.6·terminal + 0.4·swe
+ * Missing sources renormalize over the present ones. A pessimistic haircut
+ * (-0.03) applies to all normalized caps: underestimating a new model costs
+ * money (extra escalations), overestimating costs quality.
+ *
+ * Family mapping: order-insensitive token overlap between the normalized
+ * family id and the leaderboard name. Every family token must hit an entry
+ * token exactly or as a version prefix ("4" matches "4.5", "k2" matches
+ * "k2.5" — but "32b" never matches "480b"). Best overlap wins; weak matches
+ * land in `unmapped` for operator review instead of being seeded silently.
+ * Pure functions, never throw.
+ */
+
+const { normalizeFamily } = require('./family');
+
+const CAP_FLOOR = 0.15;
+const CAP_CEIL = 0.9;
+const NORMALIZE_HAIRCUT = 0.03;
+
+// score fraction (0-1) at which caps hit the ceiling — flagship territory.
+const ANCHOR_SCORE = 0.8;
+
+const HEAD_WEIGHTS = {
+  debugging: { swe: 0.6, terminal: 0.4, livecode: 0, arena: 0 },
+  codegen: { swe: 0.3, terminal: 0, livecode: 0.5, arena: 0.2 },
+  reasoning: { swe: 0.5, terminal: 0, livecode: 0.2, arena: 0.3 },
+  tool_use: { swe: 0.4, terminal: 0.6, livecode: 0, arena: 0 },
+};
+
+const STOPWORDS = new Set([
+  'the', 'model', 'preview', 'high', 'medium', 'low',
+  'agent', 'instruct', 'thinking',
+  '2024', '2025', '2026',
+]);
+
+function entryTokens(name) {
+  return String(name || '')
+    .toLowerCase()
+    .split(/[^a-z0-9.]+/)
+    .map((t) => t.replace(/^\.+|\.+$/g, ''))
+    .filter((t) => t && !STOPWORDS.has(t));
+}
+
+function _tokenHit(familyTok, entryToks) {
+  for (const tok of entryToks) {
+    if (tok === familyTok) return true;
+    // version prefix: family "4" hits entry "4.5"; family "k2" hits "k2.5".
+    // The char after the prefix must be a dot (never a letter/digit, so
+    // "32b" can't match "480b" and "gpt-5" can't match "gpt-50").
+    if (tok.length > familyTok.length && tok.startsWith(familyTok) && tok[familyTok.length] === '.') {
+      return true;
+    }
+    // reverse: entry "4" satisfies family "4.5"? No — a bare major never
+    // proves the minor. Skip.
+  }
+  return false;
+}
+
+function familyTokens(family) {
+  return String(family || '')
+    .toLowerCase()
+    .split(/[^a-z0-9.]+/)
+    .map((t) => t.replace(/^\.+|\.+$/g, ''))
+    .filter((t) => t && !STOPWORDS.has(t));
+}
+
+/**
+ * @param {string} entryName — cleaned leaderboard name
+ * @param {string[]} knownFamilies — candidate family ids (seed keys w/o wildcards)
+ * @returns {{ family:string|null, hits:number, of:number }}
+ */
+function mapEntryToFamily(entryName, knownFamilies) {
+  try {
+    const toks = entryTokens(entryName);
+    if (toks.length === 0 || !Array.isArray(knownFamilies)) {
+      return { family: null, hits: 0, of: 0 };
+    }
+    let best = { family: null, hits: 0, of: 0, ratio: 0 };
+    for (const fam of knownFamilies) {
+      const ftoks = familyTokens(fam);
+      if (ftoks.length === 0) continue;
+      let hits = 0;
+      for (const ft of ftoks) {
+        if (_tokenHit(ft, toks)) hits++;
+      }
+      const ratio = hits / ftoks.length;
+      // Full coverage required; ties prefer the more specific family.
+      if (ratio === 1 && (best.family === null || ftoks.length > best.of)) {
+        best = { family: fam, hits, of: ftoks.length, ratio };
+      }
+    }
+    return best.family ? best : { family: null, hits: 0, of: 0 };
+  } catch {
+    return { family: null, hits: 0, of: 0 };
+  }
+}
+
+function scoreToCap(score) {
+  const s = Math.max(0, Math.min(1, Number(score)));
+  if (!Number.isFinite(s)) return null;
+  const cap = CAP_FLOOR + (s / ANCHOR_SCORE) * (CAP_CEIL - CAP_FLOOR);
+  return Math.max(CAP_FLOOR, Math.min(CAP_CEIL, cap));
+}
+
+/**
+ * @param {object} scores — { swe?, terminal?, livecode?, arena? } fractions 0-1
+ * @returns {null | { reasoning, codegen, debugging, tool_use }}
+ */
+function scoresToCaps(scores) {
+  try {
+    if (!scores || typeof scores !== 'object') return null;
+    const present = {};
+    for (const k of ['swe', 'terminal', 'livecode', 'arena']) {
+      const v = Number(scores[k]);
+      if (Number.isFinite(v)) present[k] = Math.max(0, Math.min(1, v));
+    }
+    if (Object.keys(present).length === 0) return null;
+    const caps = {};
+    for (const [head, weights] of Object.entries(HEAD_WEIGHTS)) {
+      let total = 0;
+      let wsum = 0;
+      for (const [src, w] of Object.entries(weights)) {
+        if (present[src] !== undefined && w > 0) {
+          total += scoreToCap(present[src]) * w;
+          wsum += w;
+        }
+      }
+      if (wsum === 0) return null;
+      caps[head] = Math.round((total / wsum - NORMALIZE_HAIRCUT) * 1000) / 1000;
+      caps[head] = Math.max(CAP_FLOOR, Math.min(CAP_CEIL, caps[head]));
+    }
+    return caps;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  mapEntryToFamily,
+  scoresToCaps,
+  scoreToCap,
+  entryTokens,
+  familyTokens,
+  normalizeFamily,
+  CAP_FLOOR,
+  CAP_CEIL,
+  NORMALIZE_HAIRCUT,
+};

package/src/routing/capability-seeds/registry.js

@@ -0,0 +1,125 @@
+/**
+ * Seed registry: per-FAMILY capability profiles from online-derived data.
+ *
+ * Layers (first hit wins in shortfall.js resolveCapabilities):
+ *   operator modelOverrides (provider:model, manual — supreme, lives in
+ *     model-capabilities.json) → snapshot (data/, fetched, `source:'seed:snapshot'`)
+ *     → shipped (config/, reviewed, `source:'seed:shipped'`) → family
+ *     heuristic (`source:'family'`) → tier slot (`source:'tier'`).
+ *
+ * Keys are normalized family ids (see family.js), lowercased, with optional
+ * trailing `*` wildcards matched longest-first (gpt-5* , qwen3-*). Provider
+ * never appears in keys — zai/baidu/ollama servings of glm-5.2 share one entry.
+ *
+ * File lifecycles mirror model-tiers.json: read once at boot, restart to
+ * pick up edits. data/ is gitignored (operator-local), config/ is versioned.
+ * Pure lookups after load; load never throws (missing/malformed → empty).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../../logger');
+const { HEADS } = require('../capabilities');
+
+const SHIPPED_PATH = path.join(__dirname, '../../../config/model-capability-seeds.json');
+const SNAPSHOT_PATH = path.join(__dirname, '../../../data/capability-seeds.snapshot.json');
+
+let _cache = null;
+
+function sanitizeCaps(raw) {
+  const caps = {};
+  for (const h of HEADS) {
+    const v = Number(raw?.[h]);
+    caps[h] = Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 0.5;
+  }
+  return caps;
+}
+
+function _loadSeedsFile(filePath, label) {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const seeds = raw?.seeds && typeof raw.seeds === 'object' ? raw.seeds : {};
+    const out = {};
+    for (const [key, entry] of Object.entries(seeds)) {
+      const caps = entry?.caps && typeof entry.caps === 'object' ? entry.caps : entry;
+      if (!caps || typeof caps !== 'object') continue;
+      out[String(key).toLowerCase()] = {
+        caps: sanitizeCaps(caps),
+        sources: Array.isArray(entry?.sources) ? entry.sources : [],
+        note: typeof entry?.note === 'string' ? entry.note : '',
+      };
+    }
+    return out;
+  } catch (err) {
+    logger.debug({ err: err.message, label }, '[SeedRegistry] seed file load failed — skipping layer');
+    return {};
+  }
+}
+
+function loadSeedLayers() {
+  if (_cache) return _cache;
+  _cache = {
+    snapshot: _loadSeedsFile(SNAPSHOT_PATH, 'snapshot'),
+    shipped: _loadSeedsFile(SHIPPED_PATH, 'shipped'),
+  };
+  return _cache;
+}
+
+function _resetSeedsCache() {
+  _cache = null;
+}
+
+// Test hook: inject layers directly (Operations on the same cached object
+// the resolver reads).
+function _setSeedsForTests({ snapshot, shipped } = {}) {
+  const base = loadSeedLayers();
+  _cache = {
+    snapshot: snapshot ?? base.snapshot,
+    shipped: shipped ?? base.shipped,
+  };
+  return _cache;
+}
+
+function _matchWildcard(layer, family) {
+  let best = null;
+  for (const [key, entry] of Object.entries(layer)) {
+    if (!key.endsWith('*')) continue;
+    const prefix = key.slice(0, -1);
+    if (prefix && family.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
+      best = { prefix, entry };
+    }
+  }
+  return best?.entry ?? null;
+}
+
+/**
+ * @param {string} family — normalized family id
+ * @returns {null | { caps, source:'seed:snapshot'|'seed:shipped', sources, note }}
+ */
+function resolveSeedCaps(family) {
+  try {
+    const f = String(family || '').toLowerCase().trim();
+    if (!f || f === 'unknown') return null;
+    const { snapshot, shipped } = loadSeedLayers();
+    if (snapshot[f]) return { ...snapshot[f], source: 'seed:snapshot' };
+    if (shipped[f]) return { ...shipped[f], source: 'seed:shipped' };
+    const snapWild = _matchWildcard(snapshot, f);
+    if (snapWild) return { ...snapWild, source: 'seed:snapshot' };
+    const shipWild = _matchWildcard(shipped, f);
+    if (shipWild) return { ...shipWild, source: 'seed:shipped' };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  loadSeedLayers,
+  _resetSeedsCache,
+  _setSeedsForTests,
+  resolveSeedCaps,
+  sanitizeCaps,
+  SHIPPED_PATH,
+  SNAPSHOT_PATH,
+};