@cachly-dev/mcp-server 0.10.56 → 0.10.58

package/packages/telegram-notify/telegram_notify/client.py

@@ -0,0 +1,87 @@
+"""
+telegram-notify — shared Telegram notification client.
+
+Used by TCO backend (Python) and importable as a pip local package.
+Single source of truth for: emoji map, message format, env var convention.
+
+Interface: notify(app, event, payload)
+          notify_user(db, user_id, message)   — direct DM via stored chat_id
+
+Env vars:
+  TELEGRAM_BOT_TOKEN            — bot token from @BotFather
+  {APP_UPPER}_TELEGRAM_CHAT_ID  — app-specific channel (e.g. TCO_TELEGRAM_CHAT_ID)
+  TELEGRAM_CHAT_ID              — fallback for all apps
+
+No-op when unconfigured. Never throws.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+_EMOJI: dict[str, str] = json.loads(
+    (Path(__file__).parent / "emojis.json").read_text()
+)
+
+
+def _token() -> str:
+    return os.getenv("TELEGRAM_BOT_TOKEN", "")
+
+
+def _chat_id(app: str) -> str:
+    key = f"{app.upper()}_TELEGRAM_CHAT_ID"
+    return os.getenv(key) or os.getenv("TELEGRAM_CHAT_ID", "")
+
+
+def format_message(app: str, event: str, payload: dict[str, Any]) -> str:
+    icon = _EMOJI.get(event, _EMOJI["default"])
+    lines = [f"{icon} *{app.upper()}* · `{event}`"]
+    for k, v in payload.items():
+        if v is not None and v != "":
+            lines.append(f"  {k}: `{v}`")
+    return "\n".join(lines)
+
+
+async def notify(app: str, event: str, payload: dict[str, Any] | None = None) -> None:
+    """Send event notification to the app's configured Telegram channel."""
+    token = _token()
+    chat_id = _chat_id(app)
+    if not token or not chat_id:
+        return
+    try:
+        import httpx
+        text = format_message(app, event, payload or {})
+        async with httpx.AsyncClient(timeout=5) as client:
+            await client.post(
+                f"https://api.telegram.org/bot{token}/sendMessage",
+                json={"chat_id": chat_id, "text": text, "parse_mode": "Markdown"},
+            )
+    except Exception:
+        pass  # never raises
+
+
+async def notify_user(db: Any, user_id: str, message: str) -> None:
+    """Send a direct Telegram message to a user by their DB user_id.
+    Looks up telegram_chat_id from the users table. No-op if not linked."""
+    token = _token()
+    if not token:
+        return
+    try:
+        from sqlalchemy import text as sql_text
+        result = await db.execute(
+            sql_text("SELECT telegram_chat_id FROM users WHERE id = :uid"),
+            {"uid": user_id},
+        )
+        row = result.fetchone()
+        if not row or not row[0]:
+            return
+        import httpx
+        async with httpx.AsyncClient(timeout=5) as client:
+            await client.post(
+                f"https://api.telegram.org/bot{token}/sendMessage",
+                json={"chat_id": row[0], "text": message, "parse_mode": "Markdown"},
+            )
+    except Exception:
+        pass  # never raises

package/packages/telegram-notify/telegram_notify/emojis.json

@@ -0,0 +1,22 @@
+{
+  "tool_call":             "🔧",
+  "tool_error":            "🔴",
+  "cache_hit":             "⚡",
+  "cache_miss":            "💭",
+  "auth_ok":               "🔑",
+  "auth_fail":             "🚫",
+  "startup":               "🚀",
+  "waitlist_signup":       "📬",
+  "parse_file":            "📄",
+  "parse_text":            "📝",
+  "parse_url":             "🔗",
+  "trip_created":          "🗺️",
+  "trip_deleted":          "🗑️",
+  "error":                 "🔴",
+  "stripe_payment":        "💳",
+  "stripe_checkout":       "🛒",
+  "new_user":              "🆕",
+  "pdf_export":            "📑",
+  "trip_search":           "🔍",
+  "default":               "🔔"
+}

