lynkr 9.14.11 → 9.14.13

package/src/routing/jev-router.js

@@ -0,0 +1,272 @@
+/**
+ * Jev (TypeSafe System One) routing judge.
+ *
+ * Replaces the qwen-based difficulty classifier as the second opinion in
+ * intent scoring: one typed Choice over the four tiers (+ a parallel
+ * risk Noul, free — questions share state) instead of JSON coaxed through
+ * a thinking block. Native per-option probabilities replace self-reported
+ * confidence; 0.5s vs up-to-10s timeout; no local prefill.
+ *
+ * Design constraints (operator policy):
+ *   - No new env vars. Endpoint, pinned model, timeout, cache size and the
+ *     promotion cut are constants below. Only TYPESAFE_API_KEY is read from
+ *     env (pre-existing); absent key disables the client. Rollback is a
+ *     revert, not a flag — a hardcoded kill-switch you can only flip with a
+ *     code edit is theater; the fail-soft nulls are the real safety.
+ *   - Fail-soft: any failure (no key, timeout, 429/529, malformed body)
+ *     returns null and callers fall back exactly as if no classifier ran.
+ *     Single attempt, no retries in the hot path.
+ *   - Pinned model version (jev-1.13.0 observed live), never jev-latest:
+ *     routing must not ride alias drift. Re-run the difficulty evals on
+ *     any bump. Criteria text is hashed into telemetry so prompt tweaks
+ *     don't silently invalidate history either.
+ *
+ * Pure except for fetch (injectable) and the LRU cache. Never throws.
+ */
+
+const crypto = require('crypto');
+const logger = require('../logger');
+
+const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
+const JEV_MODEL = 'jev-1.13.0';
+const JEV_TIMEOUT_MS = 3000;
+const JEV_CACHE_CAPACITY = 500;
+// Promotion cut for letting a Jev tier override the heuristic (Phase 2).
+// Matches the existing upward-gate in intent-score _reconcile (0.8);
+// ratify against shadow agreement-vs-confidence data when available.
+const JEV_PROMOTE_CONFIDENCE = 0.8;
+// Risk corroboration cut: Noul at/above this corroborates upward only
+// (may escalate, never clears a keyword hit).
+const JEV_RISK_CUT = 0.85;
+
+const VALID_TIERS = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+
+// v1 criteria — carries the hard-won disambiguators from the qwen prompt
+// generations (casual follow-ups, arithmetic, verify-file-exists).
+const TIER_CRITERIA_V1 = {
+  SIMPLE: 'Greetings, confirmations, casual follow-ups about people, stories or everyday facts, trivial lookups and arithmetic. Any tiny model handles. NOT reasoning: who kills him?, 12+21, prove me wrong lol.',
+  MEDIUM: 'One specific mechanical task or focused explanation. A mid-size model suffices. Examples: list the exports from this file, explain this regex, verify the file exists before reading it.',
+  COMPLEX: 'Multi-file design, systemic refactor, architecture review, debugging that requires broad code understanding. Needs a strong general model.',
+  REASONING: 'Formal proof, correctness verification, security audit, novel algorithm design, reasoning from first principles. Needs a frontier reasoning model.',
+};
+
+const TIER_INSTRUCTIONS = 'Which difficulty tier should serve this coding-assistant request? Judge the TASK the model must perform, not the vocabulary.';
+const RISK_INSTRUCTIONS = 'This request involves auth, secrets, credentials, production systems, deployments, or destructive/data-loss operations.';
+
+const CRITERIA_HASH = crypto
+  .createHash('sha256')
+  .update(JSON.stringify(TIER_CRITERIA_V1))
+  .digest('hex')
+  .slice(0, 12);
+
+// Defensive caps (far below the ~32k-token request budget; condensed states
+// never approach them — the guard exists so a pathological upstream payload
+// can't turn a 0.5s judgment into a 30k-token one).
+const MAX_REQUEST_CHARS = 4000;
+const MAX_CONTEXT_CHARS = 500;
+
+const _cache = new Map(); // key -> result (LRU-ish: delete+re-set on hit)
+
+function _evictIfNeeded() {
+  while (_cache.size > JEV_CACHE_CAPACITY) {
+    const oldest = _cache.keys().next();
+    if (oldest.done) break;
+    _cache.delete(oldest.value);
+  }
+}
+
+function getApiKey() {
+  const raw = process.env.TYPESAFE_API_KEY;
+  if (!raw || typeof raw !== 'string') return null;
+  const key = raw.trim().replace(/^["']|["']$/g, '').split(/\s/)[0];
+  return key || null;
+}
+
+function _stripReminders(s) {
+  return typeof s === 'string'
+    ? s.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+    : s;
+}
+
+function _cacheKey(text, context, signals) {
+  return crypto
+    .createHash('sha256')
+    .update(`${text || ''}\0${context || ''}\0${JSON.stringify(signals || {})}\0${CRITERIA_HASH}`)
+    .digest('hex');
+}
+
+/**
+ * Build the Jev state: current ask in full, condensed context, precomputed
+ * signals. Signals over transcripts: the counts/flags carry the routing
+ * information at ~30 tokens instead of ~6k.
+ */
+function buildJevState({ text, context = null, signals = {} } = {}) {
+  let current = _stripReminders(text || '');
+  if (current.length > MAX_REQUEST_CHARS) current = current.slice(0, MAX_REQUEST_CHARS);
+  let ctx = context ? _stripReminders(context) : null;
+  if (ctx && ctx.length > MAX_CONTEXT_CHARS) ctx = ctx.slice(0, MAX_CONTEXT_CHARS);
+  return {
+    current_request: current,
+    conversation_context: ctx || undefined,
+    signals: {
+      message_count: Number(signals.message_count) || 0,
+      tools_attached: Number(signals.tools_attached) || 0,
+      effective_tools: Number(signals.effective_tools) || 0,
+      has_tool_history: !!signals.has_tool_history,
+      session_turn: Number(signals.session_turn) || 0,
+    },
+  };
+}
+
+function _normalizeTier(t) {
+  if (!t || typeof t !== 'string') return null;
+  const up = t.trim().toUpperCase();
+  return VALID_TIERS.includes(up) ? up : null;
+}
+
+function _num01(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : null;
+}
+
+/**
+ * One batched evaluation: Choice(tier) + Noul(risky) sharing state.
+ * @returns {null | {tier, confidence, probabilities, risky, model, latencyMs, criteriaHash}}
+ */
+async function evaluateJev(state, { fetchFn = null, endpoint = JEV_ENDPOINT, apiKey = null } = {}) {
+  const key = apiKey || getApiKey();
+  if (!key) return null;
+  const fetchImpl = fetchFn || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return null;
+  const started = Date.now();
+  try {
+    const body = {
+      state,
+      model: JEV_MODEL,
+      questions: {
+        tier: { type: 'choice', instructions: TIER_INSTRUCTIONS, criteria: TIER_CRITERIA_V1 },
+        risky: { type: 'noul', instructions: RISK_INSTRUCTIONS },
+      },
+    };
+    const resp = await fetchImpl(endpoint, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(JEV_TIMEOUT_MS),
+    });
+    if (!resp || !resp.ok) return null;
+    const data = await resp.json();
+    const t = data?.answers?.tier;
+    const tier = _normalizeTier(t?.choice);
+    if (!tier) return null;
+    return {
+      tier,
+      confidence: _num01(t?.confidence) ?? 0,
+      probabilities: (t?.probabilities && typeof t.probabilities === 'object') ? t.probabilities : null,
+      risky: _num01(data?.answers?.risky?.noul),
+      model: typeof data?.model === 'string' ? data.model : JEV_MODEL,
+      latencyMs: Date.now() - started,
+      criteriaHash: CRITERIA_HASH,
+    };
+  } catch (err) {
+    logger.debug({ err: err?.message || String(err) }, '[Jev] evaluation failed — fail-soft null');
+    return null;
+  }
+}
+
+/**
+ * LRU-cached classify() matching the qwen classifyDifficulty return shape
+ * ({tier, confidence}) plus Jev extras, so intent-score swaps one call.
+ */
+async function classifyJev(text, { context = null, signals = {}, fetchFn = null } = {}) {
+  const clean = _stripReminders(text || '');
+  if (!clean) return null;
+  const cacheKey = _cacheKey(clean, context, signals);
+  const hit = _cache.get(cacheKey);
+  if (hit) {
+    _cache.delete(cacheKey);
+    _cache.set(cacheKey, hit);
+    return { ...hit, cached: true };
+  }
+  const state = buildJevState({ text: clean, context, signals });
+  const result = await evaluateJev(state, { fetchFn });
+  if (result) {
+    _cache.set(cacheKey, result);
+    _evictIfNeeded();
+  }
+  return result;
+}
+
+function _clearCache() {
+  _cache.clear();
+}
+
+const _TIER_PRI = { SIMPLE: 1, MEDIUM: 2, COMPLEX: 3, REASONING: 4 };
+function _pri(tier) {
+  return _TIER_PRI[tier] || 0;
+}
+
+// Tier midpoints live in model-tiers.js (single source of truth, shared
+// with intent-score reconcile) so a decided tier maps to a coherent numeric
+// score for drift math, badges and telemetry.
+const { TIER_MIDPOINT } = require('./model-tiers');
+
+/**
+ * Jev tier override (pure): when a high-confidence Jev verdict disagrees
+ * with the score-derived base tier, the verdict wins either direction.
+ * Score bands remain the fallback (Jev null/low-confidence). Force paths
+ * already returned upstream; agentic floors and risk lifts apply after.
+ * @returns {null | {tier, score}} — score is the tier midpoint for coherence.
+ */
+function jevTierOverride({ baseTier, jevTier, jevConfidence } = {}) {
+  if (!baseTier || !_pri(baseTier)) return null;
+  if (!jevTier || !_pri(jevTier)) return null;
+  if (typeof jevConfidence !== 'number' || jevConfidence < JEV_PROMOTE_CONFIDENCE) return null;
+  if (_pri(jevTier) === _pri(baseTier)) return null;
+  return { tier: jevTier, score: TIER_MIDPOINT[jevTier] ?? null };
+}
+
+/**
+ * Shortfall floor target (pure; called by the router after shortfall).
+ * A high-confidence Jev tier is a measured verdict — cheapest-covering must
+ * not demote below the stronger of (scored legacy pick, Jev verdict).
+ * @returns {string|null} floor tier, or null when no floor applies.
+ */
+function jevFloorTarget({ selectedTier, legacyTier, jevTier, jevConfidence } = {}) {
+  if (typeof jevConfidence !== 'number' || jevConfidence < JEV_PROMOTE_CONFIDENCE) return null;
+  if (!jevTier || !_pri(jevTier)) return null;
+  const floor = _pri(legacyTier) >= _pri(jevTier) ? legacyTier : jevTier;
+  if (!floor || !( _pri(selectedTier) < _pri(floor))) return null;
+  return floor;
+}
+
+/**
+ * Risk corroboration lift (pure; escalate-only, one band).
+ * @returns {string|null} lifted tier, or null when no lift applies.
+ */
+function jevRiskLift({ tier, risky, riskLevel } = {}) {
+  if (tier !== 'SIMPLE' && tier !== 'MEDIUM') return null;
+  if (typeof risky !== 'number' || risky < JEV_RISK_CUT) return null;
+  if (riskLevel === 'high') return null; // keyword path owns high risk
+  return tier === 'SIMPLE' ? 'MEDIUM' : 'COMPLEX';
+}
+
+module.exports = {
+  JEV_ENDPOINT,
+  JEV_MODEL,
+  JEV_TIMEOUT_MS,
+  JEV_PROMOTE_CONFIDENCE,
+  JEV_RISK_CUT,
+  TIER_CRITERIA_V1,
+  CRITERIA_HASH,
+  VALID_TIERS,
+  getApiKey,
+  buildJevState,
+  evaluateJev,
+  classifyJev,
+  jevFloorTarget,
+  jevRiskLift,
+  jevTierOverride,
+  TIER_MIDPOINT,
+  _clearCache,
+};

package/src/routing/model-tiers.js

@@ -46,6 +46,13 @@ const TIER_DEFINITIONS = {
   },
 };
 
