lynkr 9.7.3 → 9.9.0

package/src/routing/client-profiles.js

@@ -0,0 +1,292 @@
+/**
+ * Client Profiles (WS3.1).
+ *
+ * Client harnesses like Claude Code, Cursor, and Codex attach a large
+ * baseline tool loadout to EVERY request (Claude Code sends ~11 tools
+ * unconditionally). The old agentic detector inflated `tool_count` and
+ * `agentic_tool` signals from those baselines, mis-classifying a trivial
+ * "hi" as an agentic COMPLEX-tier workload.
+ *
+ * The `slice(0, 3)` hack in `src/api/router.js` worked around that in one
+ * specific spot for one specific client — but it also discarded real MCP
+ * tools the user had configured, and did nothing for Cursor / Codex.
+ *
+ * This module fixes the root cause. Given a request's `user-agent` header
+ * and its tools list, `detectClient` returns the matching profile (or null),
+ * and `effectiveTools` subtracts the baseline so the agentic detector scores
+ * only tools the user actually added beyond the harness default.
+ *
+ * @module routing/client-profiles
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+
+/**
+ * Seed profiles. Baseline tool lists must exactly match the tool NAMES the
+ * client sends (case-sensitive) — the agentic detector reads
+ * `t.name || t.function?.name`, so these are the tools that ship in the
+ * harness's default `tools` array.
+ *
+ * Claude Code's default loadout was verified against the live proxy request
+ * shape at time of writing (2026-07). If a future release adds/renames a
+ * tool, add it here (or override via data/client-profiles.json).
+ */
+const PROFILES = {
+  'claude-code': {
+    name: 'claude-code',
+    baselineTools: new Set([
+      'Task', 'Bash', 'Glob', 'Grep', 'Read', 'Edit', 'Write',
+      'NotebookEdit', 'WebFetch', 'WebSearch', 'TodoWrite',
+      'BashOutput', 'KillShell', 'SlashCommand',
+    ]),
+    detect: {
+      // Claude Code CLI actually sends `user-agent: claude-cli/x.y.z` (not
+      // claude-code/x.y.z as the tests assumed). Match every Anthropic-side
+      // subscription client — same set as auth-mode.js's
+      // SUBSCRIPTION_UA_PREFIXES, kept in sync manually since the two files
+      // want slightly different match rules.
+      headerPatterns: [
+        /claude[-_](cli|code|vscode)/i,
+        /anthropic-cli/i,
+      ],
+      minToolFingerprintMatch: 0.8,
+    },
+  },
+  'cursor': {
+    name: 'cursor',
+    baselineTools: new Set([
+      // Cursor's default agent loadout
+      'read_file', 'write_file', 'edit_file', 'delete_file',
+      'run_terminal_command', 'grep_search', 'file_search', 'codebase_search',
+      'web_search', 'list_dir',
+    ]),
+    detect: {
+      headerPatterns: [/cursor/i],
+      minToolFingerprintMatch: 0.8,
+    },
+  },
+  'lynkr-injected': {
+    name: 'lynkr-injected',
+    baselineTools: new Set([
+      // Lynkr's own IDE_SAFE_TOOLS loadout (src/clients/standard-tools.js),
+      // injected by the OpenAI-compat routers when a client sends no tools.
+      // These are Lynkr plumbing, not user intent: without this profile the
+      // agentic detector counts its own injected tools and floors every
+      // tool-less client (e.g. goose's summarizer side-requests) at
+      // ITERATIVE/COMPLEX. Matches claude-code's names plus the four
+      // (MultiEdit, LS, NotebookRead, WebAgent) that keep it from
+      // fingerprinting as claude-code.
+      'Write', 'Read', 'Edit', 'Bash', 'Glob', 'Grep', 'MultiEdit', 'LS',
+      'NotebookRead', 'TodoWrite', 'Task', 'WebSearch', 'WebFetch',
+      'WebAgent', 'NotebookEdit',
+    ]),
+    detect: {
+      headerPatterns: [],
+      minToolFingerprintMatch: 0.8,
+    },
+  },
+  'goose': {
+    name: 'goose',
+    baselineTools: new Set([
+      // Goose CLI 1.41 default loadout — captured live 2026-07-13 against
+      // the OpenAI-compatible endpoint. Goose sends NO user-agent header,
+      // so detection relies entirely on this tool fingerprint. The apps__*,
+      // extensionmanager__* and todo__* names come from goose's default
+      // extensions; the rest are core tools that attach to every request.
+      'analyze', 'delegate', 'edit', 'load', 'load_skill', 'read_image',
+      'shell', 'tree', 'write',
+      'apps__create_app', 'apps__delete_app', 'apps__iterate_app',
+      'apps__list_apps',
+      'extensionmanager__list_resources', 'extensionmanager__manage_extensions',
+      'extensionmanager__read_resource',
+      'extensionmanager__search_available_extensions',
+      'todo__todo_write',
+    ]),
+    detect: {
+      headerPatterns: [/goose/i],
+      // 0.5 rather than the usual 0.8: users can disable goose's default
+      // extensions (apps, extensionmanager, todo), which removes up to 9 of
+      // the 18 baseline names while the 9 core tools still identify goose.
+      // A false-positive match on another harness with this many identical
+      // tool names would subtract only those shared names — harmless.
+      minToolFingerprintMatch: 0.5,
+    },
+  },
+  'openai-codex': {
+    name: 'openai-codex',
+    baselineTools: new Set([
+      // Legacy Codex CLI (and Lynkr's injected fallback names)
+      'shell', 'apply_patch', 'read_file', 'write_file',
+      // Codex v0.142+ (Rust CLI) default loadout — captured live 2026-07-11.
+      // All of these attach to EVERY request, including "Hi": counting them
+      // as agentic intent floored every Codex turn at MEDIUM.
+      'exec_command', 'write_stdin', 'update_plan', 'request_user_input',
+      'view_image', 'get_goal', 'create_goal', 'update_goal',
+      'list_mcp_resources', 'list_mcp_resource_templates', 'read_mcp_resource',
+      'list_available_plugins_to_install', 'request_plugin_install',
+    ]),
+    detect: {
+      headerPatterns: [/codex/i, /openai-cli/i],
+      minToolFingerprintMatch: 0.8,
+    },
+  },
+};
+
+// Union of every baseline tool across all known profiles — used for the
+// "no-profile-but-looks-like-a-harness" heuristic guard.
+let _knownBaselineToolsCache = null;
+function _knownBaselineTools() {
+  if (_knownBaselineToolsCache) return _knownBaselineToolsCache;
+  const s = new Set();
+  for (const p of Object.values(PROFILES)) {
+    for (const t of p.baselineTools) s.add(t);
+  }
+  _knownBaselineToolsCache = s;
+  return s;
+}
+
+// User overrides / additions from data/client-profiles.json — loaded once
+// at first use. Shape: { profileName: { baselineTools: [...], detect: {...} } }
+let _userProfilesLoaded = false;
+function _loadUserProfiles() {
+  if (_userProfilesLoaded) return;
+  _userProfilesLoaded = true;
+  const overridePath = path.join(process.cwd(), 'data', 'client-profiles.json');
+  if (!fs.existsSync(overridePath)) return;
+  try {
+    const raw = JSON.parse(fs.readFileSync(overridePath, 'utf8'));
+    for (const [name, def] of Object.entries(raw || {})) {
+      if (!def || typeof def !== 'object') continue;
+      const baseline = Array.isArray(def.baselineTools)
+        ? new Set(def.baselineTools)
+        : PROFILES[name]?.baselineTools ?? new Set();
+      const patterns = Array.isArray(def.headerPatterns)
+        ? def.headerPatterns.map((p) => new RegExp(p, 'i'))
+        : PROFILES[name]?.detect?.headerPatterns ?? [];
+      PROFILES[name] = {
+        name,
+        baselineTools: baseline,
+        detect: {
+          headerPatterns: patterns,
+          minToolFingerprintMatch: Number.isFinite(def.minToolFingerprintMatch)
+            ? def.minToolFingerprintMatch
+            : 0.8,
+        },
+      };
+    }
+    _knownBaselineToolsCache = null; // recompute after overrides
+    logger.debug({ count: Object.keys(raw).length }, '[ClientProfiles] Loaded user overrides');
+  } catch (err) {
+    logger.debug({ err: err.message }, '[ClientProfiles] Failed to load user overrides');
+  }
+}
+
+function _toolName(t) {
+  return (t && (t.name || t.function?.name)) || null;
+}
+
+/**
+ * Detect the client harness that issued this request.
+ *
+ * Match order:
+ *   1. user-agent header regex — strongest signal, cheap.
+ *   2. Tool-set fingerprint — ≥ minToolFingerprintMatch (default 80%) of the
+ *      profile's baseline tool names must be present in payload.tools.
+ *
+ * @param {Object} args
+ * @param {Object} [args.headers]
+ * @param {Object} [args.payload]
+ * @returns {Object|null} The matched profile or null.
+ */
+function detectClient({ headers = {}, payload = {} } = {}) {
+  _loadUserProfiles();
+
+  const ua = String(headers['user-agent'] || headers['User-Agent'] || '');
+  if (ua) {
+    for (const profile of Object.values(PROFILES)) {
+      for (const pattern of profile.detect.headerPatterns) {
+        if (pattern.test(ua)) return profile;
+      }
+    }
+  }
+
+  const tools = Array.isArray(payload.tools) ? payload.tools : [];
+  if (tools.length === 0) return null;
+
+  const presentNames = new Set(tools.map(_toolName).filter(Boolean));
+  let best = null;
+  let bestRatio = 0;
+  for (const profile of Object.values(PROFILES)) {
+    const baseline = profile.baselineTools;
+    if (baseline.size === 0) continue;
+    let hits = 0;
+    for (const name of baseline) {
+      if (presentNames.has(name)) hits++;
+    }
+    const ratio = hits / baseline.size;
+    if (ratio >= profile.detect.minToolFingerprintMatch && ratio > bestRatio) {
+      best = profile;
+      bestRatio = ratio;
+    }
+  }
+  return best;
+}
+
+/**
+ * Return the tools in `payload.tools` that are NOT part of `profile`'s
+ * baseline loadout — i.e., the tools the user actually configured beyond
+ * the harness default. If profile is null, returns the raw list.
+ *
+ * The array preserves the original tool objects (not just names) so the
+ * agentic detector can still inspect `t.name || t.function?.name`.
+ *
+ * @param {Object} payload
+ * @param {Object|null} profile
+ * @returns {Array}
+ */
+function effectiveTools(payload, profile) {
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  if (!profile) return tools.slice();
+  const baseline = profile.baselineTools;
+  return tools.filter((t) => {
+    const name = _toolName(t);
+    return name && !baseline.has(name);
+  });
+}
+
+/**
+ * True when every tool name in the payload is present in some known profile's
+ * baseline. Used by the agentic detector's "unknown harness" guard so a
+ * Claude-Code-alike client that omits its user-agent doesn't inflate the
+ * agentic score.
+ *
+ * @param {Object} payload
+ * @returns {boolean}
+ */
+function allToolsAreBaseline(payload) {
+  _loadUserProfiles();
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  if (tools.length === 0) return false;
+  const known = _knownBaselineTools();
+  for (const t of tools) {
+    const name = _toolName(t);
+    if (!name || !known.has(name)) return false;
+  }
+  return true;
+}
+
+/** Test helper — clear cached override state (unit tests reload from disk). */
+function _resetForTests() {
+  _userProfilesLoaded = false;
+  _knownBaselineToolsCache = null;
+}
+
+module.exports = {
+  PROFILES,
+  detectClient,
+  effectiveTools,
+  allToolsAreBaseline,
+  _resetForTests,
+};

