lynkr 9.10.0 → 9.12.0

package/src/config/index.js

@@ -809,6 +809,33 @@ var config = {
     extraction: {
       enabled: memoryExtractionEnabled,
     },
+    // TencentDB-Agent-Memory-inspired token optimization (L0-L3 pipeline).
+    // Fixed defaults by design — tune here, not via env.
+    distillation: {
+      enabled: true,
+      turnThreshold: 10, // distill once conversation reaches 10 user turns
+      keepRecentTurns: 3, // last 3 user turns stay verbatim
+      // Size-based rescue trigger: fires regardless of turn count once the
+      // history alone hits this many estimated tokens, so small-context
+      // local models (4k-8k) don't overflow before the turn threshold.
+      tokenThreshold: 3000,
+      // Cache-aware routing (Phase 5): once emitted, the distilled block is
+      // frozen and only re-distilled every this-many user turns, so the
+      // block stays byte-identical between refreshes and compounds provider
+      // prompt-cache hits instead of rewriting history on every request.
+      // The stable-breakpoint hierarchy in prompt-cache-injection.js shares
+      // this K for its frozen history boundary.
+      refreshEveryTurns: 5,
+    },
+    skills: {
+      enabled: true,
+      minSavings: 0.6, // compression outcome must save 60%+ to be cached
+    },
+    wiki: {
+      enabled: true,
+      minTokens: 500, // register blocks larger than ~500 tokens
+      similarityThreshold: 0.85,
+    },
     decay: {
       enabled: memoryDecayEnabled,
       halfLifeDays: Number.isNaN(memoryDecayHalfLifeDays) ? 30 : memoryDecayHalfLifeDays,
@@ -888,6 +915,41 @@ var config = {
     provider: headroomProvider,
     logLevel: headroomLogLevel,
   },
+  // TencentDB-Agent-Memory sidecar (memory-core + memory-hub, Docker Hub
+  // `agentmemory/*` images). Opt-in like Headroom; when enabled, `lynkr start`
+  // launches both containers. Their internal LLM calls default to routing
+  // back through Lynkr itself, so no extra API key is needed.
+  tencentdbMemory: {
+    enabled: process.env.TENCENTDB_MEMORY_ENABLED === "true",
+    docker: {
+      enabled: process.env.TENCENTDB_MEMORY_DOCKER_ENABLED !== "false", // default true when sidecar enabled
+      network: "tdai-memory-stack",
+      core: {
+        image: process.env.TENCENTDB_MEMORY_CORE_IMAGE ?? "agentmemory/memory-core:latest",
+        containerName: "tdai-memory-core",
+        port: Number.parseInt(process.env.TENCENTDB_MEMORY_CORE_PORT ?? "8420", 10),
+        volume: "tdai-memory-core-data",
+      },
+      hub: {
+        image: process.env.TENCENTDB_MEMORY_HUB_IMAGE ?? "agentmemory/memory-hub:latest",
+        containerName: "tdai-memory-hub",
+        panelPort: Number.parseInt(process.env.TENCENTDB_MEMORY_PANEL_PORT ?? "8125", 10),
+        knowledgePort: Number.parseInt(process.env.TENCENTDB_MEMORY_KNOWLEDGE_PORT ?? "8424", 10),
+        volume: "tdai-panel-data",
+      },
+    },
+    // LLM the memory services use for extraction/summarization/wiki ingest.
+    // Defaults route through Lynkr's own OpenAI-compatible endpoint (tier
+    // routing decides the actual model), so local Ollama setups run free.
+    llm: {
+      baseUrl: process.env.TENCENTDB_MEMORY_LLM_BASE_URL
+        ?? `http://host.docker.internal:${Number.isNaN(port) ? 8080 : port}/v1`,
+      apiKey: process.env.TENCENTDB_MEMORY_LLM_API_KEY ?? "lynkr-local",
+      model: process.env.TENCENTDB_MEMORY_LLM_MODEL ?? "auto",
+      protocol: process.env.TENCENTDB_MEMORY_LLM_PROTOCOL ?? "openai",
+    },
+    promptMode: process.env.TENCENTDB_MEMORY_PROMPT_MODE ?? "code", // code | chat
+  },
   security: {
     // Content filtering
     contentFilterEnabled: process.env.SECURITY_CONTENT_FILTER_ENABLED !== "false", // default true
@@ -949,6 +1011,21 @@ var config = {
     // If all exit 0, short-circuit the request with zero LLM cost.
     preflightEnabled: process.env.LYNKR_PREFLIGHT_ENABLED === 'true',
     preflightTimeoutMs: Number(process.env.LYNKR_PREFLIGHT_TIMEOUT_MS) || 120000,
+    // Cache-aware routing (Phases 1-3). Fixed defaults by design — tune
+    // here, not via env (same policy as memory.distillation).
+    cacheAware: {
+      enabled: true,
+      // Median remaining turns assumed when telemetry is too sparse to
+      // estimate — conservative so a warm pin isn't dropped for a switch
+      // that only pays off over a long horizon that may not happen.
+      defaultRemainingTurns: 10,
+      // Per-turn size assumptions when the payload gives no better signal.
+      newTokensPerTurn: 2000,
+      outputTokensPerTurn: 800,
+      // Local models: switching costs prefill latency, not dollars. Hold
+      // the pin while the warm prefix exceeds this many tokens.
+      localMaxSwitchPrefixTokens: 16000,
+    },
   },
 
   // Model Tier Configuration (REQUIRED)
@@ -973,6 +1050,8 @@ var config = {
     command: process.env.CODE_GRAPH_COMMAND || 'graphify',
     workspace: process.env.CODE_GRAPH_WORKSPACE || process.cwd(),
     timeout: parseInt(process.env.CODE_GRAPH_TIMEOUT, 10) || 10000,
+    maxDepth: 2, // symbol dependency depth for graph queries
+    maxFiles: 5, // max files returned as relevant context
   },
 
   // Large payload optimization (skip cloning media blocks that get discarded)

package/src/context/compression.js

@@ -13,6 +13,13 @@ const logger = require('../logger');
 const config = require('../config');
 const distill = require('./distill');
 
+// Lazy-loaded so requiring this module doesn't pull in the SQLite store
+let skillsCache = null;
+function getSkillsCache() {
+  if (!skillsCache) skillsCache = require('../memory/skills-cache');
+  return skillsCache;
+}
+
 /**
  * Compress conversation history to fit within token budget
  *
@@ -277,14 +284,26 @@ function compressToolResultBlock(block, options = {}) {
     tool_use_id: block.tool_use_id,
   };
 
-  // Compress content using Distill when content is large enough to benefit
+  // Compress content using Distill when content is large enough to benefit.
+  // The skills cache remembers how each output shape compressed before:
+  // known-futile shapes skip dedup work, proven-compressible shapes get a
+  // tighter length budget.
+  const compressWithSkills = (text, previousResult) => {
+    const skills = getSkillsCache();
+    const hints = skills.getCompressionHints(text);
+    const result = distill.compressToolResult(text, {
+      previousResult,
+      maxLength: Math.floor(500 * hints.maxLengthFactor),
+      skipDedup: hints.skipDedup,
+    });
+    const savings = text.length > 0 ? 1 - result.text.length / text.length : 0;
+    skills.record(hints.signature, result.method, savings);
+    return result.text;
+  };
+
   if (typeof block.content === 'string') {
     if (block.content.length > 500) {
-      const result = distill.compressToolResult(block.content, {
-        previousResult: options.previousResult,
-        maxLength: 500,
-      });
-      compressed.content = result.text;
+      compressed.content = compressWithSkills(block.content, options.previousResult);
     } else {
       compressed.content = block.content;
     }
@@ -292,14 +311,14 @@ function compressToolResultBlock(block, options = {}) {
     compressed.content = block.content.map(item => {
       if (typeof item === 'string') {
         if (item.length > 500) {
-          return distill.compressToolResult(item, { maxLength: 500 }).text;
+          return compressWithSkills(item);
         }
         return item;
       } else if (item.type === 'text') {
         if (item.text && item.text.length > 500) {
           return {
             type: 'text',
-            text: distill.compressToolResult(item.text, { maxLength: 500 }).text,
+            text: compressWithSkills(item.text),
           };
         }
         return item;

package/src/context/distill.js

@@ -342,6 +342,7 @@ function deduplicateBlocks(blocks, options = {}) {
  * @param {Object} options
  * @param {string} options.previousResult - Previous tool result for delta rendering
  * @param {number} options.maxLength - Max output length (default 1000)
+ * @param {boolean} options.skipDedup - Skip section dedup (known-futile shapes)
  * @returns {Object} { text, method, stats }
  */
 function compressToolResult(text, options = {}) {
@@ -380,7 +381,7 @@ function compressToolResult(text, options = {}) {
   }
 
   // Step 3: Internal dedup — split into logical sections and dedup
-  const sections = result.split(/\n{2,}/);
+  const sections = options.skipDedup ? [] : result.split(/\n{2,}/);
   if (sections.length > 3) {
     const { compressed, stats } = deduplicateBlocks(sections);
     if (stats.duplicatesRemoved > 0) {

package/src/dashboard/api.js

@@ -205,7 +205,15 @@ function routing(req, res) {
       if (s) providerStats[p] = s;
     }
 
-    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, window: win.label });
+    // Cache-aware routing (Phase 6): per-decision switch/hold economics,
+    // aggregated into "cache dollars saved by routing".
+    const cacheEconomics = telemetry.getCacheEconomics({ since });
+    // Lens money-framing: the MEASURED companion — cache reads actually
+    // served this window, auditable against the bill (vs the projected
+    // figures above). null until cache counters have accrued.
+    const cacheMeasured = telemetry.getMeasuredCacheSavings({ since });
+
+    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, cacheEconomics, cacheMeasured, window: win.label });
   } catch (e) {
     res.status(500).json({ error: 'routing_api_error', detail: e.message });
   }
@@ -229,4 +237,76 @@ function logs(req, res) {
   }
 }
 
