lynkr 9.14.1 → 9.14.3

package/src/routing/decide.js

@@ -0,0 +1,149 @@
+/**
+ * Routing decision core — the harness-shaped, standalone pieces of the
+ * per-request model decision, extracted from routing/index.js so they can be
+ * consumed by more than one caller:
+ *
+ *   - routing/index.js (the live request path, unchanged behavior)
+ *   - the off-policy evaluator (WS4 follow-up), which must re-derive a
+ *     candidate policy's π(a|x) on logged rows using the exact same context
+ *     vector and candidate-eligibility rules the live policy used
+ *   - a future remote decision endpoint, which needs decide-shaped logic
+ *     that doesn't reach into request/response plumbing
+ *
+ * Deliberately excluded: session pins, the escalation ladder, kNN confidence
+ * branching, deadline/tenant overrides. Those are decision *inputs and
+ * post-passes* owned by the caller; this module owns only "given a context
+ * and a candidate set, pick one and report the probability of that pick."
+ *
+ * Nothing here catches errors — callers keep their existing
+ * degradation.record() wrapping so failure accounting stays where it was.
+ */
+
+const { getBandit } = require('./bandit');
+
+/**
+ * Task-type one-hot vocabulary. Order is load-bearing: it defines feature
+ * indices 6..11 of the context vector, and every persisted bandit arm was
+ * trained against this order. Do not reorder or insert — append only, and
+ * only together with a bandit-state migration.
+ */
+const TASK_TYPES = ['code_gen', 'summarization', 'reasoning', 'factoid', 'chat', 'other'];
+
+/**
+ * Build the 12-dim context vector the bandit (and any off-policy estimator
+ * replaying its decisions) scores against.
+ *
+ * Layout: [score, log-tokens, has-tools, streaming, risk, agentic,
+ *          ...one-hot task type (6)].
+ *
+ * @param {object} args
+ * @param {object} args.analysis — complexity analysis ({ score, breakdown })
+ * @param {object} [args.payload] — request payload (for tools presence)
+ * @param {object} [args.options] — routing options (for streaming flag)
+ * @param {object} [args.risk] — risk analysis ({ level })
+ * @param {object} [args.agenticResult] — agentic detection ({ isAgentic })
+ * @returns {number[]} 12-dim feature vector
+ */
+function buildContextVector({ analysis, payload, options, risk, agenticResult }) {
+  const inferredTask = (analysis?.breakdown?.taskType?.reason || 'other').toLowerCase();
+  const taskIdx = Math.max(0, TASK_TYPES.findIndex(t => inferredTask.includes(t)));
+  return [
+    (analysis?.score || 0) / 100,
+    Math.log(Math.max(1, analysis?.breakdown?.tokenCount || 0) + 1) / 15,
+    ((payload?.tools?.length ?? 0) > 0) ? 1 : 0,
+    options?.streaming ? 1 : 0,
+    risk?.level === 'high' ? 1 : risk?.level === 'medium' ? 0.5 : 0,
+    agenticResult?.isAgentic ? 1 : 0,
+    ...TASK_TYPES.map((_, i) => i === taskIdx ? 1 : 0),
+  ];
+}
+
+/**
+ * Build the bandit's candidate set: the current selection plus the kNN
+ * alternative, if it differs AND is configured in some TIER_* entry.
+ *
+ * Tier-aware filter: the bandit may explore freely across the user's
+ * configured tiers (e.g. swap a SIMPLE request to the COMPLEX-tier model),
+ * but never pick a credentialed-but-untiered model (e.g. an Azure deployment
+ * present in .env for another purpose but referenced by no TIER_*). Tier
+ * routing stays the source of truth for eligibility.
+ *
+ * @param {{ provider: string, model: string }} current
+ * @param {{ provider: string, model: string }|null} alternative
+ * @returns {Array<{ provider: string, model: string }>}
+ */
+function buildCandidates(current, alternative) {
+  const candidates = [{ provider: current.provider, model: current.model }];
+  if (alternative && alternative.model && alternative.model !== current.model) {
+    const configured = require('./model-tiers').getModelTierSelector().getAllConfiguredModels();
+    const inConfig = configured.some(
+      m => m.provider === alternative.provider && m.model === alternative.model
+    );
+    if (inConfig) {
+      candidates.push({ provider: alternative.provider, model: alternative.model });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * The decision core: given a tier, a candidate set, and a context vector,
+ * have the bandit pick one and report the pick's propensity.
+ *
+ * Returns null when there's nothing to adjudicate (fewer than 2 candidates)
+ * or the bandit declined — callers keep their pre-existing selection.
+ *
+ * @param {string} tier
+ * @param {Array<{ provider, model }>} candidates
+ * @param {number[]} ctx — from buildContextVector
+ * @returns {null | { provider, model, ucb, explored, propensity, candidates, context }}
+ */
+function decide(tier, candidates, ctx) {
+  if (!candidates || candidates.length < 2) return null;
+  const picked = getBandit().pick(tier, candidates, ctx);
+  if (!picked) return null;
+  return { ...picked, candidates, context: ctx };
+}
+
+/**
+ * Stamp propensity/candidates/_banditContext onto a built decision (WS4.2).
+ *
+ * Collapse rule: the bandit's propensity only describes the served choice if
+ * the served (provider, model) is still one of the bandit's candidates. If a
+ * deterministic downstream override (deadline / tenant) swapped the served
+ * model out of that set — or the bandit never ran — collapse to
+ * propensity=1.0 with a single-entry candidate list, so off-policy
+ * estimators treat the row as a deterministic decision.
+ *
+ * _banditContext is underscored so it never leaks to response headers; the
+ * feedback path consumes it to call bandit.update().
+ *
+ * @param {object} decision — mutated in place (matches prior inline behavior)
+ * @param {{ provider: string, model: string }} served
+ * @param {null | { propensity, candidates, context }} banditResult — from decide()
+ * @returns {object} the same decision, for chaining
+ */
+function stampPropensity(decision, served, banditResult) {
+  const banditPickedServed = banditResult?.candidates
+    && banditResult.candidates.some(
+      c => c.provider === served.provider && c.model === served.model
+    );
+  if (banditPickedServed) {
+    decision.propensity = banditResult.propensity ?? 1.0;
+    decision.candidates = banditResult.candidates;
+    decision._banditContext = banditResult.context;
+  } else {
+    decision.propensity = 1.0;
+    decision.candidates = [{ provider: served.provider, model: served.model }];
+    decision._banditContext = null;
+  }
+  return decision;
+}
+
+module.exports = {
+  TASK_TYPES,
+  buildContextVector,
+  buildCandidates,
+  decide,
+  stampPropensity,
+};

package/src/routing/deescalator.js

@@ -57,7 +57,7 @@ function _lowerTier(tier) {
  * @param {Function} [args.deps.now] - Override Date.now() for tests.
  * @returns {string|null} The lower tier, or null if demotion is not warranted.
  */
-function suggestDemotion({ tier, requestType, analysis, deps = {} } = {}) {
+function suggestDemotion({ tier, requestType, analysis: _analysis, deps = {} } = {}) {
   if (!tier || !requestType) return null;
   const lower = _lowerTier(tier);
   if (!lower) return null;
@@ -103,6 +103,42 @@ function _clearCache() {
   _cache.clear();
 }
 
+/**
+ * Percentage-based demotion holdout (ROUTING-NOTES §4.10.4).
+ *
+ * Even when the evidence supports demotion, a configurable slice of sessions
+ * is deliberately excluded and served at the original tier. Those held-out
+ * rows are a continuously-running baseline: comparing their outcomes against
+ * demoted rows (method suffix '+deescalated' vs '+deescalation_holdout' in
+ * routing telemetry) proves the demotion rule is still net-positive over
+ * time, instead of trusting a one-time calibration.
+ *
+ * The bucket is a deterministic hash of the session key, so a session lands
+ * on the same side of the holdout on every turn — cohorts stay clean and a
+ * conversation never flip-flops tiers because of the holdout itself.
+ *
+ * LYNKR_DEESCALATION_HOLDOUT_PCT: 0–100, default 10. 0 disables the holdout.
+ * Read at call time (not module load) so tests and live re-config work.
+ *
+ * @param {string|null} sessionKey — session id/fingerprint; null → never held out
+ * @returns {boolean} true when this session must NOT be demoted (baseline cohort)
+ */
+function isHeldOut(sessionKey) {
+  if (!sessionKey) return false;
+  const raw = Number.parseInt(process.env.LYNKR_DEESCALATION_HOLDOUT_PCT, 10);
+  const pct = Number.isNaN(raw) ? 10 : Math.min(100, Math.max(0, raw));
+  if (pct === 0) return false;
+  // FNV-1a over the session key → stable bucket in 0..99.
+  let hash = 0x811c9dc5;
+  const s = String(sessionKey);
+  for (let i = 0; i < s.length; i++) {
+    hash ^= s.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  const bucket = (hash >>> 0) % 100;
+  return bucket < pct;
+}
+
 /**
  * Shadow-mode policy. Wraps the live routing decision by delegating to
  * `determineProviderSmart` and then applying `suggestDemotion` on the result.
@@ -143,6 +179,7 @@ async function shadowDeescalate(payload) {
 module.exports = {
   suggestDemotion,
   shadowDeescalate,
+  isHeldOut,
   TIER_ORDER,
   _clearCache,
 };

package/src/routing/embedding-cache.js

@@ -6,7 +6,6 @@
  */
 
 const crypto = require('crypto');
-const logger = require('../logger');
 
 const DEFAULT_MAX = 5000;
 

package/src/routing/index.js

@@ -29,6 +29,7 @@ const { scoreIntent, intentScoreMode } = require('./intent-score');
 // Phase 3-6 routing modules
 const { getKnnRouter } = require('./knn-router');
 const { getBandit } = require('./bandit');
+const { buildCandidates, buildContextVector, decide, stampPropensity } = require('./decide');
 const { getShadowPolicy, compareAndLog: shadowCompareAndLog } = require('./shadow-mode');
 const { chooseFastest } = require('./deadline');
 const { applyTenantOverrides } = require('./tenant-policy');
@@ -391,6 +392,11 @@ function _pinToDecision(pin, { reason, risk }) {
 async function determineProviderSmart(payload, options = {}) {
   const pinCheck = checkSessionPin(payload, options);
 
+  // Thread the session identity into fresh routing without mutating the
+  // caller's options object. Used by the de-escalation holdout so a session
+  // deterministically lands on one side of the holdout on every turn.
+  options = pinCheck.sessionId ? { ...options, _sessionId: pinCheck.sessionId } : options;
+
   // Bypass (no session / forceProvider / feature-off) or no pin yet →
   // straight to fresh routing, then persist the outcome for the next turn.
   if (pinCheck.reason === 'bypass' || pinCheck.reason === 'no_pin') {
@@ -680,6 +686,27 @@ function checkSessionPin(payload, options = {}) {
   const refreshOk = Array.isArray(payload?.tools) && payload.tools.length > 0;
 
   if (sessionAffinity.payloadHasToolHistory(payload)) {
+    // Stuck-loop detection: the pinned model re-issuing the same tool call
+    // (or the same text) over and over. Switching mid-exchange is forbidden
+    // (tool-call IDs aren't provider-portable), so the intervention is the
+    // same safe pattern as the embedded-text triggers below — serve the pin
+    // this turn but DROP it, so the next turn boundary re-routes fresh.
+    try {
+      const { detectStuckLoop } = require('./stuck-detector');
+      const stuck = detectStuckLoop(payload);
+      if (stuck.stuck) {
+        sessionAffinity.removePin(sessionId);
+        logger.warn({
+          sessionId,
+          trigger: stuck.reason,
+          repeats: stuck.repeats,
+          signature: stuck.signature,
+          pinnedTier: pin.tier,
+          pinnedModel: pin.model,
+        }, '[Routing] Stuck loop detected — pin dropped, next boundary re-routes fresh');
+        return { serve: true, pin, reason: 'tool_history_pin_dropped', sessionId };
+      }
+    } catch { /* never block the pin-serve path */ }
     // Text typed during a tool loop arrives merged with the pending
     // tool_result, where the pin serves unconditionally (id linkage forbids
     // switching mid-exchange). If that embedded text trips a trigger, drop
@@ -705,6 +732,32 @@ function checkSessionPin(payload, options = {}) {
         }
       }
     } catch { /* never block the pin-serve path */ }
+    // Context-overflow escape hatch. Every frame of a tool loop is an
+    // unconditional pin serve, so a long agentic session could NEVER escape
+    // to a larger-context model — the guards that check context fit only run
+    // on non-tool turns, which a busy agent may not produce for hours (live
+    // incident: an 884k-token session stayed pinned to a 128k model for 43
+    // straight requests, with 93.7% of history amputated on every one).
+    // Same safe pattern as the triggers above: serve the pin THIS turn
+    // (tool-call IDs aren't provider-portable), drop it so the next boundary
+    // re-routes — and fresh routing's context guard picks a model that fits.
+    try {
+      if (pin.model) {
+        const promptTokensEst = countPayloadTokens(payload, pin.model);
+        const ctxResult = contextValidator.validate(pin.model, promptTokensEst);
+        if (!ctxResult.ok) {
+          sessionAffinity.removePin(sessionId);
+          logger.warn({
+            sessionId,
+            trigger: 'context_overflow',
+            pinnedModel: pin.model,
+            pinnedTier: pin.tier,
+            promptTokensEst,
+          }, '[Routing] Session outgrew pinned model\'s context window — pin dropped, next boundary re-routes to a context-capable model');
+          return { serve: true, pin, reason: 'tool_history_pin_dropped', sessionId };
+        }
+      }
+    } catch { /* never block the pin-serve path */ }
     if (refreshOk) {
       sessionAffinity.setPin(sessionId, pin, {
         // Monotonic within a pin's lifetime: refreshes must never SHRINK the
@@ -1177,6 +1230,91 @@ async function _determineProviderSmartInner(payload, options = {}) {
   selectedModel = modelSelection.model;
   logger.debug({ tier, provider, model: selectedModel }, '[Routing] Using tier config');
 
+  // Item 1 — capability-decoupled shortfall matching (HyDRA port).
+  // Shadow-computes whenever possible (weighted mode only); serves only when
+  // config/model-capabilities.json has enabled:true. Never overrides risk-high (returned earlier
+  // upstream), static mode (tier null), or legacy scorer mode. Downstream
+  // guards (de-escalation, context, vision, kNN, bandit, deadline, tenant)
+  // still run after and dominate — shortfall only replaces the tier_config pick.
+  let shortfallInfo = null;
+  try {
+    if (tier && config.modelTiers?.enabled && risk?.level !== 'high'
+      && analysis?.mode === 'weighted' && analysis?.breakdown) {
+      const { buildRequirementVector } = require('./capabilities');
+      const sf = require('./shortfall');
+      const req = buildRequirementVector({ dimensions: analysis.breakdown, agenticResult });
+      // Candidates constrained to the user's TIER_* (same eligibility rule
+      // as the bandit in decide.js) with tier labels attached for capability
+      // resolution. Dedupe identical provider:model keeping the highest tier.
+      const seen = new Map();
+      for (const t of ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING']) {
+        for (const m of selector.getModelsForTier(t)) {
+          const key = `${m.provider}:${m.model}`;
+          const prev = seen.get(key);
+          if (!prev || (TIER_DEFINITIONS[t]?.priority || 0) > (TIER_DEFINITIONS[prev.tier]?.priority || 0)) {
+            seen.set(key, { provider: m.provider, model: m.model, tier: t });
+          }
+        }
+      }
+      let registry = null;
+      try { registry = require('./model-registry').getModelRegistrySync(); } catch { registry = null; }
+      let optimizer = null;
+      try { optimizer = require('./cost-optimizer').getCostOptimizer(); } catch { optimizer = null; }
+      const candidates = [...seen.values()].map((c) => {
+        let cost = Number.POSITIVE_INFINITY; // unknown price never wins on cheapness
+        try {
+          const info = registry?.getCost?.(c.model);
+          if (info && !info.unknown) {
+            const est = optimizer?.estimateCost?.(c.model, 1000);
+            cost = Number.isFinite(est?.totalEstimate)
+              ? est.totalEstimate
+              : (Number(info.input) || 0) + (Number(info.output) || 0);
+          }
+        } catch { /* keep Infinity */ }
+        return { ...c, cost };
+      });
+      const result = sf.selectByShortfall(req, candidates);
+      if (result) {
+        const agreed = result.selected.provider === provider && result.selected.model === selectedModel;
+        shortfallInfo = {
+          req,
+          tau: result.tau,
+          selected: result.selected,
+          agreed,
+          legacy: { provider, model: selectedModel, tier },
+        };
+        logger.debug({
+          req,
+          tau: result.tau,
+          legacy: `${tier}:${provider}:${selectedModel}`,
+          shortfall: `${result.selected.tier}:${result.selected.provider}:${result.selected.model}`,
+          agreed,
+        }, '[Routing] Shortfall shadow compare');
+        if (sf.isEnabled() && !agreed) {
+          const fromTier = tier;
+          const fromModel = selectedModel;
+          provider = result.selected.provider;
+          selectedModel = result.selected.model;
+          tier = result.selected.tier;
+          analysis.tier = tier;
+          method = method + '+shortfall';
+          if ((TIER_DEFINITIONS[tier]?.priority || 0) > (TIER_DEFINITIONS[fromTier]?.priority || 0)) {
+            escalations.push({
+              source: 'shortfall',
+              fromTier,
+              toTier: tier,
+              fromModel,
+              toModel: selectedModel,
+            });
+          }
+          logger.info({ from: `${fromTier}:${fromModel}`, to: `${tier}:${selectedModel}` }, '[Routing] Shortfall override');
+        }
+      }
+    }
+  } catch (err) {
+    degradation.record('shortfall', err);
+  }
+
   // WS2.3 — evidence-based de-escalation.
   //
   // The check is intentionally gated by evidence, not a feature flag: the
@@ -1200,17 +1338,31 @@ async function _determineProviderSmartInner(payload, options = {}) {
         analysis,
       });
       if (demoted && demoted !== tier) {
-        const demotedSelection = selector.selectModel(demoted, null);
-        logger.debug({
-          from: `${tier}:${provider}:${selectedModel}`,
-          to: `${demoted}:${demotedSelection.provider}:${demotedSelection.model}`,
-          requestType,
-        }, '[Routing] De-escalation — demoting tier on evidence');
-        demotedFrom = tier;
-        provider = demotedSelection.provider;
-        selectedModel = demotedSelection.model;
-        tier = demoted;
-        method = method + '+deescalated';
+        // Percentage holdout (LYNKR_DEESCALATION_HOLDOUT_PCT, default 10):
+        // a deterministic slice of sessions is served at the original tier
+        // even though the evidence supports demotion. Their telemetry rows
+        // (method '+deescalation_holdout') are the running baseline that
+        // proves demoted sessions aren't quietly doing worse.
+        if (deescalator.isHeldOut(options._sessionId)) {
+          method = method + '+deescalation_holdout';
+          logger.debug({
+            tier,
+            wouldDemoteTo: demoted,
+            requestType,
+          }, '[Routing] De-escalation — evidence supports demotion, session held out as baseline');
+        } else {
+          const demotedSelection = selector.selectModel(demoted, null);
+          logger.debug({
+            from: `${tier}:${provider}:${selectedModel}`,
+            to: `${demoted}:${demotedSelection.provider}:${demotedSelection.model}`,
+            requestType,
+          }, '[Routing] De-escalation — demoting tier on evidence');
+          demotedFrom = tier;
+          provider = demotedSelection.provider;
+          selectedModel = demotedSelection.model;
+          tier = demoted;
+          method = method + '+deescalated';
+        }
       }
     } catch (err) {
       degradation.record('tier_select', err);
@@ -1441,65 +1593,29 @@ async function _determineProviderSmartInner(payload, options = {}) {
   // WS4.2 — capture propensity + candidates + context so the outcome row can
   // support off-policy evaluation. banditContext is stashed on the decision
   // (underscored → won't leak through headers, see WS4.2 verification).
-  let banditPropensity = null;
-  let banditCandidates = null;
-  let banditContext = null;
+  //
+  // The candidate-building / context-vector / pick logic lives in decide.js
+  // so the off-policy evaluator can replay it against logged rows.
+  let banditResult = null;
   if (config.routing?.banditEnabled !== false && knnResult && knnResult.model) {
     try {
-      // Build candidates: current selection and kNN alternative if different.
-      //
-      // Tier-aware filter: only treat the kNN suggestion as a real candidate
-      // if it matches a (provider, model) combo configured in ANY TIER_*
-      // entry. The bandit is allowed to explore freely across the user's
-      // configured tiers (e.g. swap a SIMPLE request to the COMPLEX-tier
-      // model), but is forbidden from picking a credentialed-but-untiered
-      // model (e.g. an Azure OpenAI deployment whose endpoint is set in .env
-      // for some other use, but not referenced by any TIER_*). This keeps
-      // tier routing as the source of truth for what's eligible while
-      // preserving cross-tier bandit exploration.
-      const allCandidates = [{ provider, model: selectedModel }];
-      if (knnResult.model !== selectedModel) {
-        const configured = require('./model-tiers').getModelTierSelector().getAllConfiguredModels();
-        const inConfig = configured.some(
-          m => m.provider === knnResult.provider && m.model === knnResult.model
-        );
-        if (inConfig) {
-          allCandidates.push({ provider: knnResult.provider, model: knnResult.model });
-        }
-      }
-
-      if (allCandidates.length > 1) {
-        const bandit = getBandit();
-        const TASK_TYPES = ['code_gen', 'summarization', 'reasoning', 'factoid', 'chat', 'other'];
-        const inferredTask = (analysis.breakdown?.taskType?.reason || 'other').toLowerCase();
-        const taskIdx = Math.max(0, TASK_TYPES.findIndex(t => inferredTask.includes(t)));
-        const ctx = [
-          (analysis.score || 0) / 100,
-          Math.log(Math.max(1, analysis.breakdown?.tokenCount || 0) + 1) / 15,
-          ((payload?.tools?.length ?? 0) > 0) ? 1 : 0,
-          options.streaming ? 1 : 0,
-          risk?.level === 'high' ? 1 : risk?.level === 'medium' ? 0.5 : 0,
-          agenticResult?.isAgentic ? 1 : 0,
-          ...TASK_TYPES.map((_, i) => i === taskIdx ? 1 : 0),
-        ];
-        const picked = bandit.pick(tier, allCandidates, ctx);
-        if (picked) {
-          banditCandidates = allCandidates;
-          banditPropensity = picked.propensity ?? null;
-          banditContext = ctx;
-          if (picked.model !== selectedModel) {
-            logger.debug({
-              from: `${provider}:${selectedModel}`,
-              to: `${picked.provider}:${picked.model}`,
-              ucb: picked.ucb?.toFixed(4),
-              explored: picked.explored,
-              propensity: picked.propensity,
-            }, '[Routing] Bandit override');
-            provider = picked.provider;
-            selectedModel = picked.model;
-            method = method + (picked.explored ? '+bandit_explore' : '+bandit');
-          }
-        }
+      const allCandidates = buildCandidates(
+        { provider, model: selectedModel },
+        { provider: knnResult.provider, model: knnResult.model },
+      );
+      const ctx = buildContextVector({ analysis, payload, options, risk, agenticResult });
+      banditResult = decide(tier, allCandidates, ctx);
+      if (banditResult && banditResult.model !== selectedModel) {
+        logger.debug({
+          from: `${provider}:${selectedModel}`,
+          to: `${banditResult.provider}:${banditResult.model}`,
+          ucb: banditResult.ucb?.toFixed(4),
+          explored: banditResult.explored,
+          propensity: banditResult.propensity,
+        }, '[Routing] Bandit override');
+        provider = banditResult.provider;
+        selectedModel = banditResult.model;
+        method = method + (banditResult.explored ? '+bandit_explore' : '+bandit');
       }
     } catch (err) {
       degradation.record('bandit', err);
@@ -1568,6 +1684,7 @@ async function _determineProviderSmartInner(payload, options = {}) {
     knnResult,
     base_tier: baseTier,
     escalations,
+    shortfall: shortfallInfo,
     // Upward escalations take precedence in the source label; a demotion is
     // only surfaced when nothing else escalated (guarded by the wire above,
     // but re-checked here for clarity).
@@ -1577,24 +1694,13 @@ async function _determineProviderSmartInner(payload, options = {}) {
   });
 
   // WS4.2 — propensity/candidates for off-policy evaluation from telemetry.
-  // Bandit picks populate both. If a deterministic downstream override
-  // (deadline / tenant) then swapped the served model out of the bandit's
-  // candidate set, the bandit's propensity no longer describes the served
-  // choice — collapse to propensity=1.0 with a single candidate. Otherwise
-  // deterministic branches (bandit didn't run at all) always collapse.
-  // _banditContext is underscored so it never leaks to response headers;
-  // WS5 will consume it in the feedback path to call bandit.update().
-  const banditPickedServed = banditCandidates
-    && banditCandidates.some(c => c.provider === provider && c.model === selectedModel);
-  if (banditPickedServed) {
-    decision.propensity = banditPropensity ?? 1.0;
-    decision.candidates = banditCandidates;
-    decision._banditContext = banditContext;
-  } else {
-    decision.propensity = 1.0;
-    decision.candidates = [{ provider, model: selectedModel }];
-    decision._banditContext = null;
-  }
+  // Collapse rule lives in decide.js (stampPropensity): if a deterministic
+  // downstream override (deadline / tenant) swapped the served model out of
+  // the bandit's candidate set — or the bandit never ran — the row collapses
+  // to propensity=1.0 with a single candidate. _banditContext is underscored
+  // so it never leaks to response headers; the feedback path consumes it to
+  // call bandit.update().
+  stampPropensity(decision, { provider, model: selectedModel }, banditResult);
 
   // WS5.5 — attach the query embedding + raw query text so the feedback
   // path can turn conclusive outcomes into new kNN exemplars without
@@ -1658,6 +1764,16 @@ function getRoutingHeaders(decision) {
 
   if (decision.model) {
     headers['X-Lynkr-Model'] = decision.model;
+    // Served-model context window (workweave pattern): the client can't know
+    // the real window behind a virtual model name when tier routing serves
+    // different models per request — this header is the authoritative per-
+    // turn answer, intended as the client's compaction budget. Omitted (never
+    // guessed) when the registry doesn't know the model.
+    const { contextWindowFor } = require('./model-registry');
+    const contextWindow = contextWindowFor(decision.model);
+    if (contextWindow) {
+      headers['X-Lynkr-Context-Window'] = String(contextWindow);
+    }
   }
 
   if (decision.agenticResult?.isAgentic) {

package/src/routing/intent-score.js

@@ -206,7 +206,6 @@ function classify(embedding, centroids) {
  * Lexical fallback path stays clamped ≤75 (see _lexicalCleanScore).
  */
 function blendScore(sims) {
-  const classes = Object.keys(CLASS_VALUES);
   // Frontier similarity floor: a weak topical match can't jump tiers.
   const frontierSim = sims.frontier ?? -1;
   const activeSims = { ...sims };

package/src/routing/knn-router.js

@@ -22,7 +22,11 @@ const logger = require('../logger');
 const { generateEmbedding } = require('../cache/embeddings');
 const { getEmbeddingCache } = require('./embedding-cache');
 
-const INDEX_DIR = path.join(__dirname, '../../data/knn');
+// LYNKR_KNN_DIR override exists so test runs point at a scratch dir instead
+// of the production index — parallel test processes saving to the real path
+// produced a torn read → corrupt link-list lengths → a 135GB zero-filled
+// index file (2026-08-21).
+const INDEX_DIR = process.env.LYNKR_KNN_DIR || path.join(__dirname, '../../data/knn');
 const INDEX_FILE = path.join(INDEX_DIR, 'index.hnsw');
 const META_FILE = path.join(INDEX_DIR, 'meta.json');
 
@@ -85,7 +89,7 @@ class KnnRouter {
       // (Earlier Lynkr code passed MAX_ELEMENTS here — wrong type, threw on load.)
       this.index.readIndexSync(INDEX_FILE, false);
       // resize if needed so we can keep adding up to MAX_ELEMENTS
-      try { this.index.resizeIndex(MAX_ELEMENTS); } catch (_) {}
+      try { this.index.resizeIndex(MAX_ELEMENTS); } catch (err) { logger.debug({ err: err.message }, '[KnnRouter] resizeIndex failed — index may not grow past loaded size'); }
       this.ready = true;
       logger.info({ size: this.size, dim: this.dim }, '[KnnRouter] Index loaded');
       return true;
@@ -99,8 +103,26 @@ class KnnRouter {
     if (!this.ready || !this.index) return;
     try {
       fs.mkdirSync(INDEX_DIR, { recursive: true });
-      this.index.writeIndexSync(INDEX_FILE);
-      fs.writeFileSync(META_FILE, JSON.stringify({ dim: this.dim, entries: this.meta }, null, 0));
+      // Atomic save: hnswlib's writeIndexSync is truncate-then-write, so a
+      // concurrent reader can observe a torn image and later persist a
+      // corrupt index. Write to a per-pid temp file and rename into place —
+      // readers then always see a complete image.
+      const tmpIndex = `${INDEX_FILE}.tmp-${process.pid}`;
+      const tmpMeta = `${META_FILE}.tmp-${process.pid}`;
+      this.index.writeIndexSync(tmpIndex);
+      // Sanity bound: a healthy index is ~(elements × ~3.3KB) + slack. A
+      // corrupted link-list length manifests as a wildly oversized file —
+      // refuse to install it over the good one.
+      const expectedMax = (this.size + 1000) * 8192 + 1_000_000;
+      const written = fs.statSync(tmpIndex).size;
+      if (written > expectedMax) {
+        fs.rmSync(tmpIndex, { force: true });
+        logger.error({ written, expectedMax, size: this.size }, '[KnnRouter] Refusing to save implausibly large index — in-memory index likely corrupt');
+        return;
+      }
+      fs.writeFileSync(tmpMeta, JSON.stringify({ dim: this.dim, entries: this.meta }, null, 0));
+      fs.renameSync(tmpIndex, INDEX_FILE);
+      fs.renameSync(tmpMeta, META_FILE);
     } catch (err) {
       logger.warn({ err: err.message }, '[KnnRouter] Index save failed');
     }
@@ -197,7 +219,7 @@ class KnnRouter {
 
     let best = null;
     let bestScore = -Infinity;
-    for (const [model, agg] of byModel) {
+    for (const [, agg] of byModel) {
       const avgQ = agg.quality / agg.weight;
       const avgC = agg.cost / agg.weight;
       // Score = quality / log(cost+1) — reward quality, penalise cost gently

package/src/routing/latency-tracker.js

@@ -95,7 +95,7 @@ class LatencyTracker {
     }
     // Aggregate across all models for this provider
     const provEntries = [];
-    for (const [k, entry] of this._entries) {
+    for (const [_k, entry] of this._entries) {
       if (entry.provider === provider) provEntries.push(entry);
     }
     if (provEntries.length === 0) return null;