package/src/routing/complexity-analyzer.js

@@ -15,6 +15,26 @@
 const logger = require('../logger');
 const config = require('../config');
 const codeGraph = require('../tools/code-graph');
+const clientProfiles = require('./client-profiles');
+
+/**
+ * Return the tools the user actually added beyond the client harness's
+ * baseline loadout. Same intent as the agentic detector's guard: Claude
+ * Code / Cursor / Codex all attach a fat baseline tools list to every
+ * request, and counting those inflates the complexity score for trivial
+ * turns. If no profile is attached, fall back to the raw list, but zero
+ * it out when every tool is a known-harness-baseline name AND there are
+ * enough of them to look like a harness attaching its default set
+ * (mirrors the "unknown_harness_guard" in agentic-detector.js).
+ */
+function _effectiveTools(payload) {
+  const raw = Array.isArray(payload?.tools) ? payload.tools : [];
+  if (raw.length === 0) return raw;
+  const profile = payload?._clientProfile || null;
+  if (profile) return clientProfiles.effectiveTools(payload, profile);
+  if (raw.length >= 10 && clientProfiles.allToolsAreBaseline(payload)) return [];
+  return raw;
+}
 
 // ============================================================================
 // PHASE 1: Basic Scoring Patterns
@@ -422,10 +442,14 @@ function scoreTokens(payload) {
 }
 
 /**
- * Score based on tool count (0-20 points)
+ * Score based on tool count (0-20 points). Uses the effective tool list —
+ * i.e. tools the user actually added beyond the client harness's baseline
+ * loadout — so a trivial "hi" with 11 Claude Code tools attached doesn't
+ * pick up 16 points of "heavy tools" complexity for something the user
+ * didn't ask for.
  */
 function scoreTools(payload) {
-  const toolCount = Array.isArray(payload?.tools) ? payload.tools.length : 0;
+  const toolCount = _effectiveTools(payload).length;
 
   if (toolCount === 0) return 0;    // No tools
   if (toolCount <= 3) return 4;     // Few tools - local can handle
@@ -627,21 +651,22 @@ function calculateWeightedScore(payload, content) {
   }
   dimensions.domainSpecificity = Math.min(domainScore, 100);
 
-  // 5. Tool count
-  const toolCount = payload?.tools?.length ?? 0;
+  // 5. Tool count — effective tools only (harness baseline subtracted)
+  const effTools = _effectiveTools(payload);
+  const toolCount = effTools.length;
   dimensions.toolCount = toolCount === 0 ? 0 :
     toolCount <= 3 ? 20 :
     toolCount <= 6 ? 40 :
     toolCount <= 10 ? 60 :
     toolCount <= 15 ? 80 : 100;
 
-  // 6. Tool complexity (weighted by tool types)
-  if (payload?.tools?.length > 0) {
-    const totalWeight = payload.tools.reduce((sum, t) => {
+  // 6. Tool complexity (weighted by tool types) — same effective list
+  if (effTools.length > 0) {
+    const totalWeight = effTools.reduce((sum, t) => {
       const name = t.name || t.function?.name || '';
       return sum + (TOOL_COMPLEXITY_WEIGHTS[name] || TOOL_COMPLEXITY_WEIGHTS.default);
     }, 0);
-    const avgWeight = totalWeight / payload.tools.length;
+    const avgWeight = totalWeight / effTools.length;
     dimensions.toolComplexity = avgWeight * 100;
   } else {
     dimensions.toolComplexity = 0;
@@ -831,7 +856,7 @@ async function analyzeComplexity(payload, options = {}) {
     recommendation,
     breakdown: {
       tokens: { score: tokenScore, estimated: estimateTokens(payload) },
-      tools: { score: toolScore, count: payload?.tools?.length ?? 0 },
+      tools: { score: toolScore, count: _effectiveTools(payload).length },
       taskType: taskTypeResult,
       codeComplexity: codeComplexityResult,
       reasoning: reasoningResult,
@@ -878,7 +903,15 @@ async function analyzeComplexity(payload, options = {}) {
  */
 function shouldForceLocal(payload) {
   const content = extractContent(payload);
-  return FORCE_LOCAL_PATTERNS.some(pattern => pattern.test(content));
+  const matched = FORCE_LOCAL_PATTERNS.find(pattern => pattern.test(content));
+  if (matched) {
+    // Deliberately loud: a force_local misfire routed a subagent's opening
+    // frames to the weakest tier (live 2026-07-09, pattern unidentified at
+    // the time because the wrap gateway had no file logging). This line is
+    // how the next misfire names itself.
+    logger.debug({ pattern: matched.source.slice(0, 50), text: content.slice(0, 100) }, '[Force] force_local matched');
+  }
+  return !!matched;
 }
 
 /**
@@ -886,7 +919,11 @@ function shouldForceLocal(payload) {
  */
 function shouldForceCloud(payload) {
   const content = extractContent(payload);
-  return FORCE_CLOUD_PATTERNS.some(pattern => pattern.test(content));
+  const matched = FORCE_CLOUD_PATTERNS.find(pattern => pattern.test(content));
+  if (matched) {
+    logger.debug({ pattern: matched.source.slice(0, 50), text: content.slice(0, 100) }, '[Force] force_cloud matched');
+  }
+  return !!matched;
 }
 
 // ============================================================================

package/src/routing/deescalator.js

@@ -0,0 +1,148 @@
+/**
+ * De-escalation policy (WS2.3).
+ *
+ * The routing pipeline today only ratchets *up* — risk / agentic minTier /
+ * context / vision / kNN-ambiguous all escalate; nothing ever demotes. That
+ * means once a request_type has been escalated for ANY reason (even a
+ * one-off), it stays over-provisioned forever.
+ *
+ * This module supplies the missing signal: for a given (tier, request_type),
+ * has the *lower* tier historically served ≥ N similar requests at quality
+ * ≥ Q with error rate < E? If yes, the caller may demote — cheaper AND
+ * evidence-backed.
+ *
+ * The check is a plain SELECT against routing_telemetry (cached 60s) so
+ * enabling it in-line does not add DB pressure at request rate.
+ *
+ * @module routing/deescalator
+ */
+
+const logger = require('../logger');
+const telemetry = require('./telemetry');
+
+const TIER_ORDER = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+
+// Fixed thresholds. Chosen conservatively so a demotion only fires when the
+// lower tier has demonstrable evidence: a full-week window, a meaningful
+// sample count, high average quality, and a low error rate.
+const MIN_SAMPLES = 30;
+const MIN_QUALITY = 70;
+const MAX_ERROR_RATE = 0.05;
+const WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const CACHE_TTL_MS = 60 * 1000;
+
+/** @type {Map<string, {value: string|null, ts: number}>} */
+const _cache = new Map();
+
+function _cacheKey(tier, requestType) {
+  return `${tier}::${requestType || '<none>'}`;
+}
+
+function _lowerTier(tier) {
+  const idx = TIER_ORDER.indexOf(tier);
+  if (idx <= 0) return null;
+  return TIER_ORDER[idx - 1];
+}
+
+/**
+ * Return the demoted tier if evidence supports it; null otherwise.
+ *
+ * @param {Object} args
+ * @param {string} args.tier - The tier the router currently plans to serve.
+ * @param {string|null} args.requestType - Complexity analyzer's request_type.
+ * @param {Object} [args.analysis] - Passed through for callers that want it;
+ *   currently unused by the rule, kept for signature stability.
+ * @param {Object} [args.deps] - Test-injectable dependencies.
+ * @param {Function} [args.deps.getQualityByTierAndType] - Override the telemetry query.
+ * @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 = {} } = {}) {
+  if (!tier || !requestType) return null;
+  const lower = _lowerTier(tier);
+  if (!lower) return null;
+
+  const now = typeof deps.now === 'function' ? deps.now() : Date.now();
+  const key = _cacheKey(tier, requestType);
+  const cached = _cache.get(key);
+  if (cached && now - cached.ts < CACHE_TTL_MS) {
+    return cached.value;
+  }
+
+  const query = deps.getQualityByTierAndType || telemetry.getQualityByTierAndType;
+  if (typeof query !== 'function') return null;
+
+  let rows = null;
+  try {
+    rows = query({
+      since: now - WINDOW_MS,
+      until: now,
+      tiers: [lower],
+    });
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Deescalator] telemetry query failed');
+    return null;
+  }
+
+  const match = Array.isArray(rows)
+    ? rows.find((r) => r.tier === lower && r.request_type === requestType)
+    : null;
+
+  const ok = match
+    && match.count >= MIN_SAMPLES
+    && (match.avg_quality ?? 0) >= MIN_QUALITY
+    && (match.error_rate ?? 1) < MAX_ERROR_RATE;
+
+  const value = ok ? lower : null;
+  _cache.set(key, { value, ts: now });
+  return value;
+}
+
+/** Test helper — clear the memoized decisions. */
+function _clearCache() {
+  _cache.clear();
+}
+
+/**
+ * Shadow-mode policy. Wraps the live routing decision by delegating to
+ * `determineProviderSmart` and then applying `suggestDemotion` on the result.
+ * Registered with shadow-mode.js under name 'deescalate-v1' so operators can
+ * evaluate the projected cost/quality delta before enabling live demotion.
+ */
+async function shadowDeescalate(payload) {
+  // Late require to avoid the circular src/routing/index.js ↔ deescalator.js
+  // reference (index.js registers the shadow policy at module load).
+  const { determineProviderSmart } = require('./index');
+  const base = await determineProviderSmart(payload, { _shadow: true });
+  if (!base?.tier) return base;
+  const requestType = base?.analysis?.breakdown?.taskType?.reason
+    ?? base?.analysis?.taskType
+    ?? null;
+  const demoted = suggestDemotion({
+    tier: base.tier,
+    requestType,
+    analysis: base.analysis,
+  });
+  if (!demoted) return base;
+  try {
+    const { getModelTierSelector } = require('./model-tiers');
+    const selected = getModelTierSelector().selectModel(demoted, null);
+    return {
+      ...base,
+      provider: selected.provider,
+      model: selected.model,
+      tier: demoted,
+      method: (base.method || 'tier_config') + '+deescalated_shadow',
+      _shadowDemotedFrom: base.tier,
+    };
+  } catch {
+    return base;
+  }
+}
+
+module.exports = {
+  suggestDemotion,
+  shadowDeescalate,
+  TIER_ORDER,
+  _clearCache,
+};

package/src/routing/degradation.js

@@ -0,0 +1,109 @@
+/**
+ * Degradation Registry
+ *
+ * Tracks silent-fallback occurrences across the routing pipeline. Every catch
+ * block in the routing path that used to `logger.debug` and fall through now
+ * calls `record(component, err)` here instead, giving us:
+ *
+ *   - A counter per subsystem (visible via getRoutingStats)
+ *   - A warn-once-per-hour policy per component (so the first failure surfaces
+ *     in ops, but a wedged subsystem doesn't spam)
+ *   - The last error message and timestamp for postmortem
+ *
+ * @module routing/degradation
+ */
+
+const logger = require("../logger");
+
+// TODO(prometheus): expose these counters as Prometheus gauges once the
+// project ships a prom-client registry (no such registry today; the WS0 plan
+// authorised skipping this — getRoutingStats().degradation is the interim
+// signal).
+
+const KNOWN_COMPONENTS = new Set([
+  "risk",
+  "embeddings",
+  "agentic",
+  "tier_select",
+  "cost_optimize",
+  "context_validate",
+  "vision_guard",
+  "knn",
+  "bandit",
+  "deadline",
+  "tenant",
+  "feedback",
+  "calibration",
+]);
+
+const WARN_INTERVAL_MS = 60 * 60 * 1000;
+
+/** @type {Map<string, {count:number, lastError:string|null, lastAt:number, lastWarnedAt:number}>} */
+const counters = new Map();
+
+function _entry(component) {
+  let e = counters.get(component);
+  if (!e) {
+    e = { count: 0, lastError: null, lastAt: 0, lastWarnedAt: 0 };
+    counters.set(component, e);
+  }
+  return e;
+}
+
+/**
+ * Record a degradation event. Warns once per hour per component, otherwise
+ * increments the counter silently at debug level.
+ *
+ * @param {string} component - One of KNOWN_COMPONENTS. Unknown names are
+ *   accepted (kept for forward compatibility) but log a debug notice.
+ * @param {Error|{message?:string}|string} err
+ */
+function record(component, err) {
+  if (!component) return;
+  if (!KNOWN_COMPONENTS.has(component)) {
+    logger.debug({ component }, "[Degradation] Unknown component recorded");
+  }
+
+  const message = err == null
+    ? "unknown"
+    : typeof err === "string"
+      ? err
+      : (err.message || String(err));
+
+  const now = Date.now();
+  const e = _entry(component);
+  e.count += 1;
+  e.lastError = message;
+  e.lastAt = now;
+
+  if (now - e.lastWarnedAt >= WARN_INTERVAL_MS) {
+    e.lastWarnedAt = now;
+    logger.warn({ component, err: message, count: e.count }, "[Degradation] Subsystem failed, falling through");
+  } else {
+    logger.debug({ component, err: message, count: e.count }, "[Degradation] Subsystem failed, falling through");
+  }
+}
+
+/**
+ * Snapshot of per-component counters, safe to serialize into stats responses.
+ * @returns {Object<string, {count:number, lastError:string|null, lastAt:number}>}
+ */
+function getCounts() {
+  const out = {};
+  for (const [name, e] of counters.entries()) {
+    out[name] = { count: e.count, lastError: e.lastError, lastAt: e.lastAt };
+  }
+  return out;
+}
+
+/** Test helper — reset all counters. */
+function _clear() {
+  counters.clear();
+}
+
+module.exports = {
+  record,
+  getCounts,
+  KNOWN_COMPONENTS,
+  _clear,
+};