-module.exports = { overview, usage, routing, logs };
+/* ── Lens endpoints (feature/lens-dashboard) ─────────────────────────── */
+
+// Recommendations — analyzer findings ranked by past overspend.
+function recommendations(req, res) {
+  try {
+    const engine = require('./recommendations');
+    const windowMs = req.query.window === '30d' ? 30 * 86400000
+      : req.query.window === '24h' ? 86400000
+      : 7 * 86400000;
+    res.json(engine.run({ windowMs, force: req.query.force === 'true' }));
+  } catch (e) {
+    res.status(500).json({ error: 'recommendations_api_error', detail: e.message });
+  }
+}
+
+// Session drill-down: per-model mix + context-growth series + raw rows.
+function sessionDetail(req, res) {
+  try {
+    const detail = telemetry.getSessionDetail(req.params.id);
+    if (!detail) return res.status(404).json({ error: 'session_not_found' });
+    res.json(detail);
+  } catch (e) {
+    res.status(500).json({ error: 'session_api_error', detail: e.message });
+  }
+}
+
+// Pivot explorer: metric × dimension (× stack), whitelisted server-side.
+function analytics(req, res) {
+  try {
+    const days = Math.min(90, Math.max(1, parseInt(req.query.days || '7', 10) || 7));
+    const data = telemetry.getAnalytics({
+      metric: req.query.metric,
+      by: req.query.by,
+      stack: req.query.stack || null,
+      since: Date.now() - days * 86400000,
+    });
+    if (!data) return res.status(503).json({ error: 'telemetry_unavailable' });
+    res.json(data);
+  } catch (e) {
+    res.status(500).json({ error: 'analytics_api_error', detail: e.message });
+  }
+}
+
+// Statusline: one cheap snapshot for the zero-token status line — last
+// routed request, today's spend, measured cache re-read share.
+function statusline(req, res) {
+  try {
+    const last = telemetry.query({ limit: 1 })[0] ?? null;
+    const since = Date.now() - 86400000;
+    const db = telemetry.getDb();
+    let today = null;
+    if (db) {
+      today = db.prepare(
+        `SELECT SUM(COALESCE(cost_usd,0)) spend,
+                SUM(COALESCE(cache_read_tokens,0)) rd,
+                SUM(COALESCE(cache_read_tokens,0)+COALESCE(cache_creation_tokens,0)+COALESCE(input_tokens,0)) total
+         FROM routing_telemetry WHERE timestamp > ?`
+      ).get(since);
+    }
+    res.json({
+      last: last && {
+        tier: last.tier, provider: last.provider, model: last.model,
+        pinned: !!last.pinned, at: last.timestamp,
+      },
+      todaySpendUsd: today?.spend ?? null,
+      cacheReadPct: today && today.total > 0 ? Math.round((today.rd / today.total) * 100) : null,
+    });
+  } catch (e) {
+    res.status(500).json({ error: 'statusline_api_error', detail: e.message });
+  }
+}
+
+module.exports = { overview, usage, routing, logs, recommendations, sessionDetail, analytics, statusline };

