project-librarian 0.3.0 → 0.4.0

package/dist/mcp-server.js

@@ -11,10 +11,11 @@
 // frame on \n and parse each non-empty line as one JSON-RPC message.
 //
 // Methods implemented exactly: initialize, notifications/initialized (no-op),
-// ping, tools/list, tools/call. Unknown method -> JSON-RPC -32601. Parse error ->
-// JSON-RPC -32700 with id null. These protocol error responses are MCP/JSON-RPC
-// spec compliance, NOT fallback coding: a malformed frame or unknown method has a
-// single spec-defined reply.
+// ping, resources/list, resources/read, prompts/list, prompts/get, tools/list,
+// tools/call. Unknown method -> JSON-RPC -32601. Parse error -> JSON-RPC -32700
+// with id null. These protocol error responses are MCP/JSON-RPC spec compliance,
+// NOT fallback coding: a malformed frame or unknown method has a single
+// spec-defined reply.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -49,7 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRUST_SENTENCE = exports.TRUNCATION_NOTICE = exports.MAX_RESPONSE_CHARS = exports.SUPPORTED_PROTOCOL_VERSION = void 0;
+exports.PROMPT_TRUNCATION_NOTICE = exports.MAX_PROMPT_CHARS = exports.RESOURCE_TRUNCATION_NOTICE = exports.MAX_RESOURCE_CHARS = exports.TRUST_SENTENCE = exports.TRUNCATION_NOTICE = exports.MAX_RESPONSE_CHARS = exports.SUPPORTED_PROTOCOL_VERSION = void 0;
 exports.scaleGuidanceLines = scaleGuidanceLines;
 exports.runMcpServerMode = runMcpServerMode;
 exports.handleLine = handleLine;
@@ -66,6 +67,7 @@ exports.SUPPORTED_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSION;
 const JSONRPC_PARSE_ERROR = -32700;
 const JSONRPC_METHOD_NOT_FOUND = -32601;
 const JSONRPC_INVALID_PARAMS = -32602;
+const JSONRPC_RESOURCE_NOT_FOUND = -32002;
 // Hard cap on a single tool-result text payload. The benchmark finding is that
 // answer-shaped, bounded responses are the hypothesis under test; an unbounded
 // dump would reintroduce the tool-output cost the boundary measured. When a body
@@ -74,6 +76,14 @@ const MAX_RESPONSE_CHARS = 4000;
 exports.MAX_RESPONSE_CHARS = MAX_RESPONSE_CHARS;
 const TRUNCATION_NOTICE = "[truncated — refine the query]";
 exports.TRUNCATION_NOTICE = TRUNCATION_NOTICE;
+const MAX_RESOURCE_CHARS = 6000;
+exports.MAX_RESOURCE_CHARS = MAX_RESOURCE_CHARS;
+const RESOURCE_TRUNCATION_NOTICE = "[truncated - read the backing file directly or narrow the request]";
+exports.RESOURCE_TRUNCATION_NOTICE = RESOURCE_TRUNCATION_NOTICE;
+const MAX_PROMPT_CHARS = 6000;
+exports.MAX_PROMPT_CHARS = MAX_PROMPT_CHARS;
+const PROMPT_TRUNCATION_NOTICE = "[truncated - shorten the prompt arguments]";
+exports.PROMPT_TRUNCATION_NOTICE = PROMPT_TRUNCATION_NOTICE;
 // The trust sentence appended to every tool description (B4 analogue). It tells
 // the agent the index is authoritative for structure questions so it does not
 // re-run repo-wide greps, gated on the staleness signal that code_status reports.
@@ -96,6 +106,205 @@ function serverInfo() {
     }
 }
 // ---------------------------------------------------------------------------
