lynkr 9.14.12 → 9.14.13

package/src/routing/cache-switch-cost.js

@@ -61,12 +61,23 @@ function _cfg() {
  * @param {number} [args.outputTokensPerTurn] - est. output tokens per turn.
  * @param {number|null} [args.expectedRemainingTurns] - median remaining
  *   turns; falls back to the conservative config default when null.
+ * @param {number|null} [args.sessionBurnPressure] - 0..1 quota pressure from
+ *   quota-ledger.js (sustained expensive serving on a flat subscription).
+ *   Enables a parallel QUOTA break-even leg: while dollar math prices the
+ *   rebuild in USD, quota math prices it in ledger units (model weight ×
+ *   tokens, Haiku = 1.0). Either leg clearing allows the switch, so high
+ *   burn opens descents the dollar leg alone would hold. Null/0 disables
+ *   the quota leg entirely — pure dollar behavior, byte-for-byte backward
+ *   compatible. Upgrades never route through this gate, so pressure can
+ *   only accelerate descents, never block capability.
  * @param {Object} [args.deps] - test injection: {resolveCacheEconomics}.
  * @returns {{
  *   switchAllowed: boolean,
  *   reason: string,
  *   breakEvenTurns: number|null,
  *   expectedRemainingTurns: number,
+ *   quotaBreakEvenTurns: number|null,
+ *   burnPressureApplied: number,
  *   warmPrefixTokens: number,
  *   switchOnceUsd: number|null,
  *   stayPerTurnUsd: number|null,
@@ -81,18 +92,24 @@ function evaluateSwitch({
   newTokensPerTurn,
   outputTokensPerTurn,
   expectedRemainingTurns,
+  sessionBurnPressure = null,
   deps = {},
 } = {}) {
   const cfg = _cfg();
   const remaining = Number.isFinite(expectedRemainingTurns) && expectedRemainingTurns > 0
     ? expectedRemainingTurns
     : cfg.defaultRemainingTurns;
+  const burnPressure = Number.isFinite(sessionBurnPressure)
+    ? Math.max(0, Math.min(1, sessionBurnPressure))
+    : 0;
 
   const base = {
     switchAllowed: true,
     reason: 'no_cache_state',
     breakEvenTurns: null,
     expectedRemainingTurns: remaining,
+    quotaBreakEvenTurns: null,
+    burnPressureApplied: burnPressure,
     warmPrefixTokens: cacheState?.warmPrefixTokens ?? 0,
     switchOnceUsd: null,
     stayPerTurnUsd: null,
@@ -174,19 +191,46 @@ function evaluateSwitch({
   const breakEvenTurns = switchOnce / savingsPerTurn;
   const allowed = breakEvenTurns <= remaining;
 
+  // Quota leg (flat subscriptions): re-run the same break-even in ledger
+  // units when the session is burning. Model weight = (input+output $/M) /
+  // Haiku baseline — quota burn tracks price ratios, which is exactly what
+  // the ledger records. A rebuild that never pays in dollars can still pay
+  // in runway when every held turn burns 5x the units a descent would.
+  let quotaBreakEvenTurns = null;
+  let quotaAllowed = false;
+  if (burnPressure > 0) {
+    const wCur = (econCur.inputPerM + econCur.outputPerM) / 6;
+    const wTgt = (econTgt.inputPerM + econTgt.outputPerM) / 6;
+    if (wCur > wTgt) {
+      const perTurnTokens = (W + N + O) / 1000;
+      const quotaSavingsPerTurn = perTurnTokens * (wCur - wTgt);
+      if (quotaSavingsPerTurn > 0) {
+        quotaBreakEvenTurns = ((W + N) / 1000) * wTgt / quotaSavingsPerTurn;
+        quotaAllowed = quotaBreakEvenTurns <= remaining;
+      }
+    }
+  }
+  const finalAllowed = allowed || quotaAllowed;
+
   logger.debug({
     current: `${current.provider}:${current.model}`,
     target: `${target.provider}:${target.model}`,
     warmPrefixTokens: W,
     breakEvenTurns: Number(breakEvenTurns.toFixed(2)),
     expectedRemainingTurns: remaining,
+    quotaBreakEvenTurns: quotaBreakEvenTurns === null ? null : Number(quotaBreakEvenTurns.toFixed(2)),
+    burnPressureApplied: burnPressure,
     allowed,
+    quotaAllowed,
   }, '[CacheSwitchCost] break-even evaluated');
 
   return {
     ...priced,
-    switchAllowed: allowed,
-    reason: allowed ? 'break_even_cleared' : 'break_even_blocked',
+    quotaBreakEvenTurns,
+    switchAllowed: finalAllowed,
+    reason: finalAllowed
+      ? (allowed ? 'break_even_cleared' : 'quota_break_even_cleared')
+      : 'break_even_blocked',
     breakEvenTurns,
   };
 }

package/src/routing/complexity-analyzer.js

@@ -104,16 +104,28 @@ const FORCE_REASONING_PATTERNS = [
   /\b(prove|proof|formal\s+proof|verify|verification)\b/i,
   /\b(from\s+first\s+principles)\b/i,
   /\b(reason\s+(through|about|from)\s+(the|this))/i,
+  // Frontier planning: asking FOR a plan/strategy/design of technical work
+  // (not asking about one). Two-sided lookahead — a plan word AND a technical
+  // scope word must both be present, so "plan my vacation", "lesson plan"
+  // and "business plan" stay quiet while "give me a plan to refactor X",
+  // "draft an RFC to redesign Y" and "migration strategy for Z" escalate.
+  // Deliberately excludes bare "give me a plan" (nothing technical to plan)
+  // and generic nouns (module/api/database) that misfire on non-technical
+  // asks. Known overlap: "explain the deployment plan" fires — accepted,
+  // deployment planning benefits from the strong model anyway.
+  /(?=.*\b(plans?|roadmaps?|strateg(y|ies)|blueprints?|proposals?|rfcs?|design\s+docs?)\b)(?=.*\b(refactor\w*|implement\w*|migrat\w+|architect\w+|redesign\w*|restructur\w+|rewrit\w+|overhaul\w*|codebases?|infrastructure|pipelines?|deploy\w*|systems?)\b)/i,
 ];
 
 // Force COMPLEX patterns - route to COMPLEX (GLM in config B) regardless of
 // score. Architecture/refactor/code-review are substantial but not
 // security-critical, so GLM is appropriate.
 const FORCE_CLOUD_PATTERNS = [
-  /\b(architect(ure)?\s+(review|design|diagram)|system\s+design)\b/i,
+  /\b(architect\w*\s+(review|design|diagram)|system\s+design)\b/i,
   /\b(refactor\s+(entire|whole|all|the\s+entire)|complete\s+rewrite)\b/i,
   /\b(code\s+review|pr\s+review|pull\s+request\s+review)\b/i,
-  /\b(debug(ging)?\s+(complex|difficult|hard|tricky))\b/i,
+  // "debug this tricky race" reads naturally but the adjectives rarely sit
+  // adjacent to the verb, so up to two words may intervene.
+  /\bdebug(?:ging)?\s+(?:\w+\s+){0,2}(complex|difficult|hard|tricky)\b/i,
   /\b(production\s+(issue|bug|incident|outage))\b/i,
 ];
 
@@ -655,8 +667,13 @@ function calculateWeightedScore(payload, content) {
   const avgLength = content.length / Math.max(sentences.length, 1);
   dimensions.promptComplexity = Math.min(avgLength / 2, 100);
 
-  // 3. Technical depth (keyword density)
-  const techMatches = (content.match(PATTERNS.technical) || []).length;
+  // 3. Technical depth (keyword density). NOTE: uses a local global-flag
+  // copy — the shared PATTERNS.technical must stay flag-less because .test()
+  // callers above depend on stateless matching (a shared /g regex carries
+  // lastIndex between calls). String.match with a non-global regex returns
+  // at most one hit, which used to cap this dimension at 15 regardless of
+  // density and starved COMPLEX-tier scores of their strongest signal.
+  const techMatches = (content.match(new RegExp(PATTERNS.technical.source, 'gi')) || []).length;
   dimensions.technicalDepth = Math.min(techMatches * 15, 100);
 
   // 4. Domain specificity (how many domains are touched)

package/src/routing/index.js

@@ -805,6 +805,17 @@ function checkSessionPin(payload, options = {}) {
   const guards = _runPinGuards(payload, pin);
   if (!guards.ok) return { serve: false, pin, sessionId, reason: guards.reason };
 
+  // Tier-less pins (legacy cache-only rows predating the session_cache_state
+  // split) must not drive tier decisions: drift math on a null tier never
+  // fires, so serving them locks the session with no escalation path.
+  // Exempted when ANY tool blocks exist anywhere in the payload: an
+  // unresolved tool_use breaks if the provider switches, so provider
+  // stickiness wins there (same safety rationale as the tool_history path
+  // above, which returns before reaching this check).
+  if (!pin.tier && !_payloadHasAnyToolBlocks(payload)) {
+    return { serve: false, pin, sessionId, reason: 'tierless_pin' };
+  }
+
   if (refreshOk) {
     sessionAffinity.setPin(sessionId, pin, {
       messageCount: Math.max(messageCount, pin.messageCount ?? 0),
@@ -1095,6 +1106,11 @@ async function _determineProviderSmartInner(payload, options = {}) {
       analysis.score = intent.score;
       analysis.scoreMode = intent.mode; // 'anchor' | 'lexical' (clean-text fallback)
       analysis.anchorClass = intent.class ?? null;
+      // Jev verdict rides alongside the score so the shortfall floor,
+      // risk corroboration and telemetry can consume it downstream.
+      // Null unless the Jev leg ran (pinned serves, side frames and
+      // classifier skips leave no verdict — same as classifierResult).
+      if (intent.jev && typeof intent.jev === 'object') analysis.jev = intent.jev;
       intentScored = true;
       logger.debug({
         score: intent.score,
@@ -1213,12 +1229,47 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // (agentic minTier, context, vision, kNN-ambiguous) for telemetry.
   let baseTier = null;
   const escalations = [];
+  let _jevOverrode = false;
   if (config.modelTiers?.enabled) {
     try {
       const selector = getModelTierSelector();
       tier = selector.getTier(analysis.score);
       baseTier = tier;
 
+      // Jev tier override: a high-confidence measured verdict replaces the
+      // score-band tier in either direction (score bands stay the fallback
+      // for Jev-null/low-confidence). Runs BEFORE agentic floors and risk
+      // lifts so structural guarantees can still lift above the verdict —
+      // never below it. Score is set to the tier midpoint so drift math,
+      // badges and telemetry stay coherent with the decided tier.
+      try {
+        const { jevTierOverride } = require('./jev-router');
+        const _ov = jevTierOverride({
+          baseTier,
+          jevTier: analysis.jev?.tier,
+          jevConfidence: analysis.jev?.confidence,
+        });
+        if (_ov) {
+          escalations.push({
+            source: 'jev_override',
+            fromTier: tier,
+            toTier: _ov.tier,
+            fromModel: null,
+            toModel: null,
+          });
+          logger.debug({
+            fromTier: tier,
+            toTier: _ov.tier,
+            jevConfidence: analysis.jev?.confidence ?? null,
+          }, '[Routing] Jev tier override');
+          tier = _ov.tier;
+          if (typeof _ov.score === 'number') analysis.score = _ov.score;
+          _jevOverrode = true;
+        }
+      } catch (err) {
+        degradation.record('tier_select', err);
+      }
+
       // Check if agentic detection requires a higher tier
       if (agenticResult?.minTier) {
         const agenticTierPriority = TIER_DEFINITIONS[agenticResult.minTier]?.priority || 0;
@@ -1237,6 +1288,30 @@ async function _determineProviderSmartInner(payload, options = {}) {
         }
       }
 
+      // Jev risk corroboration (escalate-only): a high Noul on auth /
+      // secrets / production / destructive content lifts SIMPLE/MEDIUM one
+      // band when the keyword analyzer stayed quiet. Never clears a keyword
+      // hit (that path returned far above), never jumps two bands, never
+      // fires without a verdict (fail-soft null skips silently). Mirrors the
+      // kNN-ambiguous escalate pattern with a ledger entry.
+      try {
+        const { jevRiskLift } = require('./jev-router');
+        const _lifted = jevRiskLift({ tier, risky: analysis.jev?.risky, riskLevel: risk?.level });
+        if (_lifted) {
+          escalations.push({
+            source: 'jev_risk',
+            fromTier: tier,
+            toTier: _lifted,
+            fromModel: null,
+            toModel: null,
+          });
+          logger.debug({ fromTier: tier, toTier: _lifted, risky: analysis.jev.risky }, '[Routing] Jev risk corroboration — one-band lift');
+          tier = _lifted;
+        }
+      } catch (err) {
+        degradation.record('tier_select', err);
+      }
+
       // Select model for the tier (will be applied after provider selection)
       analysis.tier = tier;
     } catch (err) {
@@ -1247,7 +1322,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // Apply routing decision based on tier config (TIER_* env vars take precedence
   // but Phase 1.2 lets the cost-optimizer pick a cheaper qualifying model when safe).
   let provider;
-  let method = 'tier_config';
+  let method = _jevOverrode ? 'tier_config+jev_override' : 'tier_config';
   let costOptimized = false;
 
   const selector = getModelTierSelector();
@@ -1342,6 +1417,51 @@ async function _determineProviderSmartInner(payload, options = {}) {
     degradation.record('shortfall', err);
   }
 
+  // Jev shortfall floor: a high-confidence Jev tier is a measured verdict,
+  // not a heuristic guess — cheapest-covering must not demote below it.
+  // Floor target is the stronger of (scored legacy pick, Jev verdict):
+  // score-derived highs are never talked down by the judge, and judged
+  // highs are never talked down by the price optimizer (see jevFloorTarget).
+  // De-escalation below still runs after this, so evidence gates apply like
+  // any other decision.
+  try {
+    const { jevFloorTarget } = require('./jev-router');
+    const _floorTier = shortfallInfo && shortfallInfo.legacy
+      ? jevFloorTarget({
+        selectedTier: tier,
+        legacyTier: shortfallInfo.legacy.tier,
+        jevTier: analysis.jev?.tier,
+        jevConfidence: analysis.jev?.confidence,
+      })
+      : null;
+    if (_floorTier) {
+      const _floorSel = selector.selectModel(_floorTier, null);
+      if (_floorSel && _floorSel.provider && _floorSel.model) {
+        const _fromTier = tier;
+        const _fromModel = selectedModel;
+        provider = _floorSel.provider;
+        selectedModel = _floorSel.model;
+        tier = _floorTier;
+        analysis.tier = tier;
+        method = method + '+jev_floor_hold';
+        escalations.push({
+          source: 'jev_floor',
+          fromTier: _fromTier,
+          toTier: tier,
+          fromModel: _fromModel,
+          toModel: selectedModel,
+        });
+        logger.info({
+          from: `${_fromTier}:${_fromModel}`,
+          to: `${tier}:${selectedModel}`,
+          jevConfidence: analysis.jev?.confidence ?? null,
+        }, '[Routing] Jev floor hold — shortfall demotion refused');
+      }
+    }
+  } catch (err) {
+    degradation.record('shortfall', err);
+  }
+
   // WS2.3 — evidence-based de-escalation.
   //
   // The check is intentionally gated by evidence, not a feature flag: the

package/src/routing/intent-score.js

@@ -338,9 +338,8 @@ function _reconcile(anchorScore, anchorClass, classifierResult) {
   const anchorIdx = TIER_ORDER.indexOf(anchorTier);
   const classifierIdx = TIER_ORDER.indexOf(classifierTier);
 
-  // Midpoints of each tier band (from model-tiers.js defaults):
-  //   SIMPLE 0-19 → 10, MEDIUM 20-50 → 35, COMPLEX 51-75 → 63, REASONING 76-100 → 88
-  const TIER_MIDPOINT = { SIMPLE: 10, MEDIUM: 35, COMPLEX: 63, REASONING: 88 };
+  // Midpoints live in model-tiers.js (single source of truth).
+  const { TIER_MIDPOINT } = require('./model-tiers');
 
   if (classifierIdx < anchorIdx) {
     // Classifier says LOWER tier — trust it. Fixes over-routing.
@@ -410,24 +409,47 @@ async function scoreIntent(payload, opts = {}) {
         const [lo, hi] = CLASS_BANDS[cls];
         const anchorScore = Math.max(lo, Math.min(hi, blendScore(sims)));
 
-        // LLM classifier — second opinion. Skipped in tests (opts.skipClassifier)
-        // to keep unit tests hermetic. Runs live otherwise.
+        // Jev routing judge — second opinion. Skipped in tests (opts.skipClassifier)
+        // to keep unit tests hermetic (or stubbed via opts.jevFetchFn). Runs live
+        // otherwise. Replaces the qwen difficulty classifier in the same result
+        // shape ({tier, confidence}) so _reconcile semantics are unchanged;
+        // Jev extras (probabilities, risky, model, criteriaHash) ride along
+        // for telemetry and the shortfall floor. Fail-soft null preserves the
+        // anchor-only path exactly.
+        //
+        // Hermeticity note: suites asserting deterministic routing scrub
+        // TYPESAFE_API_KEY (no key → Jev leg returns null before any fetch),
+        // the same posture as the repo's live-Ollama tolerance. Never gate
+        // on NODE_ENV — .env pins it to production in every context.
         let classifierResult = null;
+        let jevResult = null;
         if (!opts.skipClassifier) {
           try {
-            const { classifyDifficulty } = require('./difficulty-classifier');
-            classifierResult = await classifyDifficulty(text, {
-              forceMatched: opts.forceMatched,
-              riskLevel: opts.riskLevel,
-              // Condensed prior turns, threaded by the router's window loop.
-              // Without it a short follow-up ("Who kills him ?") is
-              // unclassifiable in isolation.
+            const { classifyJev } = require('./jev-router');
+            const msgs = Array.isArray(payload?.messages) ? payload.messages : [];
+            const toolDefs = Array.isArray(payload?.tools) ? payload.tools : [];
+            const toolResults = msgs.filter((m) =>
+              m?.role === 'user' && Array.isArray(m.content) && m.content.some((c) => c?.type === 'tool_result')
+            ).length;
+            const jevFetchFn = opts.jevFetchFn;
+            jevResult = await classifyJev(text, {
               context: typeof payload?._conversationContext === 'string'
                 ? payload._conversationContext
                 : null,
+              signals: {
+                message_count: msgs.length,
+                tools_attached: toolDefs.length,
+                effective_tools: toolDefs.length,
+                has_tool_history: toolResults > 0,
+                session_turn: Math.max(1, Math.ceil(msgs.length / 2)),
+              },
+              fetchFn: jevFetchFn,
             });
+            if (jevResult) {
+              classifierResult = { tier: jevResult.tier, confidence: jevResult.confidence };
+            }
           } catch (err) {
-            logger.debug({ err: err.message }, '[IntentScore] classifier failed — anchor only');
+            logger.debug({ err: err.message }, '[IntentScore] Jev classifier failed — anchor only');
           }
         }
 
@@ -453,6 +475,19 @@ async function scoreIntent(payload, opts = {}) {
           classifierTier: classifierResult?.tier ?? null,
           classifierConfidence: classifierResult?.confidence ?? null,
           reconciled,
+          // Jev verdict details for telemetry + shortfall floor downstream.
+          // Null unless the Jev leg ran (same conditions as classifierResult,
+          // plus LRU-cached repeats which still carry the original extras).
+          jev: jevResult ? {
+            tier: jevResult.tier,
+            confidence: jevResult.confidence,
+            probabilities: jevResult.probabilities ?? null,
+            risky: jevResult.risky ?? null,
+            model: jevResult.model ?? null,
+            criteriaHash: jevResult.criteriaHash ?? null,
+            latencyMs: jevResult.latencyMs ?? null,
+            cached: !!jevResult.cached,
+          } : null,
         });
       }
     }

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,
+};