+// Midpoint of each tier band: the score a decision carries when only the
+// tier is known (reconcile caps, Jev overrides, badges). Single source of
+// truth — intent-score and jev-router import this rather than keeping
+// private copies that can drift (midpoints must stay inside the bands
+// above, including calibrated overrides).
+const TIER_MIDPOINT = { SIMPLE: 10, MEDIUM: 35, COMPLEX: 63, REASONING: 88 };
+
 class ModelTierSelector {
   constructor() {
     this.tierConfig = null;
@@ -147,6 +154,11 @@ class ModelTierSelector {
   getTier(complexityScore) {
     const score = Math.max(0, Math.min(100, complexityScore || 0));
     const ranges = this.ranges || this._defaultRanges();
+    // First match wins in TIER_DEFINITIONS order (SIMPLE, MEDIUM, COMPLEX,
+    // REASONING). Calibrated ranges can overlap (observed: MEDIUM [20,50] vs
+    // COMPLEX [30,75]) — in the overlap the EARLIER tier wins, so the
+    // effective COMPLEX floor is 51, not 30. Keep this in mind when reading
+    // data/calibrated-thresholds.json.
     for (const tier of Object.keys(TIER_DEFINITIONS)) {
       const [lo, hi] = ranges[tier];
       if (score >= lo && score <= hi) return tier;
@@ -354,6 +366,8 @@ class ModelTierSelector {
         return config.baidu?.model || null;
       case 'fireworks':
         return config.fireworks?.model || null;
+      case 'orcarouter':
+        return config.orcarouter?.model || null;
       case 'codex':
         return config.codex?.model || null;
       case 'vertex':
@@ -519,4 +533,5 @@ module.exports = {
   getModelTierSelector,
   reloadCalibratedThresholds,
   TIER_DEFINITIONS,
+  TIER_MIDPOINT,
 };

package/src/routing/passthrough-route.js

@@ -0,0 +1,286 @@
+/**
+ * Tier-driven model selection for the OAuth subscription passthrough.
+ *
+ * Context: when a picked tier resolves to `azure-anthropic` for a first-party
+ * subscription client, src/api/router.js forwards the request byte-for-byte
+ * to api.anthropic.com — serving whatever model the CLIENT chose. Tier picks
+ * (COMPLEX/sonnet, REASONING/opus, force keywords) were computed and then
+ * silently discarded, so escalation could never fire.
+ *
+ * This module decides the model the passthrough should ACTUALLY serve. The
+ * subscription is not model-locked (the same OAuth token serves Haiku, Sonnet
+ * and Opus), so rewriting `body.model` to a tier-configured Claude model is
+ * accepted upstream. Only the `model` field is ever rewritten — messages,
+ * tools, system prompt, thinking blocks and cache_control breakpoints pass
+ * through verbatim, which is what keeps Anthropic's prefix cache usable
+ * across the switch (same bytes, new model = one cold-prefix turn, then warm).
+ *
+ * Rules (first match wins):
+ *   1. Kill-switch: LYNKR_PASSTHROUGH_MODEL_ROUTING=false → verbatim always.
+ *   2. Side-channel tiers (suggestion/autocomplete/bare/drift frames routed to
+ *      static SIMPLE) → verbatim. Never spend Opus on harness wrapper text.
+ *   3. Unknown client model or unrankable tier model → verbatim (fail-closed).
+ *   4. Tier model outranks client model → upgrade to the tier model, with one
+ *      exception (rule 4a): stepping DOWN from a higher pin (pin Opus, fresh
+ *      verdict Sonnet) consults the downgrade gate for the pin→tier move. A
+ *      warm Opus prefix survives a Sonnet verdict when break-even blocks;
+ *      genuine upgrades (no higher pin, or pin at/below the tier) fire
+ *      ungated — correctness beats one cold turn, same policy as the normal
+ *      flow's hard triggers (cache-switch-cost.js scope: escalations are
+ *      never gated). Without 4a every Opus→Sonnet transition destroyed the
+ *      warm prefix with no math.
+ *   5. Pinned (previously served) model outranks client model → downgrade
+ *      gate: hold the pin (pin_hold) ONLY while real warmth is at stake —
+ *      cacheState present, fresh (not TTL-cold), recorded for this same
+ *      model, and warmPrefixTokens >= HOLD_MIN_PREFIX_TOKENS (2000). Otherwise
+ *      allow the downgrade (nothing warm worth protecting). This is the
+ *      normal flow's break-even philosophy ported to a flat subscription:
+ *      dollars can't justify holding (marginal cost is $0), but a large warm
+ *      prefix is paid latency on every switch, so a large fresh one protects
+ *      the pin while a cold/small/absent one doesn't.
+ *   6. Otherwise → verbatim. A client that explicitly chose Opus keeps Opus
+ *      even on a SIMPLE-scored turn.
+ *
+ * Pure functions, no I/O. Never throws.
+ */
+
+const FAMILY_RANK = [
+  { re: /opus/i, rank: 3 },
+  { re: /sonnet/i, rank: 2 },
+  { re: /haiku/i, rank: 1 },
+];
+
+/**
+ * Rank a Claude model id by family. Works on short aliases
+ * (claude-sonnet-4-5), dated ids (claude-haiku-4-5-20251001) and
+ * provider-prefixed forms. Returns null for anything unrecognized so
+ * callers fail closed to verbatim passthrough.
+ */
+function familyRank(modelId) {
+  if (!modelId || typeof modelId !== 'string') return null;
+  for (const f of FAMILY_RANK) {
+    if (f.re.test(modelId)) return f.rank;
+  }
+  return null;
+}
+
+function isRoutingEnabled() {
+  // Default ON. Set LYNKR_PASSTHROUGH_MODEL_ROUTING=false to restore pure
+  // byte-for-byte passthrough (pre-routing behavior).
+  return process.env.LYNKR_PASSTHROUGH_MODEL_ROUTING !== 'false';
+}
+
+function isSideTier(tier) {
+  if (!tier || typeof tier !== 'object') return false;
+  return tier.pinned === false && String(tier.method || '').startsWith('side_request');
+}
+
+// Warm-prefix floor for the downgrade hold (rule 5). Deliberately a
+// constant, not an env knob: one fewer dial, same protection. At/above this
+// many warm tokens the pin holds across lower-scored turns; below it (or
+// cold/absent/stale) the tier falls straight back.
+const HOLD_MIN_PREFIX_TOKENS = 2000;
+
+function holdMinPrefixTokens() {
+  return HOLD_MIN_PREFIX_TOKENS;
+}
+
+/**
+ * Resolve the effective tier model for dispatch (pure).
+ *
+ * A tier object can arrive with a weaker model than its label promises:
+ * model-swapping overrides (kNN/bandit) keep the tier label while serving
+ * cheaper, the no_user_messages fallback historically carried null, and
+ * stale pins replay both shapes indefinitely. On the orchestrator path
+ * those dynamics have dollar logic behind them; on the flat-fee
+ * subscription passthrough a demotion saves $0 and only risks quality —
+ * so here the label wins ties: effective model = max(tierModel,
+ * configured(tier)) by family rank. Promotions (stronger-than-configured,
+ * e.g. a held Opus on a COMPLEX tier) always survive.
+ *
+ * @param {object} args
+ * @param {string|null} args.tierName - tier label ('COMPLEX', ...)
+ * @param {string|null} args.tierModel - model carried on the tier object
+ * @param {function|null} args.selectModelFn - (tier) => {model} | null
+ * @returns {{model:string|null, resolved:boolean}} resolved=true when the
+ *   configured model replaced the carried one.
+ */
+function resolveTierModel({ tierName = null, tierModel = null, selectModelFn = null } = {}) {
+  try {
+    let configured = null;
+    try {
+      configured = (typeof selectModelFn === 'function' && tierName)
+        ? selectModelFn(tierName)?.model || null
+        : null;
+    } catch { configured = null; }
+    const rT = familyRank(tierModel);
+    const rC = familyRank(configured);
+    if (rC !== null && (rT === null || rC > rT)) {
+      return { model: configured, resolved: true };
+    }
+    return { model: tierModel ?? null, resolved: false };
+  } catch {
+    return { model: tierModel ?? null, resolved: false };
+  }
+}
+
+/**
+ * Downgrade gate (rule 5): is there enough live warmth to justify holding
+ * the pinned model instead of following the fresh lower tier down?
+ * Mirrors cache-switch-cost.js staleness/TTL handling: stale-model state,
+ * TTL-cold state, absent state and small prefixes all allow the downgrade
+ * without further math.
+ *
+ * Above the trivial floor, the decision is dollar break-even via the SAME
+ * evaluator the normal flow uses: holding Opus to "save" a re-read is only
+ * rational when the re-read costs more than the per-turn premium over the
+ * session's expected remaining turns. With Opus ~5x Haiku on output
+ * (registry: $25/M vs $5/M) the break-even typically clears in ~1-2 turns,
+ * so holds are rare by design — surviving only when the session is nearly
+ * over (nothing to amortize a rebuild over), quota pressure has shortened
+ * the horizon to ~nothing, or pricing is unknown (fail toward the hold).
+ *
+ * @param {string|null} pinModel - currently serving (pinned) model
+ * @param {object|null} cacheState - sessionAffinity.getCacheState(sessionId)
+ * @param {object} [opts]
+ * @param {string|null} [opts.downgradeModel] - model a downgrade would serve
+ * @param {number|null} [opts.remainingTurns] - expected turns left (null → evaluator default)
+ * @param {number|null} [opts.sessionBurnPressure] - 0..1 quota pressure,
++ *   threaded into evaluateSwitch (null/0 = untouched horizon)
+ * @param {function|null} [opts.evaluateSwitch] - injectable evaluator (tests)
+ */
+function shouldHoldForCache(pinModel, cacheState, opts = {}) {
+  if (!cacheState || typeof cacheState !== 'object') return null;
+  if (cacheState.cold) return { hold: false, reason: 'downgrade_cache_cold' };
+  if (cacheState.model && pinModel && cacheState.model !== pinModel) {
+    return { hold: false, reason: 'downgrade_cache_stale' };
+  }
+  const warm = Number(cacheState.warmPrefixTokens) || 0;
+  if (warm < holdMinPrefixTokens()) {
+    return { hold: false, reason: 'downgrade_prefix_small', warmPrefixTokens: warm };
+  }
+  try {
+    const evaluate = opts.evaluateSwitch
+      || require('./cache-switch-cost').evaluateSwitch;
+    const ev = evaluate({
+      cacheState,
+      current: { provider: cacheState.provider || 'azure-anthropic', model: pinModel },
+      target: { provider: cacheState.provider || 'azure-anthropic', model: opts.downgradeModel || null },
+      expectedRemainingTurns: opts.remainingTurns ?? null,
+      ...(opts.sessionBurnPressure != null ? { sessionBurnPressure: opts.sessionBurnPressure } : {}),
+    });
+    if (ev && ev.switchAllowed) {
+      return {
+        hold: false,
+        reason: 'downgrade_break_even_cleared',
+        warmPrefixTokens: warm,
+        breakEvenTurns: ev.breakEvenTurns ?? null,
+        expectedRemainingTurns: ev.expectedRemainingTurns ?? null,
+      };
+    }
+    return {
+      hold: true,
+      reason: 'hold_break_even_blocked',
+      warmPrefixTokens: warm,
+      breakEvenTurns: ev && ev.breakEvenTurns !== undefined ? ev.breakEvenTurns : null,
+      expectedRemainingTurns: ev && ev.expectedRemainingTurns !== undefined ? ev.expectedRemainingTurns : null,
+    };
+  } catch {
+    return { hold: true, reason: 'hold_evaluator_failed', warmPrefixTokens: warm };
+  }
+}
+
+/**
+ * @param {object} args
+ * @param {string|null} args.tierModel - model from the picked tier's config
+ * @param {string|null} args.clientModel - req.body.model (what the client asked for)
+ * @param {string|null} [args.pinModel] - model recorded on the session pin (previously served)
+ * @param {string|null} [args.tierMethod] - tier.method (side-channel detection)
+ * @param {boolean|null} [args.tierPinned] - tier.pinned flag
+ * @param {object|null} [args.cacheState] - sessionAffinity.getCacheState(sessionId):
+ *   {warmPrefixTokens, provider, model, lastRequestAt, ttlMs, cold} or null.
+ *   Caller (router fork) loads it; kept out of here so this stays pure.
+ * @param {number|null} [args.remainingTurns] - expected turns left, for the
+ *   break-even gate (null → evaluator default). Caller loads via telemetry.
+ * @param {number|null} [args.sessionBurnPressure] - 0..1 quota pressure,
+ *   threaded into both gate calls (null/0 = untouched horizon).
+ * @param {function|null} [args.evaluateSwitch] - injectable evaluator (tests).
+ * @returns {{model:string|null, action:'verbatim'|'upgrade'|'pin_hold', reason:string, warmPrefixTokens:number|null}}
+ */
+function decidePassthroughModel({ tierModel = null, clientModel = null, pinModel = null, tierMethod = null, tierPinned = null, cacheState = null, remainingTurns = null, sessionBurnPressure = null, evaluateSwitch = null } = {}) {
+  try {
+    if (!isRoutingEnabled()) {
+      return { model: clientModel, action: 'verbatim', reason: 'routing_disabled', warmPrefixTokens: null };
+    }
+    if (isSideTier({ method: tierMethod, pinned: tierPinned })) {
+      return { model: clientModel, action: 'verbatim', reason: 'side_request', warmPrefixTokens: null };
+    }
+    const clientRank = familyRank(clientModel);
+    if (clientRank === null) {
+      return { model: clientModel, action: 'verbatim', reason: 'unknown_client_model', warmPrefixTokens: null };
+    }
+    const tierRank = familyRank(tierModel);
+    const pinRank = familyRank(pinModel);
+    if (tierRank !== null && tierRank > clientRank) {
+      // Rule 4a — the upgrade branch can also be a step DOWN from the pin
+      // (pin Opus, fresh verdict Sonnet, client Haiku). Consult the gate for
+      // the pin→tier move instead of destroying warmth unexamined.
+      if (pinRank !== null && pinRank > tierRank) {
+        const gate = shouldHoldForCache(pinModel, cacheState, {
+          downgradeModel: tierModel,
+          remainingTurns,
+          sessionBurnPressure,
+          ...(evaluateSwitch ? { evaluateSwitch } : {}),
+        });
+        if (gate && gate.hold) {
+          return { model: pinModel, action: 'pin_hold', reason: gate.reason, warmPrefixTokens: gate.warmPrefixTokens ?? null };
+        }
+      }
+      return { model: tierModel, action: 'upgrade', reason: 'tier_outranks_client', warmPrefixTokens: null };
+    }
+    if (pinRank !== null && pinRank > clientRank) {
+      const gate = shouldHoldForCache(pinModel, cacheState, {
+        downgradeModel: clientModel,
+        remainingTurns,
+        sessionBurnPressure,
+        ...(evaluateSwitch ? { evaluateSwitch } : {}),
+      });
+      if (gate && gate.hold) {
+        return { model: pinModel, action: 'pin_hold', reason: gate.reason, warmPrefixTokens: gate.warmPrefixTokens ?? null };
+      }
+      return {
+        model: clientModel,
+        action: 'verbatim',
+        reason: gate ? gate.reason : 'downgrade_no_cache_state',
+        warmPrefixTokens: (gate && gate.warmPrefixTokens) ?? null,
+      };
+    }
+    return { model: clientModel, action: 'verbatim', reason: 'no_upgrade', warmPrefixTokens: null };
+  } catch {
+    return { model: clientModel ?? null, action: 'verbatim', reason: 'error_fail_closed', warmPrefixTokens: null };
+  }
+}
+
+/**
+ * Badge text for a passthrough turn (pure — unit-tested, used by router.js).
+ * Three marked variants plus the plain no-op:
+ *   upgrade  → +route  (model rewritten up)
+ *   pin_hold → +hold   (model rewritten to the held pin, with gate reason)
+ *   verbatim + downgrade_* reason → −stepdown (gate-approved descent)
+ *   otherwise → plain passthrough (true no-op: no_upgrade, side_request…)
+ */
+function buildPassthroughBadge({ action = null, reason = null, routeModel = null, clientModel = null, tierName = null, servedModel = null } = {}) {
+  if (action === 'upgrade' && routeModel) {
+    return `*[Lynkr] subscription-passthrough+route → ${routeModel} (client: ${clientModel || '—'}) · ${tierName || '—'}*`;
+  }
+  if (action === 'pin_hold' && routeModel) {
+    return `*[Lynkr] subscription-passthrough+hold → ${routeModel} (client: ${clientModel || '—'}) · ${tierName || '—'} (${reason || 'cache'})*`;
+  }
+  if (action === 'verbatim' && typeof reason === 'string' && reason.startsWith('downgrade_')) {
+    return `*[Lynkr] subscription-passthrough−stepdown → ${servedModel || '—'} (azure-anthropic) · ${tierName || '—'} (${reason})*`;
+  }
+  return `*[Lynkr] subscription-passthrough → ${servedModel || '—'} (azure-anthropic)*`;
+}
+
+module.exports = { familyRank, isRoutingEnabled, isSideTier,   decidePassthroughModel,
+  resolveTierModel, shouldHoldForCache, holdMinPrefixTokens, buildPassthroughBadge };