package/scripts/generate-icons.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Converts SVG icon assets to PNG for Expo.
+ * Run: node scripts/generate-icons.js
+ * Requires: npm install -g sharp-cli  OR  npx sharp-cli
+ */
+const { execSync } = require('child_process');
+const path = require('path');
+
+const frontend = path.join(__dirname, '..', 'apps', 'travel-chaos-organizer', 'frontend');
+
+const conversions = [
+  { input: 'assets/icon.svg', output: 'assets/icon.png', width: 1024, height: 1024 },
+  { input: 'assets/adaptive-icon.svg', output: 'assets/adaptive-icon.png', width: 1024, height: 1024 },
+  { input: 'assets/icon.svg', output: 'assets/splash.png', width: 1284, height: 2778 },
+  { input: 'assets/icon.svg', output: 'assets/favicon.png', width: 32, height: 32 },
+];
+
+for (const { input, output, width, height } of conversions) {
+  const src = path.join(frontend, input);
+  const dst = path.join(frontend, output);
+  try {
+    execSync(`npx sharp-cli --input "${src}" --output "${dst}" resize ${width} ${height}`, { stdio: 'inherit' });
+    console.log(`✓ ${output}`);
+  } catch {
+    console.error(`✗ ${output} — install sharp-cli: npm i -g sharp-cli`);
+  }
+}

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 89 MCP tools · Free tier · EU servers · GDPR.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 95 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.23",
+  "version": "0.10.58",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.23",
+      "version": "0.10.58",
       "transport": {
         "type": "stdio"
       }

package/smithery.yaml

@@ -1,27 +1,21 @@
 name: cachly AI Brain
 description: >
-  Your AI forgets everything between sessions. cachly fixes that permanently.
-  One command, 30 seconds, free forever — your AI arrives pre-briefed from your git history.
-  brain_from_git: learns 500 commits in 30s — no setup needed.
-  causal_trace: root-cause any error by tracing what caused what in your project history.
-  brain_predict: predicts likely failures before you make a change.
-  team_learn: share what you fixed — teammates' AI knows it immediately.
-  session_start: every conversation opens with a full briefing, not a blank slate.
-  80 tools. Claude Code, Cursor, Copilot, Windsurf, Cline & Zed. GDPR. EU servers. Free tier forever.
+  Persistent AI memory for Claude Code, Cursor, Copilot, Windsurf, Cline & Zed.
+  Your AI remembers every lesson, fix, and architecture decision — forever.
+  Features: causal root-cause analysis (causal_trace), failure prediction (brain_predict),
+  git-ambient learning (brain_from_git), team knowledge sharing, Memory Crystals,
+  BM25+ search in 11 languages. 80 MCP tools. Free tier. GDPR. German servers.
+  Zero-config: sign in once via browser, auto-provisions your Brain instance.
 
-# Streamable HTTP — hosted on our infrastructure (mcp.cachly.dev).
-# Multi-tenant: per-request CACHLY_JWT + instance ID resolved from
-# Authorization header + X-Cachly-Instance-Id, or Smithery ?config= param.
 startCommand:
-  type: http
-  url: https://mcp.cachly.dev/mcp
+  type: stdio
   configSchema:
     type: object
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Get your free API key at https://cachly.dev/setup-ai (no credit card)."
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
@@ -31,4 +25,21 @@ startCommand:
         pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
         examples:
           - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
-
+      CACHLY_API_URL:
+        type: string
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
+        default: "https://api.cachly.dev"
+    required: []
+  commandFunction: |-
+    (config) => ({
+      command: "npx",
+      args: ["-y", "@cachly-dev/mcp-server@latest"],
+      env: Object.fromEntries(
+        Object.entries({
+          CACHLY_JWT: config.CACHLY_JWT,
+          CACHLY_BRAIN_INSTANCE_ID: config.CACHLY_BRAIN_INSTANCE_ID,
+          CACHLY_API_URL: config.CACHLY_API_URL ?? "https://api.cachly.dev",
+        }).filter(([, v]) => v != null && v !== "")
+      )
+    })

package/src/__tests__/auth.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
 
 function makeJwt(payload: Record<string, unknown>): string {

package/src/__tests__/brain-flow.test.ts

@@ -10,13 +10,14 @@
  * Run: npx vitest run src/__tests__/brain-flow.test.ts
  */
 
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { EventEmitter } from 'node:events';
 
 // ── Modules under test ────────────────────────────────────────────────────────
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import { EMBED_PROVIDER, hasEmbedProvider, embedProviderHint, embedConfig, setEmbedJwt } from '../embeddings.js';
 import { keywordSearch } from '../search.js';
+import { handleBrainTool } from '../handlers/brain.js';
 import type { Redis } from 'ioredis';
 
 // ── In-memory Redis mock ──────────────────────────────────────────────────────
@@ -67,6 +68,21 @@ class MockRedis {
     return [...(this.sets.get(key) ?? [])];
   }
 
+  async mget(...keys: string[]): Promise<(string | null)[]> {
+    return keys.map(k => this.store.get(k) ?? null);
+  }
+
+  async exists(key: string): Promise<number> {
+    return this.store.has(key) ? 1 : 0;
+  }
+
+  async incrbyfloat(key: string, increment: number): Promise<string> {
+    const cur = parseFloat(this.store.get(key) ?? '0');
+    const next = cur + increment;
+    this.store.set(key, String(next));
+    return String(next);
+  }
+
   /** Simplified scanStream: returns all matching keys in a single 'data' event. */
   scanStream(opts: { match: string; count?: number }): EventEmitter {
     const emitter = new EventEmitter();
@@ -872,3 +888,161 @@ describe('Brain Flow: advanced scenarios', () => {
     });
   });
 });
