lynkr 9.14.2 → 9.14.7

package/src/routing/ope.js

@@ -0,0 +1,255 @@
+/**
+ * Off-policy evaluation (ROUTING-NOTES §3 + §4.10.3).
+ *
+ * Estimates how a CANDIDATE routing policy would have performed, using only
+ * logged decisions made by the LIVE policy — no live traffic, no A/B test.
+ * This consumes exactly what WS4.2 has been logging on every telemetry row
+ * since it shipped: `propensity` (the live policy's probability of the
+ * logged choice), `candidates` (the choice set), `quality_score` (reward),
+ * and — as of the same change that added this module — `context` (the
+ * bandit's 12-dim feature vector, needed by the doubly-robust term).
+ *
+ * Four estimators, in increasing order of sophistication:
+ *
+ *   IPS    importance sampling: reweight logged rewards by
+ *          π(a|x) / p. Unbiased but high-variance when propensities are
+ *          small.
+ *   SNIPS  self-normalized IPS: divide by the sum of weights instead of n.
+ *          Slightly biased, far lower variance (Swaminathan & Joachims).
+ *   DR     doubly robust (Dudík/Langford/Li 2011): a regression baseline
+ *          r̂(x, a) — LinUCB's own per-arm ridge model, reused — plus the
+ *          importance-weighted residual. Unbiased if EITHER the propensities
+ *          OR the regression model is right.
+ *   WDR    weighted DR: DR with SNIPS-style self-normalized weights on the
+ *          correction term. The production target named by real systems'
+ *          own code ("the IPS/DR/WDR estimators").
+ *
+ * A candidate policy is a plain function:
+ *   policyFn({ tier, context, candidates }) →
+ *     { probs: Map<candidateKey, number> } — action probabilities summing
+ *     to 1 over the row's candidate set (deterministic policies return
+ *     probability 1 on one candidate).
+ *
+ * Rewards are quality_score rescaled to [0, 1] (same scale the bandit and
+ * its r̂ train on). Rows are only usable when they carry propensity,
+ * candidates (≥1), and quality_score; the DR term additionally needs
+ * context and falls back to the pure IPS term on rows without it.
+ *
+ * @module routing/ope
+ */
+
+const { getBandit } = require('./bandit');
+
+/** Canonical key for a candidate. */
+function candKey(c) {
+  return `${c.provider}:${c.model}`;
+}
+
+// Propensity floor: a logged propensity below this is clamped, bounding any
+// single row's importance weight (the same reason workweave's Monte-Carlo
+// propensity floors at 1/trials — one row must not dominate the estimate).
+const PROPENSITY_FLOOR = 1e-3;
+
+function _parseRow(row) {
+  if (row == null) return null;
+  const propensity = typeof row.propensity === 'number' ? row.propensity : null;
+  const quality = typeof row.quality_score === 'number' ? row.quality_score : null;
+  if (propensity == null || quality == null) return null;
+
+  let candidates = row.candidates;
+  if (typeof candidates === 'string') {
+    try {
+      candidates = JSON.parse(candidates);
+    } catch {
+      return null;
+    }
+  }
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+
+  let context = row.context ?? null;
+  if (typeof context === 'string') {
+    try {
+      context = JSON.parse(context);
+    } catch {
+      context = null;
+    }
+  }
+  if (!Array.isArray(context)) context = null;
+
+  return {
+    tier: row.tier ?? null,
+    served: { provider: row.provider, model: row.model ?? null },
+    reward: Math.max(0, Math.min(1, quality / 100)),
+    propensity: Math.max(PROPENSITY_FLOOR, Math.min(1, propensity)),
+    candidates,
+    context,
+  };
+}
+
+/**
+ * Evaluate a candidate policy against logged telemetry rows.
+ *
+ * @param {Array<object>} rows — telemetry rows (raw DB rows or equivalents)
+ * @param {Function} policyFn — ({ tier, context, candidates }) → { probs: Map }
+ * @param {object} [deps]
+ * @param {object} [deps.bandit] — override the reward model (tests)
+ * @returns {{
+ *   n: number, usable: number, drRows: number,
+ *   ips: number|null, snips: number|null, dr: number|null, wdr: number|null,
+ *   effectiveSampleSize: number|null,
+ *   loggedMeanReward: number|null,
+ * }}
+ */
+function evaluatePolicy(rows, policyFn, deps = {}) {
+  const bandit = deps.bandit || getBandit();
+
+  let usable = 0;
+  let drRows = 0;
+  let ipsSum = 0;
+  let weightSum = 0;
+  let weightSqSum = 0;
+  let drSum = 0;
+  let wdrBaselineSum = 0;
+  let wdrCorrectionSum = 0;
+  let loggedRewardSum = 0;
+
+  for (const raw of rows) {
+    const row = _parseRow(raw);
+    if (!row) continue;
+    usable += 1;
+    loggedRewardSum += row.reward;
+
+    let probs;
+    try {
+      const out = policyFn({ tier: row.tier, context: row.context, candidates: row.candidates });
+      probs = out?.probs;
+    } catch {
+      probs = null;
+    }
+    if (!probs) continue;
+
+    // π(a_logged | x): the candidate policy's probability of the action the
+    // live policy actually served.
+    const piLogged = probs.get(candKey(row.served)) ?? 0;
+    const w = piLogged / row.propensity;
+
+    ipsSum += w * row.reward;
+    weightSum += w;
+    weightSqSum += w * w;
+
+    // DR terms: baseline = Σ_a π(a|x)·r̂(x,a); correction = w·(r − r̂(x,a_logged)).
+    // Rows without a context (bandit didn't run) or without a usable r̂ fall
+    // back to r̂ = 0, which reduces the row's DR contribution to pure IPS.
+    let baseline = 0;
+    let rhatLogged = 0;
+    if (row.context && row.tier) {
+      drRows += 1;
+      for (const c of row.candidates) {
+        const p = probs.get(candKey(c)) ?? 0;
+        if (p === 0) continue;
+        const rhat = bandit.estimateReward(row.tier, c.provider, c.model, row.context);
+        if (rhat != null) baseline += p * rhat;
+      }
+      const rhatServed = bandit.estimateReward(row.tier, row.served.provider, row.served.model, row.context);
+      if (rhatServed != null) rhatLogged = rhatServed;
+    }
+    drSum += baseline + w * (row.reward - rhatLogged);
+    wdrBaselineSum += baseline;
+    wdrCorrectionSum += w * (row.reward - rhatLogged);
+  }
+
+  if (usable === 0) {
+    return {
+      n: rows.length, usable: 0, drRows: 0,
+      ips: null, snips: null, dr: null, wdr: null,
+      effectiveSampleSize: null, loggedMeanReward: null,
+    };
+  }
+
+  // Effective sample size — Kish's approximation. A small ESS relative to
+  // `usable` means a few high-weight rows dominate: treat the estimate with
+  // suspicion regardless of its value.
+  const ess = weightSqSum > 0 ? (weightSum * weightSum) / weightSqSum : 0;
+
+  return {
+    n: rows.length,
+    usable,
+    drRows,
+    ips: ipsSum / usable,
+    snips: weightSum > 0 ? ipsSum / weightSum : null,
+    dr: drSum / usable,
+    // WDR: baseline averaged per-row (deterministic, no weights) plus the
+    // self-normalized correction — variance control on exactly the term
+    // that needs it.
+    wdr: weightSum > 0
+      ? wdrBaselineSum / usable + wdrCorrectionSum / weightSum
+      : wdrBaselineSum / usable,
+    effectiveSampleSize: ess,
+    loggedMeanReward: loggedRewardSum / usable,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Reference policies — useful baselines to evaluate out of the box.
+// ---------------------------------------------------------------------------
+
+/** Always pick the first candidate (the tier-config/heuristic selection). */
+function firstCandidatePolicy({ candidates }) {
+  const probs = new Map();
+  candidates.forEach((c, i) => probs.set(candKey(c), i === 0 ? 1 : 0));
+  return { probs };
+}
+
+/** Always pick the last candidate (the kNN suggestion when present). */
+function lastCandidatePolicy({ candidates }) {
+  const probs = new Map();
+  const lastIdx = candidates.length - 1;
+  candidates.forEach((c, i) => probs.set(candKey(c), i === lastIdx ? 1 : 0));
+  return { probs };
+}
+
+/** Uniform-random over the candidate set. */
+function uniformPolicy({ candidates }) {
+  const probs = new Map();
+  const p = 1 / candidates.length;
+  candidates.forEach((c) => probs.set(candKey(c), p));
+  return { probs };
+}
+
+/**
+ * The current LinUCB policy replayed greedily (no exploration, mean+bonus
+ * argmax at TODAY'S learned weights). Comparing this against the logged
+ * rewards answers: "has the bandit's learning actually converged on
+ * something better than what it served while learning?"
+ */
+function currentBanditGreedyPolicy({ tier, context, candidates }, deps = {}) {
+  const bandit = deps.bandit || getBandit();
+  const probs = new Map();
+  if (!context || !tier || candidates.length < 2) {
+    return firstCandidatePolicy({ candidates });
+  }
+  let best = null;
+  let bestVal = -Infinity;
+  for (const c of candidates) {
+    const est = bandit.estimateReward(tier, c.provider, c.model, context);
+    const val = est ?? -1; // unknown arms lose to any known arm
+    if (val > bestVal) {
+      bestVal = val;
+      best = c;
+    }
+  }
+  candidates.forEach((c) => probs.set(candKey(c), c === best ? 1 : 0));
+  return { probs };
+}
+
+module.exports = {
+  evaluatePolicy,
+  candKey,
+  PROPENSITY_FLOOR,
+  policies: {
+    firstCandidate: firstCandidatePolicy,
+    lastCandidate: lastCandidatePolicy,
+    uniform: uniformPolicy,
+    currentBanditGreedy: currentBanditGreedyPolicy,
+  },
+};

package/src/routing/openai-model-slots.js

@@ -0,0 +1,82 @@
+/**
+ * Model + reasoning-effort → tier mapping for Codex/ChatGPT desktop's model
+ * picker (the "5.6 Sol Light" dropdown in the app UI).
+ *
+ * This is the OpenAI/Responses-API-shaped counterpart to ./model-slots.js.
+ * That module works because Claude Desktop lets a gateway advertise
+ * completely made-up model ids ("claude-fable-5" etc.) via its own /v1/models
+ * list. Codex has no such gateway hook — its dropdown is populated from
+ * OpenAI's own real model catalog, and it always sends a real OpenAI model
+ * id (e.g. "gpt-5.6-sol", "gpt-5.6-mini") plus a `reasoning.effort` field
+ * (OpenAI's documented enum: minimal | low | medium | high). So instead of
+ * inventing ids, this pins on (model, effort) combinations Codex's dropdown
+ * can actually produce.
+ *
+ * Verification status: CONFIRMED live (2026-08-28) via a temp diagnostic log
+ * (since removed) that captured a real Codex Desktop request. A screenshot
+ * of the picker showed model options "5.6 Sol / 5.6 Terra / 5.6 Luna / 5.5 /
+ * 5.2" (five peer entries, no visible size/tier hint — an earlier version of
+ * this file guessed "luna" meant a cheap/distilled variant; that guess had
+ * no evidence and has been removed) and an "Effort" row labeled "Light".
+ * The captured request, sent with that exact picker state, carried
+ * `reasoning: {"effort":"low","summary":"detailed","context":"all_turns"}`
+ * — so the UI label "Light" is confirmed to be OpenAI's documented public
+ * enum value "low" verbatim, not a distinct string. resolveTierForOpenAIModel()
+ * stays conservative regardless: any unrecognized model or effort value
+ * returns null (no pin), falling through to normal content-based scoring.
+ *
+ * Scope note (also observed live in the same captured session): the pin
+ * only governs the FIRST model call of a turn. Multi-step agentic turns
+ * (tool calls, follow-up steps) re-score by content on each subsequent
+ * step — this is inherent to the shared `_forceProvider` mechanism
+ * (orchestrator/index.js deletes it after the first read), identical to
+ * how router.js's own Claude-Desktop-picker pin already behaves. Not a bug
+ * introduced here; a pre-existing property of the shared pin plumbing.
+ *
+ * Shared by:
+ *   - src/api/openai-router.js — resolves an incoming /chat/completions or
+ *     /responses request's `model` + `reasoning.effort` fields to a tier,
+ *     mirroring router.js's model-id-pin block (which openai-router.js's
+ *     handlers never go through — they call orchestrator.processMessage()
+ *     directly).
+ *
+ * @module routing/openai-model-slots
+ */
+
+// OpenAI's publicly documented naming convention for distilled/cheap model
+// variants — NOT confirmed present in this app's specific dropdown (its
+// real options are Sol/Terra/Luna/5.5/5.2, no mini/nano seen), kept only
+// because it's a well-established public-catalog convention that costs
+// nothing to check if some other Codex build or client does send one.
+const SMALL_MODEL_PATTERN = /-(mini|nano)\b/i;
+
+// reasoning.effort → tier. Confirmed live 2026-08-28: Codex Desktop's
+// "Light" picker label sends the literal wire value "low", not "light" —
+// OpenAI's publicly documented Responses API enum, verbatim. See the module
+// doc comment above for the captured request that confirmed this.
+const EFFORT_TIER = {
+  minimal: "SIMPLE",
+  low: "MEDIUM",
+  medium: "COMPLEX",
+  high: "REASONING",
+};
+
+/**
+ * Resolve a Codex-style model id + reasoning effort to a Lynkr tier.
+ *
+ * @param {string|null|undefined} model - e.g. "gpt-5.6-sol"
+ * @param {string|null|undefined} effort - e.g. "low" (from body.reasoning.effort)
+ * @returns {string|null} one of SIMPLE/MEDIUM/COMPLEX/REASONING, or null when
+ *   unrecognized — caller should fall through to normal content scoring.
+ */
+function resolveTierForOpenAIModel(model, effort) {
+  if (typeof model === "string" && SMALL_MODEL_PATTERN.test(model)) {
+    return "SIMPLE";
+  }
+  if (typeof effort === "string" && EFFORT_TIER[effort.toLowerCase()]) {
+    return EFFORT_TIER[effort.toLowerCase()];
+  }
+  return null;
+}
+
+module.exports = { EFFORT_TIER, SMALL_MODEL_PATTERN, resolveTierForOpenAIModel };

package/src/routing/shortfall.js

@@ -0,0 +1,290 @@
+/**
+ * Shortfall matching (item 1: HyDRA port, phase 1).
+ *
+ * Selects the cheapest candidate whose capabilities cover the predicted
+ * requirement vector within tolerance τ:
+ *
+ *   shortfall(m) = Σ w_k · max(0, req_k − cap_mk)
+ *
+ * All four heads share the [0,1] bandwidth, so v1 weights are uniform
+ * (band compensation is a no-op until heads diverge — noted for phase 2).
+ *
+ * Contracts:
+ *   - Catalog-decoupled: candidates arrive as [{provider, model, tier}];
+ *     capabilities resolve per MODEL FAMILY (provider never matters:
+ *     zai/baidu/ollama servings of glm-5.2 share caps) via operator
+ *     modelOverrides → seed snapshot/shipped → family heuristic → tier
+ *     profile. Adding, removing, or repricing a model re-routes via config
+ *     with zero retraining.
+ *   - Self-contained config: enabled/tau/weights also live in
+ *     config/model-capabilities.json — no env vars. The file is read once at
+ *     boot (same lifecycle as config/model-tiers.json); restart to pick up
+ *     edits.
+ *   - Cost comes from the caller (model-registry) or per-1k blended estimate;
+ *     unknown cost sorts last (conservative — never wins on cheapness alone).
+ *   - No covering candidate (all shortfalls > τ) → minimal shortfall wins,
+ *     tiebreak higher tier (correctness over cost, matches tier-fallback.js
+ *     escalate-then-demote bias). Never returns null on valid input; returns
+ *     null only on malformed input so callers fail open to legacy routing.
+ *   - Pure except for config load (cached). Never throws.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+const { HEADS } = require('./capabilities');
+
+const PROFILES_PATH = path.join(__dirname, '../../config/model-capabilities.json');
+
+const DEFAULT_TAU = 0.24; // HyDRA iso-quality operating point
+const TIER_PRIORITY = { SIMPLE: 1, MEDIUM: 2, COMPLEX: 3, REASONING: 4 };
+
+let _profilesCache = null;
+
+function _defaultWeights() {
+  const w = {};
+  for (const h of HEADS) w[h] = 1 / HEADS.length;
+  return w;
+}
+
+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 loadProfiles() {
+  if (_profilesCache) return _profilesCache;
+  try {
+    const raw = JSON.parse(fs.readFileSync(PROFILES_PATH, 'utf8'));
+    const tierProfiles = {};
+    const fileTiers = raw?.tierProfiles && typeof raw.tierProfiles === 'object'
+      ? raw.tierProfiles
+      : {};
+    for (const [tier, caps] of Object.entries(fileTiers)) {
+      if (caps && typeof caps === 'object') tierProfiles[tier] = _sanitizeCaps(caps);
+    }
+    const modelOverrides = {};
+    const fileOverrides = raw?.modelOverrides && typeof raw.modelOverrides === 'object'
+      ? raw.modelOverrides
+      : {};
+    for (const [key, caps] of Object.entries(fileOverrides)) {
+      if (caps && typeof caps === 'object') modelOverrides[String(key).toLowerCase()] = _sanitizeCaps(caps);
+    }
+    const tau = Number(raw?.tau);
+    const weights = _normalizeWeights(raw?.weights);
+    _profilesCache = {
+      tierProfiles,
+      modelOverrides,
+      enabled: raw?.enabled === true,
+      tau: Number.isFinite(tau) && tau >= 0 ? tau : DEFAULT_TAU,
+      weights,
+    };
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Shortfall] profiles load failed — disabled with tier fallbacks');
+    _profilesCache = { tierProfiles: {}, modelOverrides: {}, enabled: false, tau: DEFAULT_TAU, weights: _defaultWeights() };
+  }
+  return _profilesCache;
+}
+
+// Exposed for tests (cache reset / profile injection).
+function _resetProfilesCache() {
+  _profilesCache = null;
+}
+
+function _setProfilesForTests(profiles) {
+  const base = loadProfiles();
+  _profilesCache = {
+    tierProfiles: profiles?.tierProfiles ?? base.tierProfiles,
+    modelOverrides: profiles?.modelOverrides ?? base.modelOverrides,
+    enabled: profiles?.enabled ?? base.enabled,
+    tau: profiles?.tau ?? base.tau,
+    weights: profiles?.weights ?? base.weights,
+  };
+  return _profilesCache;
+}
+
+function _normalizeWeights(raw) {
+  const w = _defaultWeights();
+  if (!raw || typeof raw !== 'object') return w;
+  let touched = false;
+  for (const h of HEADS) {
+    const v = Number(raw[h]);
+    if (Number.isFinite(v) && v >= 0) {
+      w[h] = v;
+      touched = true;
+    }
+  }
+  if (!touched) return _defaultWeights();
+  const sum = Object.values(w).reduce((a, b) => a + b, 0);
+  if (sum <= 0) return _defaultWeights();
+  for (const h of HEADS) w[h] = w[h] / sum;
+  return w;
+}
+
+function getTau() {
+  return loadProfiles().tau;
+}
+
+function getWeights() {
+  return { ...loadProfiles().weights };
+}
+
+function isEnabled() {
+  return loadProfiles().enabled === true;
+}
+
+/**
+ * Resolve capabilities for one candidate. Precedence (first hit wins):
+ *   1. operator "provider:model" / "provider:*" override (manual, supreme,
+ *      returned verbatim — not even the quant haircut applies)
+ *   2. seed snapshot / shipped seeds by normalized MODEL FAMILY
+ *      (zai/baidu/ollama servings of glm-5.2 share one entry)
+ *   3. family-ladder heuristic (zero-network estimate, never frontier)
+ *   4. tier profile → tier-priority fallback (SIMPLE 0.2 … REASONING 0.9)
+ *
+ * Quantized self-hosted servings (Q4_K_M, gguf, …) take a small haircut at
+ * every level except 1: same brain, smaller body.
+ *
+ * @returns {{ caps, source }} — source is override|seed:snapshot|
+ *   seed:shipped|family|tier|tier-fallback (telemetry provenance).
+ */
+function resolveCapabilitiesWithSource({ provider, model, tier }) {
+  const { tierProfiles, modelOverrides } = loadProfiles();
+  const key = `${String(provider || '').toLowerCase()}:${String(model || '').toLowerCase()}`;
+  const wild = `${String(provider || '').toLowerCase()}:*`;
+  const pick = modelOverrides[key] || modelOverrides[wild];
+  if (pick) return { caps: { ...pick }, source: 'override' };
+
+  let family = 'unknown';
+  let quant = false;
+  try {
+    const fam = require('./capability-seeds/family');
+    ({ family, quant } = fam.normalizeFamily(provider, model));
+  } catch { /* family helpers unavailable — tier fallback below */ }
+
+  try {
+    const { resolveSeedCaps } = require('./capability-seeds/registry');
+    const seed = resolveSeedCaps(family);
+    if (seed) {
+      const caps = quant
+        ? require('./capability-seeds/family').applyQuantHaircut(seed.caps)
+        : { ...seed.caps };
+      return { caps, source: seed.source };
+    }
+  } catch { /* seed layers unavailable — keep falling through */ }
+
+  try {
+    const { heuristicCaps } = require('./capability-seeds/family-heuristics');
+    const heur = heuristicCaps(family);
+    if (heur) {
+      const caps = quant
+        ? require('./capability-seeds/family').applyQuantHaircut(heur)
+        : heur;
+      return { caps, source: 'family' };
+    }
+  } catch { /* heuristic unavailable — tier fallback below */ }
+
+  const tp = tierProfiles[tier];
+  if (tp) {
+    const caps = quant
+      ? require('./capability-seeds/family').applyQuantHaircut(tp)
+      : { ...tp };
+    return { caps, source: 'tier' };
+  }
+  const p = (TIER_PRIORITY[tier] || 1) / 4;
+  const caps = {};
+  for (const h of HEADS) caps[h] = Math.round(p * 1000) / 1000;
+  return { caps, source: 'tier-fallback' };
+}
+
+function resolveCapabilities(candidate) {
+  return resolveCapabilitiesWithSource(candidate).caps;
+}
+
+function shortfall(req, caps, weights = null) {
+  const w = weights || _defaultWeights();
+  let s = 0;
+  for (const h of HEADS) {
+    const r = Math.max(0, Math.min(1, Number(req?.[h]) || 0));
+    const c = Math.max(0, Math.min(1, Number(caps?.[h]) || 0));
+    s += (w[h] ?? 0) * Math.max(0, r - c);
+  }
+  return Math.round(s * 10000) / 10000;
+}
+
+function _costValue(c) {
+  const n = Number(c);
+  return Number.isFinite(n) && n >= 0 ? n : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * @param {object} req — requirement vector {reasoning, codegen, debugging, tool_use} in [0,1]
+ * @param {Array<{provider, model, tier, cost?}>} candidates — catalog-constrained set
+ *   (callers pass getAllConfiguredModels() + model-registry costs)
+ * @param {object} [opts] — { tau, weights }
+ * @returns {null | { selected, shortfalls: Array<{provider, model, tier, shortfall, cost, source}>, tau }}
+ */
+function selectByShortfall(req, candidates, opts = {}) {
+  try {
+    if (!req || typeof req !== 'object') return null;
+    if (!Array.isArray(candidates) || candidates.length === 0) return null;
+    const tau = opts.tau ?? getTau();
+    const weights = opts.weights ?? getWeights();
+
+    const rows = candidates
+      .filter((c) => c && c.provider && c.model)
+      .map((c) => {
+        const { caps, source } = resolveCapabilitiesWithSource(c);
+        return {
+          provider: c.provider,
+          model: c.model,
+          tier: c.tier || 'MEDIUM',
+          cost: _costValue(c.cost),
+          shortfall: shortfall(req, caps, weights),
+          source,
+        };
+      });
+    if (rows.length === 0) return null;
+
+    const covering = rows.filter((r) => r.shortfall <= tau);
+    const pool = covering.length > 0 ? covering : rows;
+    pool.sort((a, b) => {
+      if (covering.length > 0) {
+        // Cheapest covering wins; cost tie (incl. all-unknown) breaks toward
+        // the LOWER tier — a covering lower tier is sufficient by definition,
+        // so prefer it over excess headroom (avoids over-provisioning).
+        if (a.cost !== b.cost) return a.cost - b.cost;
+        return (TIER_PRIORITY[a.tier] || 0) - (TIER_PRIORITY[b.tier] || 0);
+      }
+      // Nothing covers: minimal shortfall wins, tiebreak higher tier then cheaper.
+      if (a.shortfall !== b.shortfall) return a.shortfall - b.shortfall;
+      const tp = (TIER_PRIORITY[b.tier] || 0) - (TIER_PRIORITY[a.tier] || 0);
+      if (tp !== 0) return tp;
+      return a.cost - b.cost;
+    });
+
+    return { selected: pool[0], shortfalls: rows, tau };
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Shortfall] select failed — failing open');
+    return null;
+  }
+}
+
+module.exports = {
+  HEADS,
+  DEFAULT_TAU,
+  loadProfiles,
+  _resetProfilesCache,
+  _setProfilesForTests,
+  getTau,
+  getWeights,
+  isEnabled,
+  resolveCapabilities,
+  resolveCapabilitiesWithSource,
+  shortfall,
+  selectByShortfall,
+};