package/src/dashboard/recommendations/cache-weakspots.js

@@ -0,0 +1,88 @@
+/**
+ * cache-weakspots — prompt-cache hit ratio per (provider, model), worst first.
+ *
+ * Reads the per-request cache counters (cache_read_tokens /
+ * cache_creation_tokens). Rows recorded before capture began are NULL and
+ * excluded — when nothing has been measured yet the finding says so
+ * explicitly instead of reporting a fake all-clear.
+ */
+
+const MIN_REQUESTS = 5;
+const WEAK_RATIO = 0.5;
+
+module.exports = {
+  id: 'cache-weakspots',
+  title: 'Weak prompt-cache hit ratios',
+
+  analyze({ db, since }) {
+    const rows = db
+      .prepare(
+        `SELECT provider, model, COUNT(*) n,
+                SUM(COALESCE(cache_read_tokens,0)) rd,
+                SUM(COALESCE(cache_creation_tokens,0)) cr,
+                SUM(COALESCE(input_tokens,0)) inp
+         FROM routing_telemetry
+         WHERE timestamp > ? AND cache_read_tokens IS NOT NULL
+         GROUP BY provider, model
+         HAVING COUNT(*) >= ${MIN_REQUESTS}`
+      )
+      .all(since);
+
+    if (!rows.length) {
+      return {
+        id: this.id, title: this.title, mechanism: 'info', state: 'not_measured',
+        framing: 'usd', pastOverspendUsd: null, pastOverspendTokens: null,
+        stats: [], evidence: { columns: [], rows: [] }, fix: null,
+        caveat: null,
+        estimateBasis: 'Cache counters are captured from this version onward — data accrues as requests flow. An un-run measurement is not an all-clear.',
+      };
+    }
+
+    const { resolveCacheEconomics } = require('../../routing/cache-economics');
+    const weak = [];
+    let usd = 0;
+    for (const r of rows) {
+      const total = r.rd + r.cr + r.inp;
+      const ratio = total > 0 ? r.rd / total : 0;
+      if (ratio >= WEAK_RATIO) continue;
+      const econ = resolveCacheEconomics(r.provider, r.model);
+      // Ceiling: what the uncached input cost beyond cache-read price.
+      const missedUsd = econ.unknownPricing || econ.mechanism === 'local'
+        ? null
+        : (r.inp * Math.max(0, econ.inputPerM - econ.cacheReadPerM)) / 1_000_000;
+      if (missedUsd != null) usd += missedUsd;
+      weak.push([r.provider, r.model, r.n, `${Math.round(ratio * 100)}%`, r.inp, missedUsd ?? '(local/unknown)']);
+    }
+
+    if (!weak.length) {
+      return {
+        id: this.id, title: this.title, mechanism: 'info', state: 'clean',
+        framing: 'usd', pastOverspendUsd: 0, pastOverspendTokens: null,
+        stats: [{ label: 'models measured', value: rows.length }],
+        evidence: { columns: [], rows: [] }, fix: null, caveat: null,
+        estimateBasis: `Hit ratio = cache reads ÷ (reads + writes + uncached input); weak = below ${WEAK_RATIO * 100}%.`,
+      };
+    }
+
+    return {
+      id: this.id,
+      title: this.title,
+      mechanism: 'info',
+      state: 'actionable',
+      framing: 'usd',
+      pastOverspendUsd: usd,
+      pastOverspendTokens: null,
+      stats: [
+        { label: 'weak (provider, model) pairs', value: weak.length },
+        { label: 'models measured', value: rows.length },
+      ],
+      evidence: {
+        columns: ['provider', 'model', 'requests', 'hit ratio', 'uncached input tokens', 'ceiling $'],
+        rows: weak.sort((a, b) => parseFloat(a[3]) - parseFloat(b[3])),
+      },
+      fix: 'Low ratios usually mean an unstable prefix: per-request bytes in the system prompt, client-side history rewrites, or conversations too short to cache. Check the silent-invalidator list and whether the distiller freeze covers these sessions.',
+      caveat: 'The dollar figure is a CEILING — it prices every uncached input token at the read discount, which assumes perfect cacheability. Real recovery is lower.',
+      estimateBasis: 'Uncached input tokens × (input price − cache-read price) for pairs below a 50% hit ratio, this window. NULL-counter rows (pre-capture) excluded.',
+    };
+  },
+};