+// Resources and prompts (fixed registry; no arbitrary file reads)
+// ---------------------------------------------------------------------------
+function finalizeResourceText(text) {
+    if (text.length <= MAX_RESOURCE_CHARS)
+        return text;
+    const budget = MAX_RESOURCE_CHARS - RESOURCE_TRUNCATION_NOTICE.length - 1;
+    return `${text.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${RESOURCE_TRUNCATION_NOTICE}`;
+}
+function finalizePromptText(text) {
+    if (text.length <= MAX_PROMPT_CHARS)
+        return text;
+    const budget = MAX_PROMPT_CHARS - PROMPT_TRUNCATION_NOTICE.length - 1;
+    return `${text.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${PROMPT_TRUNCATION_NOTICE}`;
+}
+function readProjectMarkdown(relativePath) {
+    const absolutePath = path.join(workspace_1.root, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+        return `Resource unavailable: ${relativePath} is missing. Run \`project-librarian\` to bootstrap or refresh the project wiki.`;
+    }
+    return finalizeResourceText(fs.readFileSync(absolutePath, "utf8"));
+}
+function codeStatusResourceText() {
+    let opened;
+    try {
+        opened = (0, code_index_1.openCodeEvidenceDatabaseForServing)();
+    }
+    catch (error) {
+        if (error instanceof code_index_1.CodeEvidenceIndexUnavailableError) {
+            return `Code status unavailable: ${error.message}`;
+        }
+        throw error;
+    }
+    try {
+        const staleness = (0, code_index_1.codeIndexStaleness)(opened.database);
+        return finalizeResourceText(statusAnswer(opened.database, opened.relativePath, staleness));
+    }
+    finally {
+        opened.database.close();
+    }
+}
+const RESOURCES = [
+    {
+        uri: "project-librarian://wiki/startup",
+        name: "wiki-startup",
+        title: "Project Wiki Startup",
+        description: "Compact session-start project context from wiki/startup.md.",
+        mimeType: "text/markdown",
+        read: () => readProjectMarkdown("wiki/startup.md"),
+    },
+    {
+        uri: "project-librarian://wiki/index",
+        name: "wiki-index",
+        title: "Project Wiki Index",
+        description: "Project wiki router from wiki/index.md.",
+        mimeType: "text/markdown",
+        read: () => readProjectMarkdown("wiki/index.md"),
+    },
+    {
+        uri: "project-librarian://code/status",
+        name: "code-status",
+        title: "Code Evidence Status",
+        description: "Current code-evidence freshness, coverage, and scale guidance.",
+        mimeType: "text/plain",
+        read: codeStatusResourceText,
+    },
+];
+const RESOURCES_BY_URI = new Map(RESOURCES.map((resource) => [resource.uri, resource]));
+function resourceDescriptor(resource) {
+    return {
+        uri: resource.uri,
+        name: resource.name,
+        title: resource.title,
+        description: resource.description,
+        mimeType: resource.mimeType,
+        annotations: { audience: ["assistant"], priority: resource.uri === "project-librarian://code/status" ? 0.7 : 0.9 },
+    };
+}
+function readResource(uri) {
+    if (typeof uri !== "string" || uri.trim() === "") {
+        throw new ToolArgumentError("missing required string argument: uri");
+    }
+    const resource = RESOURCES_BY_URI.get(uri.trim());
+    if (!resource) {
+        throw new ResourceNotFoundError(`Resource not found: ${uri}`);
+    }
+    return {
+        contents: [{
+                uri: resource.uri,
+                mimeType: resource.mimeType,
+                text: resource.read(),
+            }],
+    };
+}
+function optionalPromptArg(args, key, placeholder) {
+    const value = args[key];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : placeholder;
+}
+function requiredPromptArg(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ToolArgumentError(`missing required string argument: ${key}`);
+    }
+    return value.trim();
+}
+const PROMPTS = [
+    {
+        name: "wiki_taxonomy_update",
+        title: "Wiki Taxonomy Update",
+        description: "Classify and apply project-planning content through the wiki taxonomy before editing.",
+        arguments: [
+            { name: "content", description: "Project-planning content to classify and apply.", required: true },
+            { name: "target", description: "Optional intended wiki area or page." },
+        ],
+        get: (args) => {
+            const content = requiredPromptArg(args, "content");
+            const target = optionalPromptArg(args, "target", "choose the canonical, decision, source, or meta target from wiki/meta/document-taxonomy.md");
+            return [
+                "Use the Project Librarian wiki contract for this planning update.",
+                "1. Read project-librarian://wiki/startup and project-librarian://wiki/index first.",
+                "2. Classify the content with wiki/meta/document-taxonomy.md before editing.",
+                "3. Update the wiki in the same turn, then refresh the index and run wiki lint.",
+                `Target hint: ${target}`,
+                "Planning content:",
+                content,
+            ].join("\n");
+        },
+    },
+    {
+        name: "code_impact_trace",
+        title: "Code Impact Trace",
+        description: "Trace a path, symbol, route, or module through code evidence before planning a change.",
+        arguments: [
+            { name: "term", description: "Path, symbol, route, module, or concept to trace.", required: true },
+            { name: "question", description: "Optional user question or change intent." },
+        ],
+        get: (args) => {
+            const term = requiredPromptArg(args, "term");
+            const question = optionalPromptArg(args, "question", "identify impacted files, owners, imports, routes, and tests before editing");
+            return [
+                `Build a code impact trace for "${term}".`,
+                "1. Read project-librarian://code/status and stop to rebuild the index if it is stale.",
+                "2. Call code_context_pack first for bounded first-pass context.",
+                "3. Call code_impact only when deeper incoming/outgoing edge detail is needed.",
+                "4. Report paths, symbols, route handlers, import aliases, owners, and missing test coverage before editing.",
+                `Question: ${question}`,
+            ].join("\n");
+        },
+    },
+    {
+        name: "retrieval_quality_review",
+        title: "Retrieval Quality Review",
+        description: "Review whether wiki/code retrieval evidence is precise, complete, bounded, and stale-aware.",
+        arguments: [
+            { name: "query", description: "The retrieval query or task being evaluated.", required: true },
+            { name: "expected_evidence", description: "Optional expected files, blocks, symbols, or answer terms." },
+        ],
+        get: (args) => {
+            const query = requiredPromptArg(args, "query");
+            const expected = optionalPromptArg(args, "expected_evidence", "state the expected files, wiki blocks, symbols, answer terms, or say unknown");
+            return [
+                `Review retrieval quality for query "${query}".`,
+                "Use project-librarian://wiki/startup, project-librarian://wiki/index, and project-librarian://code/status as the first context sources.",
+                "Evaluate source hit rate, evidence precision, block integrity, graph hop usefulness, scan/output byte discipline, stale-state handling, and answer correctness.",
+                "Flag broad pages, hub expansion noise, source-snippet leakage, missing edge cases, and any unsupported quality claim.",
+                `Expected evidence: ${expected}`,
+            ].join("\n");
+        },
+    },
+];
+const PROMPTS_BY_NAME = new Map(PROMPTS.map((prompt) => [prompt.name, prompt]));
+function promptDescriptor(prompt) {
+    return {
+        name: prompt.name,
+        title: prompt.title,
+        description: prompt.description,
+        arguments: prompt.arguments,
+    };
+}
+function getPrompt(name, rawArgs) {
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new ToolArgumentError("missing required string argument: name");
+    }
+    const prompt = PROMPTS_BY_NAME.get(name.trim());
+    if (!prompt) {
+        throw new ResourceNotFoundError(`Prompt not found: ${name}`);
+    }
+    const args = rawArgs && typeof rawArgs === "object" && !Array.isArray(rawArgs) ? rawArgs : {};
+    return {
+        description: prompt.description,
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: finalizePromptText(prompt.get(args)),
+                },
+            }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Answer-shape helpers
 // ---------------------------------------------------------------------------
 function requireStringArg(args, key) {
@@ -108,6 +317,9 @@ function requireStringArg(args, key) {
 // Thrown for bad tool arguments; surfaces as a JSON-RPC -32602 invalid params.
 class ToolArgumentError extends Error {
 }
+// Thrown for unknown fixed resources/prompts; surfaces as JSON-RPC -32002.
+class ResourceNotFoundError extends Error {
+}
 // Prepend a single staleness warning line when the index is stale, then enforce
 // the hard char cap with an explicit truncation notice. The warning is counted
 // against the cap so the cap is a true ceiling on the returned text.
@@ -263,6 +475,16 @@ function statusAnswer(database, relativePath, staleness) {
     return lines.join("\n");
 }
 const TOOLS = [
+    {
+        name: "code_context_pack",
+        description: `Budgeted first-pass context for a path, symbol, route, or module term: matching files, symbols, routes, imports, edges, owners, freshness, and scale guidance without source snippets. ${TRUST_SENTENCE}`,
+        inputSchema: {
+            type: "object",
+            properties: { term: { type: "string", description: "Path, symbol, route, module, or concept to build a compact code context pack for." } },
+            required: ["term"],
+        },
+        run: (database, args) => (0, code_index_1.codeContextPack)(database, requireStringArg(args, "term")),
+    },
     {
         name: "code_impact",
         description: `Impact of a file, symbol, route, or module term across the indexed code: matching symbols/signatures, routes, imports, dependent edges, and impacted owners. ${TRUST_SENTENCE}`,
@@ -380,11 +602,49 @@ function handleRequest(request) {
         case "initialize":
             return successResponse(id, {
                 protocolVersion: negotiatedProtocolVersion(request.params),
-                capabilities: { tools: {} },
+                capabilities: { tools: {}, resources: {}, prompts: {} },
                 serverInfo: serverInfo(),
             });
         case "ping":
             return successResponse(id, {});
+        case "resources/list":
+            return successResponse(id, {
+                resources: RESOURCES.map(resourceDescriptor),
+            });
+        case "resources/read": {
+            const params = request.params && typeof request.params === "object" ? request.params : {};
+            try {
+                return successResponse(id, readResource(params.uri));
+            }
+            catch (error) {
+                if (error instanceof ToolArgumentError) {
+                    return errorResponse(id, { code: JSONRPC_INVALID_PARAMS, message: error.message });
+                }
+                if (error instanceof ResourceNotFoundError) {
+                    return errorResponse(id, { code: JSONRPC_RESOURCE_NOT_FOUND, message: error.message });
+                }
+                throw error;
+            }
+        }
+        case "prompts/list":
+            return successResponse(id, {
+                prompts: PROMPTS.map(promptDescriptor),
+            });
+        case "prompts/get": {
+            const params = request.params && typeof request.params === "object" ? request.params : {};
+            try {
+                return successResponse(id, getPrompt(params.name, params.arguments));
+            }
+            catch (error) {
+                if (error instanceof ToolArgumentError) {
+                    return errorResponse(id, { code: JSONRPC_INVALID_PARAMS, message: error.message });
+                }
+                if (error instanceof ResourceNotFoundError) {
+                    return errorResponse(id, { code: JSONRPC_RESOURCE_NOT_FOUND, message: error.message });
+                }
+                throw error;
+            }
+        }
         case "tools/list":
             return successResponse(id, {
                 tools: TOOLS.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),

package/dist/modes.js

@@ -170,35 +170,89 @@ This block is managed by \`--refresh-index\`. Move useful rows into a hand-writt
 | --- | --- | --- | --- |
 ${rows}<!-- PROJECT-WIKI-AUTO-INDEX:END -->`;
 }
+function termOccurrences(text, terms) {
+    const lowered = text.toLowerCase();
+    return terms.reduce((sum, term) => sum + (lowered.split(term).length - 1), 0);
+}
+function blockKindBoost(block) {
+    if (block.kind === "heading")
+        return 4;
+    if (block.kind === "table_row")
+        return 3;
+    if (block.kind === "list_item")
+        return 2;
+    return 1;
+}
+function scoreQueryBlock(block, terms) {
+    const occurrences = termOccurrences(`${block.headingPath.join(" ")}\n${block.text}`, terms);
+    return occurrences > 0 ? occurrences + blockKindBoost(block) : 0;
+}
 // Answer-shaped query output (2026-06-12 method-transfer decision): first line is
-// the answer, each result carries the page's TL;DR first bullet so the agent can
-// pick a page without opening it, and the whole body sits under the shared hard
-// cap with an explicit truncation notice.
+// the answer, each result carries the page's TL;DR first bullet and the strongest
+// matching block so the agent can pick a page without opening it, and the whole
+// body sits under the shared hard cap with an explicit truncation notice.
 function runQueryMode() {
     if (!args_1.queryTerm.trim()) {
         console.error("missing query: use --query \"search terms\"");
         process.exit(1);
     }
     const terms = args_1.queryTerm.toLowerCase().split(/\s+/).filter(Boolean);
-    const matches = (0, wiki_files_1.wikiMarkdownFiles)().map((file) => {
-        const text = (0, workspace_1.read)(file);
+    const pages = (0, wiki_files_1.wikiMarkdownFiles)().map((file) => ({ file, text: (0, workspace_1.read)(file) }));
+    const graph = (0, wiki_graph_1.buildWikiGraph)(pages);
+    const routerDepths = (0, wiki_graph_1.wikiRouterDepths)(graph);
+    const matches = pages.map(({ file, text }) => {
         const body = (0, workspace_1.stripMetadataHeader)(text);
         const title = (0, wiki_files_1.wikiTitleForFile)(file, text);
         const meta = (0, wiki_files_1.metadataSummary)(file, text);
-        const weighted = `${file}\n${title}\n${meta.scope}\n${(0, workspace_1.metadataValue)(text, "tags")}\n${body}`.toLowerCase();
-        const score = terms.reduce((sum, term) => sum + (weighted.split(term).length - 1) + (file.toLowerCase().includes(term) ? 3 : 0) + (title.toLowerCase().includes(term) ? 5 : 0), 0);
-        return { file, title, score, tldr: (0, wiki_files_1.firstTldrBullet)(text), ...meta };
+        const metadataScore = termOccurrences(`${file}\n${title}\n${meta.scope}\n${(0, workspace_1.metadataValue)(text, "tags")}`, terms)
+            + terms.reduce((sum, term) => sum + (file.toLowerCase().includes(term) ? 3 : 0) + (title.toLowerCase().includes(term) ? 5 : 0), 0);
+        const blocks = (0, wiki_files_1.extractMarkdownBlocks)(body)
+            .map((block) => ({ block, score: scoreQueryBlock(block, terms) }))
+            .filter((item) => item.score > 0)
+            .sort((left, right) => right.score - left.score || left.block.line - right.block.line || left.block.id.localeCompare(right.block.id));
+        const topBlock = blocks[0]?.block;
+        const blockScore = blocks.slice(0, 5).reduce((sum, item) => sum + item.score, 0);
+        const score = metadataScore + blockScore;
+        return {
+            blockKind: topBlock?.kind ?? "",
+            blockLine: topBlock?.line ?? 0,
+            blockSnippet: topBlock ? (0, wiki_files_1.markdownBlockSnippet)(topBlock) : "",
+            file,
+            graphEvidence: (0, wiki_graph_1.wikiQueryGraphEvidence)(graph, file, routerDepths),
+            title,
+            score,
+            tldr: (0, wiki_files_1.firstTldrBullet)(text),
+            ...meta,
+        };
     }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
-    const results = matches.slice(0, 10);
-    const best = results[0];
-    const lines = [best
-            ? `Project wiki query "${args_1.queryTerm}": best match ${best.file} — ${best.title} (${matches.length} matching page${matches.length === 1 ? "" : "s"}, top ${results.length} shown).`
-            : `Project wiki query "${args_1.queryTerm}": no matches.`];
-    for (const item of results) {
-        lines.push(`${item.score.toString().padStart(3)}  ${item.file}  [${item.scope}|${item.status}|${item.budget}]  ${item.title}`);
+    const resultBlocks = matches.slice(0, 10).map((item) => {
+        const lines = [`${item.score.toString().padStart(3)}  ${item.file}  [${item.scope}|${item.status}|${item.budget}]  ${item.title}`];
         if (item.tldr)
             lines.push(`     tldr: ${item.tldr}`);
+        if (item.blockSnippet)
+            lines.push(`     match: ${item.blockKind}@L${item.blockLine}: ${item.blockSnippet}`);
+        if (item.graphEvidence)
+            lines.push(`     graph: ${item.graphEvidence}`);
+        return lines;
+    });
+    const selectedBlocks = [];
+    const answerBudget = wiki_graph_1.wikiAnswerCharCap - wiki_graph_1.wikiAnswerTruncationNotice.length - 1;
+    const headlineFor = (shown) => matches[0]
+        ? `Project wiki query "${args_1.queryTerm}": best match ${matches[0].file} — ${matches[0].title} (${matches.length} matching page${matches.length === 1 ? "" : "s"}, top ${shown} shown).`
+        : `Project wiki query "${args_1.queryTerm}": no matches.`;
+    for (const block of resultBlocks) {
+        const candidateBlocks = [...selectedBlocks, block];
+        const candidate = [headlineFor(candidateBlocks.length), ...candidateBlocks.flat()].join("\n");
+        if (candidate.length > answerBudget && selectedBlocks.length > 0)
+            break;
+        selectedBlocks.push(block);
     }
+    const best = matches[0];
+    const lines = [best
+            ? headlineFor(selectedBlocks.length)
+            : `Project wiki query "${args_1.queryTerm}": no matches.`];
+    for (const block of selectedBlocks)
+        lines.push(...block);
     console.log((0, wiki_graph_1.finalizeWikiAnswer)(lines.join("\n")));
 }
 // Wiki impact mode: backlink/decision_ref/routing evidence for a page so wiki

package/dist/retrieval-eval.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRetrievalMetrics = computeRetrievalMetrics;
+function bytesOf(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function finiteNonNegativeInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return fallback;
+    return Math.floor(value);
+}
+function itemKeys(item) {
+    return new Set([item.id, item.sourceId ?? "", item.blockId ?? ""].filter(Boolean));
+}
+function itemMatches(item, expectedId) {
+    return itemKeys(item).has(expectedId);
+}
+function ratio(numerator, denominator, emptyValue) {
+    if (denominator === 0)
+        return emptyValue;
+    return numerator / denominator;
+}
+function uniqueNonEmptyStrings(values) {
+    return [...new Set((values ?? []).filter((value) => value.length > 0))];
+}
+function answerCorrect(outputText, terms) {
+    const requiredTerms = uniqueNonEmptyStrings(terms);
+    if (requiredTerms.length === 0)
+        return null;
+    const lowered = outputText.toLowerCase();
+    return requiredTerms.every((term) => lowered.includes(term.toLowerCase()));
+}
+function computeRetrievalMetrics(results, expectation, options = {}) {
+    const topK = finiteNonNegativeInteger(options.topK, results.length);
+    const considered = results.slice(0, topK);
+    const requiredSourceIds = uniqueNonEmptyStrings(expectation.requiredSourceIds);
+    const relevantSourceIds = expectation.relevantSourceIds === undefined
+        ? requiredSourceIds
+        : uniqueNonEmptyStrings(expectation.relevantSourceIds);
+    const requiredHits = requiredSourceIds.filter((sourceId) => considered.some((item) => itemMatches(item, sourceId))).length;
+    const relevantHits = relevantSourceIds.length === 0
+        ? 0
+        : considered.filter((item) => relevantSourceIds.some((sourceId) => itemMatches(item, sourceId))).length;
+    const intactBlocks = considered.filter((item) => item.blockIntact !== false).length;
+    const maxHop = considered.reduce((currentMax, item) => Math.max(currentMax, finiteNonNegativeInteger(item.hop, 0)), 0);
+    const outputText = options.outputText ?? considered.map((item) => item.text ?? "").join("\n");
+    const computedScanBytes = considered.reduce((sum, item) => {
+        if (item.bytes !== undefined && Number.isFinite(item.bytes) && item.bytes >= 0)
+            return sum + Math.floor(item.bytes);
+        return sum + bytesOf(item.text ?? "");
+    }, 0);
+    const scanBytes = options.scanBytes === undefined
+        ? computedScanBytes
+        : finiteNonNegativeInteger(options.scanBytes, 0);
+    return {
+        answer_correct: answerCorrect(outputText, expectation.requiredAnswerTerms),
+        block_integrity: ratio(intactBlocks, considered.length, 1),
+        considered_results: considered.length,
+        evidence_precision: ratio(relevantHits, considered.length, 0),
+        max_hop_count: maxHop,
+        output_bytes: bytesOf(outputText),
+        required_source_count: requiredSourceIds.length,
+        required_source_hits: requiredHits,
+        scan_bytes: scanBytes,
+        source_hit_rate: ratio(requiredHits, requiredSourceIds.length, 1),
+        top_k: topK,
+    };
+}

package/dist/wiki-concepts.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conceptIdForFile = conceptIdForFile;
+exports.wikiConceptType = wikiConceptType;
+exports.conceptFromPage = conceptFromPage;
+exports.readWikiConcepts = readWikiConcepts;
+const wiki_files_1 = require("./wiki-files");
+const workspace_1 = require("./workspace");
+function conceptIdForFile(file) {
+    return file.replace(/^wiki\//, "").replace(/\.(md|mdx)$/i, "");
+}
+function wikiConceptType(file, scope) {
+    if (scope === "startup-router" || file === "wiki/startup.md")
+        return "Startup Router";
+    if (scope === "wiki-router" || file === "wiki/index.md" || /^wiki\/indexes\//.test(file))
+        return "Wiki Router";
+    if (scope === "project-canonical" || /^wiki\/canonical\//.test(file))
+        return "Project Canonical Concept";
+    if (scope === "project-decisions" || /^wiki\/decisions\//.test(file))
+        return "Project Decision";
+    if (scope === "source-summary" || /^wiki\/sources\//.test(file))
+        return "Source Summary";
+    if (scope === "wiki-meta" || /^wiki\/meta\//.test(file))
+        return "Wiki Operations Concept";
+    if (/^migration-/.test(scope) || /^wiki\/migration\//.test(file))
+        return "Migration Ledger";
+    if (scope === "inbox" || /^wiki\/inbox\//.test(file))
+        return "Project Candidate";
+    return "Wiki Concept";
+}
+function conceptFromPage(file, text) {
+    const scope = (0, workspace_1.metadataValue)(text, "scope") || "-";
+    const tldr = (0, wiki_files_1.firstTldrBullet)(text);
+    return {
+        budget: (0, workspace_1.metadataValue)(text, "read_budget") || "-",
+        conceptId: conceptIdForFile(file),
+        description: tldr || (0, wiki_files_1.compactSummary)(text),
+        file,
+        reviewTrigger: (0, workspace_1.metadataValue)(text, "review_trigger"),
+        scope,
+        status: (0, workspace_1.metadataValue)(text, "status") || "-",
+        timestamp: (0, workspace_1.metadataValue)(text, "updated"),
+        title: (0, wiki_files_1.wikiTitleForFile)(file, text),
+        type: wikiConceptType(file, scope),
+    };
+}
+function readWikiConcepts(files = (0, wiki_files_1.wikiMarkdownFiles)()) {
+    return files.map((file) => conceptFromPage(file, (0, workspace_1.read)(file)));
+}

package/dist/wiki-files.js

@@ -37,6 +37,8 @@ exports.ignoredDirs = exports.standardWikiFiles = void 0;
 exports.walkMarkdownFiles = walkMarkdownFiles;
 exports.firstHeading = firstHeading;
 exports.compactSummary = compactSummary;
+exports.markdownBlockSnippet = markdownBlockSnippet;
+exports.extractMarkdownBlocks = extractMarkdownBlocks;
 exports.splitMarkdownRow = splitMarkdownRow;
 exports.parseMarkdownTableRows = parseMarkdownTableRows;
 exports.wikiMarkdownFiles = wikiMarkdownFiles;
@@ -134,6 +136,109 @@ function compactSummary(text) {
         .trim()
         .slice(0, 180);
 }
+function slugForBlockId(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "block";
+}
+function isMarkdownHeading(line) {
+    return line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+}
+function isMarkdownTableSeparator(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.replace(/\s/g, "")));
+}
+function normalizeBlockText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function blockId(kind, line, text) {
+    return `${kind}:${line}:${slugForBlockId(text)}`;
+}
+function markdownBlockSnippet(block, maxLength = 180) {
+    const prefix = block.headingPath.length > 0 && block.kind !== "heading" ? `${block.headingPath.join(" > ")}: ` : "";
+    return `${prefix}${normalizeBlockText(block.text)}`.slice(0, maxLength);
+}
+function extractMarkdownBlocks(text) {
+    const body = (0, workspace_1.stripMetadataHeader)(text);
+    const lines = body.split(/\r?\n/);
+    const blocks = [];
+    const headingPath = [];
+    let paragraph = null;
+    let fence = null;
+    function addBlock(kind, line, blockText) {
+        const normalized = normalizeBlockText(blockText);
+        if (!normalized)
+            return;
+        blocks.push({
+            headingPath: [...headingPath],
+            id: blockId(kind, line, normalized),
+            kind,
+            line,
+            text: normalized,
+        });
+    }
+    function flushParagraph() {
+        if (!paragraph)
+            return;
+        addBlock("paragraph", paragraph.line, paragraph.lines.join(" "));
+        paragraph = null;
+    }
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        const trimmed = line.trim();
+        const fenceMatch = trimmed.match(/^(```+|~~~+)\s*(.*)$/);
+        if (fence) {
+            const closingFence = fenceMatch?.[1] ?? "";
+            if (closingFence.startsWith(fence.fence.slice(0, 3)) && closingFence.length >= fence.fence.length) {
+                const sample = fence.lines.map((item) => item.trim()).filter(Boolean).slice(0, 3).join(" ");
+                addBlock("code_fence", fence.line, `code fence${fence.lang ? ` ${fence.lang}` : ""}: ${sample}`);
+                fence = null;
+            }
+            else {
+                fence.lines.push(line);
+            }
+            return;
+        }
+        if (fenceMatch) {
+            flushParagraph();
+            fence = { fence: fenceMatch[1] ?? "```", lang: (fenceMatch[2] ?? "").trim(), line: lineNumber, lines: [] };
+            return;
+        }
+        if (!trimmed) {
+            flushParagraph();
+            return;
+        }
+        const heading = isMarkdownHeading(line);
+        if (heading?.[1] && heading[2]) {
+            flushParagraph();
+            const level = heading[1].length;
+            const title = heading[2].trim();
+            headingPath.splice(level - 1);
+            headingPath[level - 1] = title;
+            addBlock("heading", lineNumber, title);
+            return;
+        }
+        if (/^\s{0,3}([-*+]|\d+\.)\s+\S/.test(line)) {
+            flushParagraph();
+            addBlock("list_item", lineNumber, trimmed);
+            return;
+        }
+        if (/^\|.+\|$/.test(trimmed)) {
+            flushParagraph();
+            const cells = splitMarkdownRow(line);
+            if (!isMarkdownTableSeparator(cells))
+                addBlock("table_row", lineNumber, cells.join(" | "));
+            return;
+        }
+        if (!paragraph)
+            paragraph = { line: lineNumber, lines: [] };
+        paragraph.lines.push(trimmed);
+    });
+    const unclosedFence = fence;
+    if (unclosedFence) {
+        const sample = unclosedFence.lines.map((item) => item.trim()).filter(Boolean).slice(0, 3).join(" ");
+        addBlock("code_fence", unclosedFence.line, `code fence${unclosedFence.lang ? ` ${unclosedFence.lang}` : ""}: ${sample}`);
+    }
+    flushParagraph();
+    return blocks;
+}
 function splitMarkdownRow(line) {
     const trimmed = line.trim();
     const row = trimmed.replace(/^\|/, "").replace(/\|$/, "");