+
+// ── New feature coverage (0.10.41 / 0.10.42) ─────────────────────────────────
+// Trust badges, Proven Laws crystallization, and focus-less predictive warning.
+// These exercise the REAL handleBrainTool code path with the MockRedis.
+
+const noopApiFetch = (async () => null) as unknown as Parameters<typeof handleBrainTool>[3];
+
+/** Seed a best-solution lesson with an explicit recall_count / authors / pinned. */
+async function seedLesson(
+  redis: MockRedis,
+  topic: string,
+  opts: {
+    outcome?: 'success' | 'failure' | 'partial';
+    what_worked?: string;
+    what_failed?: string;
+    recall_count?: number;
+    severity?: 'critical' | 'major' | 'minor';
+    pinned?: boolean;
+    author?: string;
+    tags?: string[];
+  } = {},
+): Promise<void> {
+  const ts = new Date().toISOString();
+  const obj = {
+    topic,
+    outcome: opts.outcome ?? 'success',
+    what_worked: opts.what_worked ?? `solution for ${topic}`,
+    what_failed: opts.what_failed,
+    severity: opts.severity ?? 'minor',
+    recall_count: opts.recall_count ?? 0,
+    ts,
+    verified_at: ts,
+    confidence: 1.0,
+    tags: opts.tags ?? [],
+    ...(opts.pinned ? { pinned: true } : {}),
+    ...(opts.author ? { author: opts.author } : {}),
+  };
+  await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(obj));
+}
+
+describe('Trust badges (recall_best_solution)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('shows "Battle-tested" when recall_count crosses 10', async () => {
+    await seedLesson(redis, 'redis:pool', { recall_count: 9, what_worked: 'set max_retries=3' });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'redis:pool' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Battle-tested');
+    expect(out).toContain('recalled 10×');
+  });
+
+  it('shows "Proven" when recall_count is between 5 and 9', async () => {
+    await seedLesson(redis, 'api:auth', { recall_count: 4 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'api:auth' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven');
+    expect(out).toContain('recalled 5×');
+    expect(out).not.toContain('Battle-tested');
+  });
+
+  it('shows no trust badge for a fresh low-recall lesson', async () => {
+    await seedLesson(redis, 'misc:thing', { recall_count: 0 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'misc:thing' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Battle-tested');
+    expect(out).not.toContain('Proven —');
+    expect(out).not.toContain('Team-verified');
+  });
+
+  it('increments recall_count and persists it', async () => {
+    await seedLesson(redis, 'deploy:x', { recall_count: 2 });
+    await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'deploy:x' }, getConn, noopApiFetch);
+    const stored = JSON.parse((await redis.get('cachly:lesson:best:deploy:x'))!);
+    expect(stored.recall_count).toBe(3);
+  });
+});
+
+describe('Proven Laws crystallization (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(async () => {
+    redis = new MockRedis();
+    // Provide a last session so session_start does not attempt git reconstruction.
+    await redis.set('cachly:session:last', JSON.stringify({ summary: 'prior work', ts: new Date().toISOString(), files_changed: [] }));
+  });
+
+  it('surfaces lessons recalled >= 5 in the Proven Laws section', async () => {
+    await seedLesson(redis, 'infra:k3s', { recall_count: 7, what_worked: 'add WireGuard IP to TLS-SAN' });
+    await seedLesson(redis, 'random:note', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('infra:k3s');
+    expect(out).toContain('recalled 7×');
+  });
+
+  it('surfaces an explicitly pinned lesson even with low recall', async () => {
+    await seedLesson(redis, 'team:convention', { recall_count: 0, pinned: true, what_worked: 'always snake_case handlers' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('team:convention');
+    expect(out).toContain('pinned');
+  });
+
+  it('omits the Proven Laws section when nothing qualifies', async () => {
+    await seedLesson(redis, 'small:thing', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+
+  it('does not crystallize failure lessons', async () => {
+    await seedLesson(redis, 'broken:flow', { recall_count: 9, outcome: 'failure', what_failed: 'never works' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+});
+
+describe('Predictive pre-warning without explicit focus (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('derives danger area from last session files and warns', async () => {
+    // Last session touched payment files → likely to continue there.
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'worked on payment integration',
+      ts: new Date().toISOString(),
+      files_changed: ['api/payment/stripe_webhook.go'],
+    }));
+    // A known failure in the payment area.
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'missed idempotency key → double charge', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('PRE-WARNING');
+    expect(out).toContain('payment:webhook');
+  });
+
+  it('does not warn when last-session area has no known failures', async () => {
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'wrote docs',
+      ts: new Date().toISOString(),
+      files_changed: ['docs/readme.md'],
+    }));
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'x', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+
+  it('filters path noise so common segments do not trigger false matches', async () => {
+    // Last session only touched generic noise paths (src/lib/index).
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'refactor',
+      ts: new Date().toISOString(),
+      files_changed: ['src/lib/index.ts'],
+    }));
+    // A failure tagged 'src' — should NOT match because 'src' is noise.
+    await seedLesson(redis, 'src:thing', { outcome: 'failure', what_failed: 'noise', tags: ['src'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+});

package/src/__tests__/e2e/api-health.test.ts

@@ -5,7 +5,7 @@
  * Run: E2E_API_URL=https://api.dev.cachly.dev npx vitest run src/__tests__/e2e/api-health.test.ts
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { cfg } from './config.js';
 
 describe('API health (no auth required)', () => {

package/src/__tests__/handlers-unit.test.ts

@@ -334,8 +334,7 @@ describe('handleRoadmapTool', () => {
       // Add and complete one item
       const addResult = await handleRoadmapTool('roadmap_add', { instance_id: INSTANCE, title: 'Finished task', priority: 'low' }, getConnection, apiFetch);
       const idMatch = addResult!.match(/`(rm_[a-z0-9_]+)`/);
-      if (!idMatch) throw new Error('expected roadmap id in add result');
-      const id = idMatch[1];
+      const id = idMatch![1];
       await handleRoadmapTool('roadmap_update', { instance_id: INSTANCE, id, status: 'done' }, getConnection, apiFetch);
 
       const result = await handleRoadmapTool('roadmap_list', { instance_id: INSTANCE, status: 'done' }, getConnection, apiFetch);

package/src/__tests__/rerank.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for quality-aware reranking and the Cachly-Bench regression guard.
+ */
+import { describe, it, expect } from 'vitest';
+import { qualityMultiplier, extractLessonQuality, rerankByQuality, type LessonQuality } from '../rerank.js';
+import type { KeywordMatch } from '../search.js';
+import { runBenchmark } from '../bench/cachly-bench.js';
+
+const lessonMatch = (topic: string, score: number, lesson: Partial<LessonQuality> & Record<string, unknown>): KeywordMatch => ({
+  key: `cachly:lesson:best:${topic}`,
+  content: JSON.stringify(lesson),
+  score,
+  matchedWords: ['x'],
+});
+
+describe('qualityMultiplier', () => {
+  it('returns neutral 1.0 for documents with no quality signal', () => {
+    expect(qualityMultiplier(null)).toBe(1.0);
+    expect(qualityMultiplier({})).toBe(1.0);
+  });
+
+  it('ranks a proven success above a fresh failure', () => {
+    const success = qualityMultiplier({ outcome: 'success', confidence: 0.95, recall_count: 12 });
+    const failure = qualityMultiplier({ outcome: 'failure', confidence: 0.3, recall_count: 0 });
+    expect(success).toBeGreaterThan(failure);
+  });
+
+  it('rewards proven-ness (recall_count) but saturates', () => {
+    const never = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 0 });
+    const some = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 5 });
+    const many = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 500 });
+    expect(some).toBeGreaterThan(never);
+    expect(many).toBeGreaterThan(some);
+    expect(many - some).toBeLessThan(some - never + 0.2); // diminishing returns
+  });
+
+  it('clamps within [0.5, 2.5]', () => {
+    const hi = qualityMultiplier({ outcome: 'success', confidence: 1, recall_count: 100000, severity: 'critical', review_level: 'senior', reviewed_by: 'x', endorsements: 99 });
+    const lo = qualityMultiplier({ outcome: 'failure', confidence: 0, recall_count: 0, severity: 'minor' });
+    expect(hi).toBeLessThanOrEqual(2.5);
+    expect(lo).toBeGreaterThanOrEqual(0.5);
+  });
+
+  it('boosts a human-reviewed lesson above an unreviewed equal', () => {
+    const base = { outcome: 'success', confidence: 0.8, recall_count: 3 } as const;
+    const unreviewed = qualityMultiplier({ ...base });
+    const peer = qualityMultiplier({ ...base, reviewed_by: 'alice', review_level: 'peer', endorsements: 1 });
+    const senior = qualityMultiplier({ ...base, reviewed_by: 'bob', review_level: 'senior', endorsements: 1 });
+    expect(peer).toBeGreaterThan(unreviewed);
+    expect(senior).toBeGreaterThan(peer);
+  });
+
+  it('rewards additional distinct endorsements but saturates', () => {
+    const base = { outcome: 'success', confidence: 0.8, recall_count: 3, reviewed_by: 'a', review_level: 'peer' } as const;
+    const one = qualityMultiplier({ ...base, endorsements: 1 });
+    const three = qualityMultiplier({ ...base, endorsements: 3 });
+    const fifty = qualityMultiplier({ ...base, endorsements: 50 });
+    expect(three).toBeGreaterThan(one);
+    expect(fifty).toBeGreaterThan(three);
+    expect(fifty - three).toBeLessThan(three - one + 0.1);
+  });
+});
+
+describe('extractLessonQuality', () => {
+  it('parses lesson JSON for lesson keys', () => {
+    const q = extractLessonQuality({ key: 'cachly:lesson:best:foo', content: '{"outcome":"success"}' });
+    expect(q?.outcome).toBe('success');
+  });
+  it('returns null for non-lesson keys (e.g. context)', () => {
+    expect(extractLessonQuality({ key: 'cachly:ctx:custom:foo', content: 'plain text' })).toBeNull();
+  });
+  it('returns null for corrupt lesson JSON', () => {
+    expect(extractLessonQuality({ key: 'cachly:lesson:best:foo', content: '{not json' })).toBeNull();
+  });
+});
+
+describe('rerankByQuality', () => {
+  it('promotes a proven success over a higher-BM25 failure distractor', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('symptom-failure', 10, { outcome: 'failure', confidence: 0.2, recall_count: 0 }),
+      lessonMatch('proven-success', 8, { outcome: 'success', confidence: 0.95, recall_count: 12 }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked[0].key).toBe('cachly:lesson:best:proven-success');
+  });
+
+  it('keeps a strong text match competitive (does not bury it on quality alone)', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('weak-but-perfect', 1, { outcome: 'success', confidence: 1, recall_count: 100 }),
+      lessonMatch('strong-text', 100, { outcome: 'partial', confidence: 0.6, recall_count: 0 }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked[0].key).toBe('cachly:lesson:best:strong-text');
+  });
+
+  it('is stable and returns every input', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('a', 5, { outcome: 'success' }),
+      lessonMatch('b', 5, { outcome: 'success' }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked).toHaveLength(2);
+  });
+
+  it('handles empty input', () => {
+    expect(rerankByQuality([])).toEqual([]);
+  });
+});
+
+describe('Cachly-Bench regression guard', () => {
+  it('quality rerank never regresses headline metrics vs baseline', async () => {
+    const r = await runBenchmark();
+    // Cachly must be >= baseline on the headline metrics (the moat must not hurt).
+    expect(r.cachly.mrr).toBeGreaterThanOrEqual(r.baseline.mrr - 1e-9);
+    expect(r.cachly.precisionAt1).toBeGreaterThanOrEqual(r.baseline.precisionAt1 - 1e-9);
+    expect(r.cachly.ndcgAt5).toBeGreaterThanOrEqual(r.baseline.ndcgAt5 - 1e-9);
+  });
+
+  it('demonstrates a positive lift on Precision@1 and MRR (the proof)', async () => {
+    const r = await runBenchmark();
+    expect(r.lift.precisionAt1).toBeGreaterThan(0);
+    expect(r.lift.mrr).toBeGreaterThan(0);
+  });
+
+  it('baseline is already strong (corpus is not rigged to make rerank look good)', async () => {
+    const r = await runBenchmark();
+    // A fair benchmark: BM25 alone already gets most queries right.
+    expect(r.baseline.mrr).toBeGreaterThan(0.7);
+  });
+});