package/src/dashboard/recommendations/deadweight.js

@@ -0,0 +1,82 @@
+/**
+ * deadweight — tool schemas carried on every request but never called.
+ *
+ * Telemetry stores per-request tool COUNTS, not names, so the detectable
+ * unit is the session: sessions whose every request shipped a tool loadout
+ * and whose tool_calls_made never left zero paid schema rent for nothing.
+ * (Per-tool attribution needs tool names in telemetry — future work.)
+ */
+
+const EST_TOKENS_PER_TOOL = 150; // typical JSON schema; stated in estimateBasis
+const MIN_REQUESTS = 3;
+
+module.exports = {
+  id: 'deadweight',
+  title: 'Tool schemas carried but never used',
+
+  analyze({ db, since }) {
+    const rows = db
+      .prepare(
+        `SELECT session_id,
+                COUNT(*) reqs,
+                AVG(COALESCE(tool_count,0)) avg_tools,
+                MAX(model) model,
+                MAX(provider) provider,
+                SUM(COALESCE(cost_usd,0)) session_cost
+         FROM routing_telemetry
+         WHERE timestamp > ? AND session_id IS NOT NULL AND COALESCE(tool_count,0) > 0
+         GROUP BY session_id
+         HAVING SUM(COALESCE(tool_calls_made,0)) = 0 AND COUNT(*) >= ${MIN_REQUESTS}
+         ORDER BY reqs * avg_tools DESC
+         LIMIT 50`
+      )
+      .all(since);
+
+    if (!rows.length) {
+      return {
+        id: this.id, title: this.title, mechanism: 'snippet', state: 'clean',
+        framing: 'usd', pastOverspendUsd: 0, pastOverspendTokens: 0,
+        stats: [], evidence: { columns: [], rows: [] },
+        fix: null, caveat: null,
+        estimateBasis: 'Sessions with >=3 requests, a tool loadout on every request, and zero tool calls.',
+      };
+    }
+
+    const { resolveCacheEconomics } = require('../../routing/cache-economics');
+    let tokens = 0;
+    let usd = 0;
+    const evidence = [];
+    for (const r of rows) {
+      const wastedTokens = Math.round(r.avg_tools * EST_TOKENS_PER_TOOL * r.reqs);
+      tokens += wastedTokens;
+      const econ = resolveCacheEconomics(r.provider, r.model);
+      const rowUsd = econ.unknownPricing ? null : (wastedTokens * econ.inputPerM) / 1_000_000;
+      if (rowUsd != null) usd += rowUsd;
+      evidence.push([
+        r.session_id, r.reqs, Math.round(r.avg_tools), wastedTokens,
+        rowUsd != null ? rowUsd : '(price unknown)',
+      ]);
+    }
+
+    return {
+      id: this.id,
+      title: this.title,
+      mechanism: 'snippet',
+      state: 'actionable',
+      framing: 'usd',
+      pastOverspendUsd: usd,
+      pastOverspendTokens: tokens,
+      stats: [
+        { label: 'sessions affected', value: rows.length },
+        { label: 'est. schema tokens re-sent', value: tokens },
+      ],
+      evidence: {
+        columns: ['session', 'requests', 'avg tools', 'est. wasted tokens', 'est. $'],
+        rows: evidence,
+      },
+      fix: 'These sessions never called a tool — their MCP servers/tool registrations paid schema rent on every request. Trim unused MCP servers from the client config, or scope them per-project.',
+      caveat: 'Schema size is estimated at ~150 tokens per tool; telemetry stores tool counts, not names, so attribution is per-session rather than per-tool.',
+      estimateBasis: 'avg tools × ~150 est. tokens/schema × requests per session, priced at each session\'s model input rate. Sessions with any tool call are excluded entirely.',
+    };
+  },
+};

