project-librarian 0.2.1 → 0.4.0

package/dist/modes.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRefreshIndexBlock = buildRefreshIndexBlock;
 exports.runQueryMode = runQueryMode;
+exports.runWikiImpactMode = runWikiImpactMode;
 exports.projectCandidatesContent = projectCandidatesContent;
 exports.appendCaptureInbox = appendCaptureInbox;
 exports.runIssueDraftMode = runIssueDraftMode;
@@ -49,6 +50,7 @@ exports.runQualityCheckMode = runQualityCheckMode;
 exports.runMigrationQualityCheckMode = runMigrationQualityCheckMode;
 exports.runMigrationLintMode = runMigrationLintMode;
 exports.runMigrationDoctorMode = runMigrationDoctorMode;
+exports.collectRouterTruthDiagnostics = collectRouterTruthDiagnostics;
 exports.runDoctorMode = runDoctorMode;
 exports.runLintMode = runLintMode;
 const fs = __importStar(require("node:fs"));
@@ -60,6 +62,7 @@ const workspace_1 = require("./workspace");
 const templates_1 = require("./templates");
 const migration_1 = require("./migration");
 const wiki_files_1 = require("./wiki-files");
+const wiki_graph_1 = require("./wiki-graph");
 const scopedAutoIndexThreshold = 40;
 const scopedAutoIndexMarker = "<!-- PROJECT-WIKI-SCOPED-AUTO-INDEX -->";
 function isScopedAutoIndex(file) {
@@ -167,26 +170,100 @@ 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 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 results = (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, ...meta };
-    }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, 10);
-    console.log(`Project wiki query: ${args_1.queryTerm}`);
-    if (results.length === 0)
-        console.log("no matches");
-    for (const item of results)
-        console.log(`${item.score.toString().padStart(3)}  ${item.file}  ${item.scope}  ${item.status}  ${item.title}`);
+        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 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
+// maintenance can find review candidates when project truth changes.
+function runWikiImpactMode() {
+    if (!args_1.wikiImpactTarget.trim()) {
+        console.error("missing wiki impact target: use --wiki-impact \"page-or-term\"");
+        process.exit(1);
+    }
+    const pages = (0, wiki_files_1.wikiMarkdownFiles)().map((file) => ({ file, text: (0, workspace_1.read)(file) }));
+    console.log((0, wiki_graph_1.wikiImpactAnswer)(pages, args_1.wikiImpactTarget.trim()));
 }
 function projectCandidatesContent() {
     return `${(0, templates_1.metadata)("inbox", "on-demand", "wiki/meta/wiki-ops-v1-decisions.md", "candidates are adopted, rejected, or stale")}
@@ -456,15 +533,12 @@ function printDiagnostics(title, diagnostics, checked) {
     console.log(`passed: ${checked} wiki markdown files checked, ${warnings} warnings`);
     return true;
 }
-function collectWikiLinkReferences(files) {
-    return files.flatMap((file) => (0, wiki_files_1.extractWikiLinks)(file, (0, workspace_1.read)(file)));
-}
 function collectLinkDiagnostics() {
     const diagnostics = [];
     const files = (0, wiki_files_1.wikiMarkdownFiles)();
     const fileSet = new Set(files);
-    const links = collectWikiLinkReferences(files);
-    for (const link of links) {
+    const graph = (0, wiki_graph_1.buildWikiGraph)(files.map((file) => ({ file, text: (0, workspace_1.read)(file) })));
+    for (const link of graph.links) {
         if (!fileSet.has(link.normalizedTarget)) {
             diagnostics.push({
                 code: "broken-link",
@@ -474,25 +548,29 @@ function collectLinkDiagnostics() {
             });
         }
     }
-    if ((0, workspace_1.exists)("wiki/index.md")) {
-        const indexLinks = (0, wiki_files_1.extractWikiLinks)("wiki/index.md", (0, workspace_1.read)("wiki/index.md"));
-        const indexTargets = new Map();
-        for (const link of indexLinks)
-            indexTargets.set(link.normalizedTarget, (indexTargets.get(link.normalizedTarget) ?? 0) + 1);
-        for (const [target, count] of indexTargets) {
-            if (count > 1) {
-                diagnostics.push({
-                    code: "duplicate-route",
-                    severity: "warn",
-                    file: "wiki/index.md",
-                    message: `${count} index routes resolve to ${target}`,
-                });
-            }
+    const indexTargets = new Map();
+    for (const link of graph.outgoingLinks.get("wiki/index.md") ?? []) {
+        indexTargets.set(link.normalizedTarget, (indexTargets.get(link.normalizedTarget) ?? 0) + 1);
+    }
+    for (const [target, count] of indexTargets) {
+        if (count > 1) {
+            diagnostics.push({
+                code: "duplicate-route",
+                severity: "warn",
+                file: "wiki/index.md",
+                message: `${count} index routes resolve to ${target}`,
+            });
         }
     }
+    // Self-links are not connectivity: a page whose only incoming link is its own
+    // self-loop has no route into it and must stay an orphan-page finding, keeping
+    // the orphan and router-unreachable rules disjoint.
     const incoming = new Map();
-    for (const link of links)
+    for (const link of graph.links) {
+        if (link.file === link.normalizedTarget)
+            continue;
         incoming.set(link.normalizedTarget, (incoming.get(link.normalizedTarget) ?? 0) + 1);
+    }
     const orphanExemptions = new Set(["wiki/index.md", "wiki/startup.md", "wiki/README.md"]);
     for (const file of files) {
         if (orphanExemptions.has(file))
@@ -506,6 +584,50 @@ function collectLinkDiagnostics() {
             });
         }
     }
+    // Bounded router reachability, promoted from the benchmark fixture A1 hard
+    // assert (benchmarks/lib/llm-fixtures.js assertBoundedAnswerReachability) to the
+    // real wiki: fixture wikis were guaranteed navigable from startup while real
+    // wikis were never checked for the same property. Pages with zero incoming
+    // links are already the orphan-page rule's finding, so reachability reports
+    // only the cases orphan cannot see: linked-but-disconnected islands, an index
+    // the startup router never links (hop 1), and routes deeper than the budget.
+    // When wiki/startup.md itself is missing, lint owns that as a required-file
+    // error and reachability has no root to check from.
+    if (fileSet.has(wiki_graph_1.wikiRouterRoot)) {
+        const depths = (0, wiki_graph_1.wikiRouterDepths)(graph);
+        for (const file of files) {
+            if (wiki_graph_1.wikiRouterExemptPages.has(file))
+                continue;
+            const depth = depths.get(file);
+            const isIndex = file === "wiki/index.md";
+            if (depth === undefined) {
+                if (isIndex) {
+                    diagnostics.push({
+                        code: "router-unreachable",
+                        severity: "warn",
+                        file,
+                        message: `${wiki_graph_1.wikiRouterRoot} does not link [[index]], so the router chain never starts (hop 1 broken)`,
+                    });
+                }
+                else if ((incoming.get(file) ?? 0) > 0) {
+                    diagnostics.push({
+                        code: "router-unreachable",
+                        severity: "warn",
+                        file,
+                        message: `linked only from pages that never connect to ${wiki_graph_1.wikiRouterRoot}; route it from wiki/index.md or a scoped router`,
+                    });
+                }
+            }
+            else if (depth > wiki_graph_1.wikiRouterDepthBudget) {
+                diagnostics.push({
+                    code: "router-depth-exceeded",
+                    severity: "warn",
+                    file,
+                    message: `reachable from ${wiki_graph_1.wikiRouterRoot} only at depth ${depth} (budget ${wiki_graph_1.wikiRouterDepthBudget}); add a shorter route`,
+                });
+            }
+        }
+    }
     return diagnostics.sort((a, b) => a.severity.localeCompare(b.severity) || a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
 }
 function legacyWikiRoots() {
@@ -585,15 +707,19 @@ function collectMigrationQualityDiagnostics() {
 function collectMigrationLintDiagnostics() {
     if (legacyWikiRoots().length === 0)
         return [];
-    const requiredFiles = [
+    const requiredCoreFiles = [
+        "wiki/meta/document-taxonomy.md",
         "wiki/migration/inventory.md",
+        "wiki/migration/unit-map.md",
+        "wiki/migration/split-plan.md",
         "wiki/migration/coverage.md",
         "wiki/migration/plan.md",
+        "wiki/migration/review.md",
         "wiki/migration/verification.md",
-        "wiki/canonical/migration-inbox.md",
-        "wiki/decisions/migration-inbox.md",
-        "wiki/sources/migration-inbox.md",
+        "wiki/migration/bulk-review.md",
     ];
+    const requiredInboxFiles = (0, migration_1.migrationSemanticReviewComplete)() ? [] : [...migration_1.generatedMigrationInboxFiles];
+    const requiredFiles = [...requiredCoreFiles, ...requiredInboxFiles];
     const diagnostics = requiredFiles
         .filter((file) => !(0, workspace_1.exists)(file))
         .map((file) => ({
@@ -603,6 +729,8 @@ function collectMigrationLintDiagnostics() {
         message: "migration review files are missing; run --migrate or keep migration diagnostics out of normal doctor",
     }));
     diagnostics.push(...(0, migration_1.collectMigrationCoverageDiagnostics)());
+    diagnostics.push(...(0, migration_1.collectMigrationUnitMapDiagnostics)());
+    diagnostics.push(...(0, migration_1.collectMigrationSplitPlanDiagnostics)());
     return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message));
 }
 function runLinkCheckMode() {
@@ -631,6 +759,73 @@ function runMigrationDoctorMode() {
     if (!lintOk || !qualityOk)
         process.exit(1);
 }
+// B2 router-truth contradiction rule. A compact router that contradicts the
+// decision log is worse than none: the measured 2026-06-10 run spiraled into
+// post-answer verification because wiki/startup.md Recent Decisions and
+// wiki/decisions/recent.md said "None yet." while wiki/decisions/log.md held the
+// dated answer. This flags that exact contradiction as an error-level diagnostic.
+// "None yet." is the bootstrap template marker for an empty decision surface
+// (startup template "## Recent Project Decisions" and recent.md template
+// "## Decisions" both seed "- None yet."), so its presence while the log carries a
+// dated entry is the template-equivalent of an unmaintained router.
+//
+// SECTION-ANCHORED SCAN: the rule checks the relevant section body only, not the
+// whole file, to avoid false-positives on other sections (e.g. an open-questions
+// list that legitimately says "None yet." while Recent Decisions is maintained).
+//   wiki/startup.md   → "## Recent Project Decisions" section body
+//   decisions/recent.md → "## Decisions" section body
+//
+// MINOR 2: the marker regex is tolerant of trailing whitespace / omitted terminal
+// period ("None yet", "None yet. ") but stays anchored to the section scope above.
+// Coupling: this English-only marker matches the bootstrap template text only;
+// a project using a different language for these sections will not be checked.
+const ROUTER_TRUTH_NONE_YET_REGEX = /\bNone yet\.?\s*$/m;
+// Extract the body of a named heading section (from the heading line to the next
+// same-or-higher-level heading, or end of string). Returns empty string when the
+// heading is absent so the caller can decide whether to flag or skip.
+function extractSectionBody(markdown, headingText) {
+    // Match `## <headingText>` (level-2 only, matching the template structure).
+    const headingRe = new RegExp(`^##\\s+${headingText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
+    const match = headingRe.exec(markdown);
+    if (!match)
+        return "";
+    const afterHeading = markdown.slice(match.index + match[0].length);
+    // Stop at the next ## heading (same or higher level), or end of string.
+    const nextHeading = /^##\s/m.exec(afterHeading);
+    return nextHeading ? afterHeading.slice(0, nextHeading.index) : afterHeading;
+}
+function collectRouterTruthDiagnostics() {
+    const logPath = "wiki/decisions/log.md";
+    if (!(0, workspace_1.exists)(logPath))
+        return [];
+    const logHasDatedEntry = /\b\d{4}-\d{2}-\d{2}\b/.test((0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(logPath)));
+    if (!logHasDatedEntry)
+        return [];
+    const diagnostics = [];
+    // Each tuple: [file, headingText, surfaceLabel]
+    // headingText must match the bootstrap template section heading exactly so the
+    // section-anchored scan never accidentally reads unrelated sections.
+    const routers = [
+        ["wiki/startup.md", "Recent Project Decisions", "Recent Decisions"],
+        ["wiki/decisions/recent.md", "Decisions", "Decisions"],
+    ];
+    for (const [file, heading, surface] of routers) {
+        if (!(0, workspace_1.exists)(file))
+            continue;
+        const section = extractSectionBody((0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(file)), heading);
+        if (section === "")
+            continue; // section absent — skip rather than false-positive
+        if (ROUTER_TRUTH_NONE_YET_REGEX.test(section)) {
+            diagnostics.push({
+                code: "router-truth-contradiction",
+                severity: "error",
+                file,
+                message: `${file} ${surface} still says "None yet." while ${logPath} holds a dated decision entry; update ${file} to reflect the recorded decision`,
+            });
+        }
+    }
+    return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
+}
 function runDoctorMode(fix) {
     if (fix) {
         console.log("Project wiki doctor --fix");
@@ -645,40 +840,45 @@ function runDoctorMode(fix) {
     const files = (0, wiki_files_1.wikiMarkdownFiles)();
     const linkOk = printDiagnostics("Project wiki link-check", collectLinkDiagnostics(), files.length);
     const qualityOk = printDiagnostics("Project wiki quality-check", collectQualityDiagnostics(), files.length);
+    const routerTruthOk = printDiagnostics("Project wiki router-truth check", collectRouterTruthDiagnostics(), files.length);
     runLintMode();
-    if (!linkOk || !qualityOk)
+    if (!linkOk || !qualityOk || !routerTruthOk)
         process.exit(1);
 }
+const commonLintRequiredFiles = [
+    "AGENTS.md",
+    "wiki/AGENTS.md",
+    "wiki/startup.md",
+    "wiki/index.md",
+    "wiki/decisions/log.md",
+    "wiki/decisions/recent.md",
+    "wiki/meta/operating-model.md",
+    "wiki/meta/decision-policy.md",
+    "wiki/meta/wiki-ops-v1-decisions.md",
+    ".githooks/prepare-commit-msg",
+    ".githooks/wiki-commit-trailers.js",
+];
+const agentLintRequiredFiles = {
+    codex: [".codex/hooks/wiki-session-start.js", ".codex/hooks.json"],
+    claude: ["CLAUDE.md", ".claude/hooks/wiki-session-start.js", ".claude/settings.json"],
+    cursor: [".cursor/rules/project-librarian.mdc", ".cursor/hooks/wiki-session-start.js", ".cursor/hooks.json"],
+    gemini: ["GEMINI.md", ".gemini/hooks/wiki-session-start.js", ".gemini/settings.json"],
+};
+function activeLintAgentSurfaces() {
+    const active = new Set();
+    for (const [agent, files] of Object.entries(agentLintRequiredFiles)) {
+        if (files.some((file) => (0, workspace_1.exists)(file)))
+            active.add(agent);
+    }
+    return active;
+}
 function runLintMode() {
     const errors = [];
     const warnings = [];
+    const activeAgents = activeLintAgentSurfaces();
     const requiredFiles = [
-        "AGENTS.md",
-        "CLAUDE.md",
-        "GEMINI.md",
-        "wiki/AGENTS.md",
-        "wiki/startup.md",
-        "wiki/index.md",
-        "wiki/canonical/project-brief.md",
-        "wiki/canonical/open-questions.md",
-        "wiki/canonical/assumptions.md",
-        "wiki/canonical/risks.md",
-        "wiki/decisions/log.md",
-        "wiki/decisions/recent.md",
-        "wiki/meta/operating-model.md",
-        "wiki/meta/decision-policy.md",
-        "wiki/meta/wiki-ops-v1-decisions.md",
-        ".githooks/prepare-commit-msg",
-        ".githooks/wiki-commit-trailers.js",
-        ".codex/hooks/wiki-session-start.js",
-        ".codex/hooks.json",
-        ".claude/hooks/wiki-session-start.js",
-        ".claude/settings.json",
-        ".cursor/rules/project-librarian.mdc",
-        ".cursor/hooks/wiki-session-start.js",
-        ".cursor/hooks.json",
-        ".gemini/hooks/wiki-session-start.js",
-        ".gemini/settings.json",
+        ...commonLintRequiredFiles,
+        ...Array.from(activeAgents).flatMap((agent) => agentLintRequiredFiles[agent]),
     ];
     for (const file of requiredFiles) {
         if (!(0, workspace_1.exists)(file))

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,
+    };
+}