package/src/dashboard/recommendations/downsize.js

@@ -0,0 +1,109 @@
+/**
+ * downsize — request types where the tier below has statistically proven
+ * itself, Wilson-bounded.
+ *
+ * The de-escalator's live rule uses raw averages (>=30 rows, avg quality
+ * >=70). This analyzer applies the stricter test TokenJam-bench uses for
+ * verdicts: the WILSON LOWER BOUND of the lower tier's success rate must
+ * clear the bar, so 21-of-30 (lower bound ~0.52) stays "unproven" while
+ * 140-of-170 (~0.76) is a verdict. Success = quality >= 70 and no error.
+ *
+ * No quality-equivalence claim is made — the verdict is "the lower tier's
+ * measured floor clears the bar on this request type", nothing more.
+ */
+
+const { wilsonLowerBound } = require('./wilson');
+
+const TIER_ORDER = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+const MIN_SAMPLES = 20;
+const SUCCESS_QUALITY = 70;
+const WILSON_BAR = 0.7;
+const EVIDENCE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // evidence looks back further than the spend window
+
+module.exports = {
+  id: 'downsize',
+  title: 'Tiers that could step down (Wilson-proven)',
+
+  analyze({ db, since, until }) {
+    // Lower-tier track record per request_type over 30 days.
+    const evidence = db
+      .prepare(
+        `SELECT tier, request_type,
+                COUNT(*) n,
+                SUM(CASE WHEN COALESCE(quality_score,0) >= ${SUCCESS_QUALITY} AND error_type IS NULL THEN 1 ELSE 0 END) k,
+                AVG(COALESCE(cost_usd,0)) avg_cost
+         FROM routing_telemetry
+         WHERE timestamp > ? AND tier IS NOT NULL AND request_type IS NOT NULL
+         GROUP BY tier, request_type`
+      )
+      .all(until - EVIDENCE_WINDOW_MS);
+
+    const byKey = new Map(evidence.map((r) => [`${r.tier}::${r.request_type}`, r]));
+
+    // Spend at each upper tier per request_type, this window.
+    const upperSpend = db
+      .prepare(
+        `SELECT tier, request_type, COUNT(*) n, SUM(COALESCE(cost_usd,0)) cost, AVG(COALESCE(cost_usd,0)) avg_cost
+         FROM routing_telemetry
+         WHERE timestamp > ? AND tier IS NOT NULL AND request_type IS NOT NULL
+         GROUP BY tier, request_type`
+      )
+      .all(since);
+
+    const rows = [];
+    let usd = 0;
+    let anyEvidence = false;
+    for (const u of upperSpend) {
+      const idx = TIER_ORDER.indexOf(u.tier);
+      if (idx <= 0) continue;
+      const lower = byKey.get(`${TIER_ORDER[idx - 1]}::${u.request_type}`);
+      if (!lower) continue;
+      anyEvidence = true;
+      if (lower.n < MIN_SAMPLES) continue;
+      const bound = wilsonLowerBound(lower.k, lower.n);
+      if (bound < WILSON_BAR) continue;
+      // Empirical per-request price delta between the two tiers on the SAME
+      // request type — measured, not modeled.
+      const delta = Math.max(0, (u.avg_cost ?? 0) - (lower.avg_cost ?? 0)) * u.n;
+      usd += delta;
+      rows.push([
+        u.request_type, u.tier, `${TIER_ORDER[idx - 1]}`,
+        `${lower.k}/${lower.n}`, bound.toFixed(2), u.n, delta,
+      ]);
+    }
+
+    if (!rows.length) {
+      return {
+        id: this.id, title: this.title, mechanism: 'info',
+        state: anyEvidence ? 'clean' : 'not_measured',
+        framing: 'usd', pastOverspendUsd: anyEvidence ? 0 : null, pastOverspendTokens: null,
+        stats: [],
+        evidence: { columns: [], rows: [] }, fix: null, caveat: null,
+        estimateBasis: anyEvidence
+          ? `No (tier, request_type) pair has a lower tier whose Wilson lower bound clears ${WILSON_BAR} on >=${MIN_SAMPLES} samples yet.`
+          : 'Needs quality-scored telemetry with request_type populated — accrues as traffic flows (request_type capture is recent).',
+      };
+    }
+
+    rows.sort((a, b) => b[6] - a[6]);
+    return {
+      id: this.id,
+      title: this.title,
+      mechanism: 'info',
+      state: 'actionable',
+      framing: 'usd',
+      pastOverspendUsd: usd,
+      pastOverspendTokens: null,
+      stats: [
+        { label: 'proven (request_type, tier) pairs', value: rows.length },
+      ],
+      evidence: {
+        columns: ['request_type', 'served tier', 'proven lower tier', 'lower success', 'Wilson lower bound', 'requests this window', 'measured delta $'],
+        rows,
+      },
+      fix: 'The live de-escalator will demote these automatically as its own thresholds clear; to act sooner, adjust the TIER_* mapping for these request types or lower the de-escalator sample bar deliberately.',
+      caveat: 'Verdict is "the lower tier\'s measured success floor clears the bar" — not quality equivalence. Success = quality >= 70 with no error.',
+      estimateBasis: 'Per-request cost delta between tiers measured on the SAME request_type (30-day evidence window), × this window\'s upper-tier request count. Wilson 95% lower bound.',
+    };
+  },
+};

package/src/dashboard/recommendations/index.js

@@ -0,0 +1,106 @@
+/**
+ * Lens recommendations engine.
+ *
+ * Registry-driven analyzers over routing telemetry that answer "what should
+ * the operator change", TokenJam-style, with three disciplines borrowed
+ * deliberately:
+ *
+ *  - PAST OVERSPEND, never projected savings: every dollar figure is
+ *    backward-looking so the operator can check it against a bill already
+ *    paid. Ceilings are labeled as ceilings in estimateBasis.
+ *  - THREE-STATE HONESTY: 'actionable' (evidence found), 'clean' (ran,
+ *    found nothing), 'not_measured' (data doesn't exist yet on this
+ *    install). An un-run scan is not an all-clear.
+ *  - MECHANISM badges: 'auto' (Lynkr could act), 'snippet' (client-side
+ *    fix the operator applies), 'info' (diagnosis only).
+ *
+ * Analyzer contract: analyze({db, since, until}) -> finding
+ *   {id, title, mechanism, state, framing: 'usd'|'tokens',
+ *    pastOverspendUsd|null, pastOverspendTokens|null, stats: [{label,value}],
+ *    evidence: {columns:[], rows:[][]}, fix, caveat, estimateBasis}
+ *
+ * The analyzers' overspend bases are disjoint by construction (dead tool
+ * schemas / harness side traffic / uncached input / tier price deltas), so
+ * the total is a plain sum — revisit if an analyzer is added whose basis
+ * overlaps an existing one.
+ *
+ * @module dashboard/recommendations
+ */
+
+const logger = require('../../logger');
+const telemetry = require('../../routing/telemetry');
+
+const ANALYZERS = [
+  require('./deadweight'),
+  require('./side-requests'),
+  require('./cache-weakspots'),
+  require('./downsize'),
+];
+
+const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const RESULT_TTL_MS = 45 * 1000;
+
+let _cached = null;
+
+/**
+ * Run all analyzers. Cached for 45s — findings shift slowly and the
+ * dashboard polls every 30s.
+ *
+ * @param {Object} [opts] {windowMs, force}
+ */
+function run(opts = {}) {
+  const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
+  if (!opts.force && _cached && Date.now() - _cached.computedAt < RESULT_TTL_MS
+    && _cached.windowMs === windowMs) {
+    return _cached;
+  }
+
+  const db = telemetry.getDb();
+  const until = Date.now();
+  const since = until - windowMs;
+
+  const findings = [];
+  for (const analyzer of ANALYZERS) {
+    try {
+      const finding = db
+        ? analyzer.analyze({ db, since, until })
+        : { id: analyzer.id, title: analyzer.title, state: 'not_measured', reason: 'telemetry unavailable' };
+      if (finding) findings.push(finding);
+    } catch (err) {
+      logger.debug({ analyzer: analyzer.id, err: err.message }, '[Recommendations] analyzer failed');
+      findings.push({ id: analyzer.id, title: analyzer.title, state: 'not_measured', reason: err.message });
+    }
+  }
+
+  // Rank by dollars, biggest first; token-framed findings after usd ones.
+  findings.sort((a, b) => (b.pastOverspendUsd ?? -1) - (a.pastOverspendUsd ?? -1));
+
+  let spendUsd = 0;
+  try {
+    if (db) {
+      spendUsd = db
+        .prepare('SELECT SUM(COALESCE(cost_usd,0)) s FROM routing_telemetry WHERE timestamp > ?')
+        .get(since)?.s ?? 0;
+    }
+  } catch { /* spend share stays 0 */ }
+
+  const totalRecoverableUsd = findings
+    .filter((f) => f.state === 'actionable' && typeof f.pastOverspendUsd === 'number')
+    .reduce((acc, f) => acc + f.pastOverspendUsd, 0);
+
+  _cached = {
+    computedAt: Date.now(),
+    windowMs,
+    spendUsd,
+    totalRecoverableUsd,
+    findings,
+  };
+  return _cached;
+}
+
+/** Test helper — drop the memoized result. */
+function _clearCacheForTests() {
+  _cached = null;
+}
+
+module.exports = { run, ANALYZERS, _clearCacheForTests };