syncstaff-mcp 0.2.3

package/dist/lib/index/checker-resolver.js

@@ -0,0 +1,257 @@
+/**
+ * Call resolution through the TypeScript type checker.
+ *
+ * WHY THIS EXISTS, given ADR 002 chose a syntactic parser on purpose.
+ *
+ * The syntactic pass refuses any member call whose receiver type it does not
+ * track. That refusal is what keeps it from inventing edges, and it is why its
+ * precision has held at 1.00 against the compiler. The cost of that refusal
+ * was never measured until now, and it is much larger than assumed:
+ *
+ *   keel (plain functions)   470 edges found, checker finds 695   — 64% recall
+ *   zod  (fluent API)        722 edges found, checker finds 3178  — 14% recall
+ *
+ * `z.string()` is 2,591 calls in zod that the syntactic pass cannot see, and
+ * measuring the cheap escape hatch — receivers imported from inside the same
+ * repo — put it at 0-7% across five repositories. There is no middle path
+ * between a parser and a checker; the receiver types genuinely have to be
+ * inferred.
+ *
+ * WHAT THIS IS NOT. It does not replace the syntactic backend. It is slower by
+ * 6-7x (4.1s on keel, 11.2s on zod, against 0.7s and 1.6s), it needs a
+ * tsconfig, and it wants node_modules present to resolve external types. The
+ * syntactic pass still answers when those are missing, which is the ordinary
+ * case in a fresh checkout. Callers choose, and the result says which backend
+ * produced it so nobody has to guess.
+ *
+ * PRIVACY. Same rule as everything else here: the program is constructed from
+ * files on this disk, the checker runs in this process, and nothing leaves it
+ * (inv_01KZWPAM9QCZ0DD7789N55X647). A type checker reads more of the code than
+ * a parser does; it still reads it locally.
+ *
+ * ATTRIBUTION. The checker follows aliases to the original declaration, so a
+ * call reaching a symbol through a re-export is attributed to the file that
+ * declares it rather than the barrel it was imported from. The syntactic pass
+ * reports the barrel. Both are defensible; the checker's answer is the more
+ * useful one for "which file must I edit", and the difference accounts for
+ * most of what looked like disagreement between the two backends.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { byCodeUnit } from "./order.js";
+const posix = (p) => p.split("\\").join("/");
+/**
+ * Find the tsconfig that actually lists source files.
+ *
+ * Solution-style configs — a root tsconfig whose only job is `references` —
+ * produce a program with zero files, and a zero-file program reports zero
+ * edges rather than an error. That silence is indistinguishable from "this
+ * repo has no calls", which is how a broken measurement passes for a finding:
+ * probing hono this way returned 0 edges from 0 call expressions and it looked
+ * like a result until the file count gave it away.
+ */
+export function findProjectConfigs(ts, root) {
+    const seen = new Set();
+    const withFiles = [];
+    const visit = (configPath, depth) => {
+        if (depth > 3 || seen.has(configPath) || !existsSync(configPath))
+            return;
+        seen.add(configPath);
+        const raw = ts.readConfigFile(configPath, (p) => {
+            try {
+                return readFileSync(p, "utf8");
+            }
+            catch {
+                return undefined;
+            }
+        });
+        const parsed = ts.parseJsonConfigFileContent(raw.config ?? {}, ts.sys, dirname(configPath));
+        if (parsed.fileNames.length > 0)
+            withFiles.push(configPath);
+        for (const ref of parsed.projectReferences ?? []) {
+            const target = ref.path.endsWith(".json") ? ref.path : join(ref.path, "tsconfig.json");
+            visit(resolve(dirname(configPath), target), depth + 1);
+        }
+    };
+    const NAMES = ["tsconfig.json", "tsconfig.base.json", "tsconfig.build.json"];
+    for (const candidate of NAMES)
+        visit(join(root, candidate), 0);
+    // Monorepos keep the tsconfig one level down. `repoRoot()` returns the git
+    // root, so asking about a symbol in keel/ resolved to /home/.../sync, which
+    // has no tsconfig — findProjectConfigs returned nothing, the checker backend
+    // reported "cannot run here", and the hook fell back to the parser while
+    // still claiming it had been asked for the checker. A silent downgrade is
+    // the worst of the three outcomes.
+    if (withFiles.length === 0) {
+        let children = [];
+        try {
+            children = readdirSync(root);
+        }
+        catch {
+            children = [];
+        }
+        for (const child of children.sort()) {
+            if (child.startsWith(".") || child === "node_modules")
+                continue;
+            let isDir = false;
+            try {
+                isDir = statSync(join(root, child)).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (!isDir)
+                continue;
+            for (const candidate of NAMES)
+                visit(join(root, child, candidate), 0);
+        }
+    }
+    return withFiles;
+}
+/** The nearest enclosing named function/method, for a checkable reason string. */
+function enclosingName(ts, node) {
+    for (let n = node.parent; n; n = n.parent) {
+        if (ts.isFunctionDeclaration(n) || ts.isMethodDeclaration(n))
+            return n.name?.getText();
+        if (ts.isVariableDeclaration(n) && n.initializer && (ts.isArrowFunction(n.initializer) || ts.isFunctionExpression(n.initializer))) {
+            return n.name.getText();
+        }
+        if (ts.isPropertyAssignment(n) && n.initializer && (ts.isArrowFunction(n.initializer) || ts.isFunctionExpression(n.initializer))) {
+            return n.name.getText();
+        }
+    }
+    return undefined;
+}
+/**
+ * Every repo-internal call edge the checker can see.
+ *
+ * Edges to declarations outside the repository are counted, not returned:
+ * `console.log` and third-party APIs are real calls but not edges anyone can
+ * act on, and reporting them as impact is the miscalibration that made the
+ * `Date.now` caveat so expensive.
+ */
+export function buildCheckerCallGraph(ts, root, configPaths) {
+    const started = Date.now();
+    const configs = configPaths ?? findProjectConfigs(ts, root);
+    const fileNames = new Set();
+    let options = {};
+    for (const configPath of configs) {
+        const raw = ts.readConfigFile(configPath, (p) => {
+            try {
+                return readFileSync(p, "utf8");
+            }
+            catch {
+                return undefined;
+            }
+        });
+        const parsed = ts.parseJsonConfigFileContent(raw.config ?? {}, ts.sys, dirname(configPath));
+        for (const f of parsed.fileNames)
+            fileNames.add(f);
+        options = { ...parsed.options, ...options };
+    }
+    const program = ts.createProgram([...fileNames], {
+        ...options,
+        // Nothing is emitted and lib.d.ts is trusted: this is a resolution query,
+        // not a build, and a repo that does not currently compile must still be
+        // answerable.
+        noEmit: true,
+        skipLibCheck: true,
+    });
+    const checker = program.getTypeChecker();
+    const edges = [];
+    const files = [];
+    let considered = 0;
+    let external = 0;
+    let unresolved = 0;
+    const inRepo = (abs) => {
+        const rel = posix(relative(root, abs));
+        return rel && !rel.startsWith("..") && !rel.includes("node_modules") ? rel : null;
+    };
+    for (const sf of program.getSourceFiles()) {
+        if (sf.isDeclarationFile)
+            continue;
+        const from = inRepo(sf.fileName);
+        if (!from)
+            continue;
+        files.push(from);
+        const visit = (node) => {
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                considered += 1;
+                const member = ts.isPropertyAccessExpression(node.expression);
+                const target = member ? node.expression.name : node.expression;
+                let symbol = checker.getSymbolAtLocation(target);
+                if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+                    // Follow re-exports to the declaring file. A caller asking what to
+                    // edit wants where the function lives, not which barrel it came in
+                    // through.
+                    try {
+                        symbol = checker.getAliasedSymbol(symbol);
+                    }
+                    catch {
+                        /* keep the alias */
+                    }
+                }
+                const declarations = symbol?.declarations ?? [];
+                if (declarations.length === 0)
+                    unresolved += 1;
+                let landedInRepo = false;
+                for (const d of declarations) {
+                    const to = inRepo(d.getSourceFile().fileName);
+                    if (!to || to === from)
+                        continue;
+                    landedInRepo = true;
+                    edges.push({
+                        from,
+                        to,
+                        symbol: symbol.getName(),
+                        line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+                        enclosing: enclosingName(ts, node),
+                        member,
+                    });
+                }
+                if (declarations.length > 0 && !landedInRepo)
+                    external += 1;
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    // byCodeUnit, not localeCompare: collation is locale-dependent, and an
+    // index that sorts differently on another machine stops being comparable
+    // to itself. order.ts carries the incident that established this.
+    edges.sort((a, b) => byCodeUnit(a.from, b.from) || a.line - b.line || byCodeUnit(a.symbol, b.symbol));
+    return {
+        edges,
+        files: files.sort(byCodeUnit),
+        considered,
+        external,
+        unresolved,
+        backend: "typescript-checker",
+        ms: Date.now() - started,
+    };
+}
+/**
+ * Load the checker backend, or null when it cannot run here.
+ *
+ * Null is a normal answer, not a failure: a checkout without node_modules, or
+ * without a tsconfig that lists files, cannot be type-checked, and the
+ * syntactic backend exists for exactly that case.
+ */
+export async function loadCheckerProgram(root) {
+    let ts;
+    try {
+        const loaded = (await import("typescript"));
+        ts = (loaded.default ?? loaded);
+        if (typeof ts.createProgram !== "function")
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const configs = findProjectConfigs(ts, root);
+    return configs.length > 0 ? { ts, configs } : null;
+}
+/** Callers of one symbol declared in one file — the question the hook asks. */
+export function callersOf(graph, symbol, declaredIn) {
+    return graph.edges.filter((e) => e.symbol === symbol && e.to === declaredIn);
+}

package/dist/lib/index/context-card.js

@@ -0,0 +1,140 @@
+import { byCodeUnit } from "./order.js";
+const DEFAULT_SKELETON_LINES = 60;
+const DEFAULT_MAX_CALLERS = 20;
+export function buildContextCard(index, graph, calls, path, options = {}) {
+    const file = index.files.find((candidate) => candidate.path === path);
+    if (!file)
+        return null;
+    const maxCallers = options.maxCallers ?? DEFAULT_MAX_CALLERS;
+    const maxSkeleton = options.maxSkeletonLines ?? DEFAULT_SKELETON_LINES;
+    const notes = [];
+    const importEdges = graph.edges.filter((edge) => edge.from === path);
+    const resolvedBySpecifier = new Map();
+    for (const edge of importEdges)
+        resolvedBySpecifier.set(edge.to, edge.to);
+    const imports = file.result.imports.map((imported) => ({
+        specifier: imported.specifier,
+        resolved: graph.edges.find((edge) => edge.from === path && imported.names.every((n) => edge.names.includes(n)))
+            ?.to ?? null,
+    }));
+    // Callers: import edges and call edges pointing at this file, merged so a
+    // file that both imports and calls appears once with both reasons.
+    const callerReasons = new Map();
+    for (const edge of graph.edges) {
+        if (edge.to !== path)
+            continue;
+        append(callerReasons, edge.from, `imports this file`);
+    }
+    for (const edge of calls.edges) {
+        if (edge.to !== path || edge.from === path)
+            continue;
+        append(callerReasons, edge.from, `calls ${edge.symbol}()`);
+    }
+    const allCallers = [...callerReasons.entries()]
+        .map(([caller, reasons]) => ({ path: caller, reason: reasons.sort().join("; ") }))
+        .sort((a, b) => byCodeUnit(a.path, b.path));
+    const callers = allCallers.slice(0, maxCallers);
+    if (allCallers.length > callers.length) {
+        notes.push(`${allCallers.length - callers.length} further callers were omitted by the budget`);
+    }
+    const callees = calls.edges
+        .filter((edge) => edge.from === path && edge.to !== path)
+        .map((edge) => ({ path: edge.to, symbol: edge.symbol }))
+        .sort((a, b) => byCodeUnit(a.path, b.path) || byCodeUnit(a.symbol, b.symbol));
+    let skeleton = [];
+    let truncated = false;
+    if (options.readFile) {
+        try {
+            const outline = outlineOf(options.readFile(path));
+            skeleton = outline.slice(0, maxSkeleton);
+            truncated = outline.length > skeleton.length;
+            if (truncated)
+                notes.push(`skeleton truncated at ${maxSkeleton} lines`);
+        }
+        catch (error) {
+            notes.push(`source could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const parsed = file.result.status === "parsed";
+    if (!parsed) {
+        notes.push(`this file's parse status is "${file.result.status}", so its surface may be incomplete`);
+    }
+    // A caller list is only as complete as the graph behind it. Reusing the same
+    // honesty rule as impact: unresolved edges anywhere mean the neighbourhood
+    // may be larger than shown.
+    if (graph.unresolved.length > 0) {
+        notes.push(`${graph.unresolved.length} unresolved imports repository-wide may hide further callers`);
+    }
+    if (calls.unanalyzed.length > 0) {
+        notes.push(`${calls.unanalyzed.length} files had no call analysis`);
+    }
+    return {
+        localOnly: true,
+        path,
+        language: file.language,
+        exports: file.result.exports.map((exported) => ({ name: exported.name, kind: exported.kind })),
+        imports,
+        callers,
+        callees,
+        skeleton,
+        quality: {
+            parsed,
+            complete: graph.unresolved.length === 0 && calls.unanalyzed.length === 0 && parsed,
+            truncated,
+            notes,
+        },
+    };
+}
+/**
+ * A structural outline: lines that declare something, with bodies dropped.
+ *
+ * Intentionally crude and language-agnostic. A real outline belongs to the
+ * language backend, which knows what a declaration is; doing it properly here
+ * would mean a second, worse parser living outside the registry — the exact
+ * duplication the registry exists to prevent. This is a budgeted preview, and
+ * anything that depends on precision should use `exports` instead.
+ */
+function outlineOf(source) {
+    const lines = source.split("\n");
+    const outline = [];
+    for (const raw of lines) {
+        const line = raw.trimEnd();
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*"))
+            continue;
+        // Indentation is the cheap, language-agnostic proxy for "this is a
+        // declaration rather than a statement inside one". Without it, a `const`
+        // in a function body matches the same pattern as a top-level `const` and
+        // the outline quietly becomes a copy of the source — which is the one
+        // thing a bounded preview must not be.
+        if (/^\s/.test(raw))
+            continue;
+        if (/^(export|import|class|interface|type|function|async function|const|let|enum|def|impl|struct)\b/.test(trimmed)) {
+            // Drop an opening body brace so the outline reads as signatures.
+            outline.push(line.replace(/\s*\{\s*$/, ""));
+        }
+    }
+    return outline;
+}
+function append(map, key, value) {
+    const list = map.get(key);
+    if (list)
+        list.push(value);
+    else
+        map.set(key, [value]);
+}
+/**
+ * Throws if a context card is about to be transmitted.
+ *
+ * Call this at any point where a value of unknown provenance is heading for
+ * the network. It is a runtime backstop for the case the type system cannot
+ * see — a card that arrived as `unknown` from JSON, or through an `any`.
+ */
+export function assertNotTransmissible(value) {
+    if (value && typeof value === "object" && value.localOnly === true) {
+        throw new Error("refusing to transmit a local context card: it carries source skeletons, which must never " +
+            "reach the central server (inv_01KZWPAM9QCZ0DD7789N55X647). Send a PrivacyBoundaryPayload instead.");
+    }
+}

package/dist/lib/index/coverage.js

@@ -0,0 +1,218 @@
+import { byCodeUnit } from "./order.js";
+/** How many examples to keep per reason. Bounded so a fact never grows without limit. */
+const SAMPLE_LIMIT = 5;
+const take = (values) => ({
+    count: values.length,
+    sample: [...new Set(values)].sort(byCodeUnit).slice(0, SAMPLE_LIMIT),
+});
+/**
+ * Build one fact per file the index knows about.
+ *
+ * Every input is already keyed by the file that caused it — `UnresolvedEdge.from`,
+ * `UnresolvedCall.from`, `blindSpots[].path` — so attribution is a regrouping
+ * rather than an inference. That is why this can be exact: it is not guessing
+ * which file a repo-wide count came from, it is declining to throw that
+ * information away.
+ */
+export function buildCoverageFacts(index, graph, calls) {
+    const unresolvedImports = new Map();
+    for (const edge of graph.unresolved) {
+        // A dynamic specifier is unresolvable by construction rather than by
+        // failure, but it still hides a real edge, so it counts. The reason
+        // distinguishes them for anyone reading.
+        const list = unresolvedImports.get(edge.from);
+        const label = edge.dynamic ? `${edge.specifier} (dynamic)` : edge.specifier;
+        if (list)
+            list.push(label);
+        else
+            unresolvedImports.set(edge.from, [label]);
+    }
+    // Names something in this repository actually defines. Without this filter
+    // the facts are worse than useless.
+    //
+    // `resolveCallEdges` reports every callee it did not bind, and in a real file
+    // that is overwhelmingly `JSON.stringify`, `Math.floor`, `assert.equal`,
+    // `map`, `filter`, `edges.push`. None of them is evidence that a reference to
+    // *your* symbol was missed. An unfiltered list said `code-map.ts` had 80
+    // unbound calls, which reads as catastrophic and means nothing.
+    //
+    // `resolveReferenceEdges` already applies exactly this rule, and its comment
+    // says why: "a false incompleteness warning destroys a correct answer and
+    // teaches the reader to discount the real ones." That is the Experiment C
+    // lesson, and coverage facts are precisely the surface where ignoring it
+    // would do the most damage — a blind-spot report nobody believes is worse
+    // than none, because it still looks like diligence.
+    const definedAnywhere = new Set();
+    for (const file of index.files) {
+        for (const definition of file.result.definitions ?? [])
+            definedAnywhere.add(definition.name);
+    }
+    // Repo-defined is necessary but not sufficient, and the gap between the two
+    // is where a name-matching filter turns back into noise. This repository
+    // defines local helpers called `push`, `add` and `get`, so `edges.push` and
+    // `bySymbol.get` pass a last-segment test and are still not references to
+    // anything. An unfiltered run called that 62 unbound calls in one module; the
+    // last-segment filter only got it to 16, all of them still spurious.
+    //
+    // So the rule uses structure rather than name resemblance, per file:
+    //
+    //   bare callee   count it when the repository defines the name and THIS file
+    //                 does not — a call to a local helper is not a cross-file
+    //                 dependent, which is the only kind a blast radius cares about.
+    //
+    //   recv.callee   count it when `recv` is a binding this file imports. That is
+    //                 the namespace case, `registryMod.LanguageRegistry`, which is
+    //                 exactly the one real miss the reference-edge grading found.
+    //                 `edges.push` fails it because `edges` is a local variable.
+    //
+    // No denylist of built-in method names, deliberately. A hand-maintained list
+    // of what JavaScript defines would be arbitrary, would need upkeep, and would
+    // be wrong in both directions.
+    const definedIn = new Map();
+    for (const file of index.files) {
+        definedIn.set(file.path, new Set((file.result.definitions ?? []).map((d) => d.name)));
+    }
+    // Bindings taken across an import edge that RESOLVED TO A FILE IN THIS REPO.
+    //
+    // Read from the graph rather than from the file's own import list, and the
+    // difference matters: `import assert from "node:assert/strict"` makes
+    // `assert` an imported binding, so `assert.deepEqual` passes a naive
+    // "receiver is imported" test and is obviously not a dependent of anything
+    // here. Graph edges only exist between repo files, so an external package can
+    // never contribute one.
+    const repoBindings = new Map();
+    for (const edge of graph.edges) {
+        let bindings = repoBindings.get(edge.from);
+        if (!bindings) {
+            bindings = new Set();
+            repoBindings.set(edge.from, bindings);
+        }
+        for (const name of edge.names)
+            bindings.add(name);
+    }
+    const couldHideADependent = (from, call) => {
+        if (!call.receiver) {
+            // A bare callee is now distinguishable from a member call. Count it only
+            // when this file does not define the name itself; that is the one case in
+            // which an unresolved bare call can hide a cross-file dependent.
+            return definedAnywhere.has(call.callee) && !(definedIn.get(from)?.has(call.callee) ?? false);
+        }
+        // Only the outermost receiver matters: `a.b.c` is reached through `a`.
+        const root = call.receiver.split(".")[0];
+        return repoBindings.get(from)?.has(root) ?? false;
+    };
+    const unboundCalls = new Map();
+    for (const call of calls.unresolved) {
+        if (!couldHideADependent(call.from, call))
+            continue;
+        const list = unboundCalls.get(call.from);
+        if (list)
+            list.push(call.callee);
+        else
+            unboundCalls.set(call.from, [call.callee]);
+    }
+    const blindSpots = new Map();
+    for (const spot of graph.blindSpots) {
+        // First reason wins, deterministically: blindSpots is already sorted by the
+        // index, and a file with two reasons is not twice as blind.
+        if (!blindSpots.has(spot.path))
+            blindSpots.set(spot.path, spot.reason);
+    }
+    const unanalyzed = new Set(calls.unanalyzed);
+    const facts = new Map();
+    for (const file of index.files) {
+        const imports = take(unresolvedImports.get(file.path) ?? []);
+        const bound = take(unboundCalls.get(file.path) ?? []);
+        const blindSpot = blindSpots.get(file.path) ?? null;
+        const isUnanalyzed = unanalyzed.has(file.path);
+        facts.set(file.path, {
+            path: file.path,
+            backend: file.parser ?? null,
+            language: file.language ?? null,
+            unresolvedImports: imports,
+            unboundCalls: bound,
+            blindSpot,
+            unanalyzed: isUnanalyzed,
+            clean: imports.count === 0 && bound.count === 0 && blindSpot === null && !isUnanalyzed,
+        });
+    }
+    return facts;
+}
+export function coverageForRadius(facts, paths) {
+    const inRadius = new Set(paths);
+    const within = [];
+    let elsewhereCount = 0;
+    for (const fact of facts.values()) {
+        if (fact.clean)
+            continue;
+        if (inRadius.has(fact.path))
+            within.push(fact);
+        else
+            elsewhereCount += 1;
+    }
+    within.sort((a, b) => byCodeUnit(a.path, b.path));
+    return {
+        within,
+        withinCount: within.length,
+        elsewhereCount,
+        radiusComplete: within.length === 0,
+    };
+}
+/** One human-checkable line per blind spot. Used by the context hook. */
+export function explainCoverage(coverage) {
+    if (coverage.radiusComplete) {
+        return coverage.elsewhereCount === 0
+            ? []
+            : [
+                `Graph coverage: complete for these files. ${coverage.elsewhereCount} file` +
+                    `${coverage.elsewhereCount === 1 ? "" : "s"} elsewhere in the repository are blind spots, none of them here.`,
+            ];
+    }
+    const lines = [`Graph blind spots among these files (${coverage.withinCount}):`];
+    for (const fact of coverage.within) {
+        const parts = [];
+        if (fact.blindSpot)
+            parts.push(`not parsed (${fact.blindSpot})`);
+        if (fact.unanalyzed)
+            parts.push("no call analysis for this language");
+        if (fact.unresolvedImports.count > 0) {
+            parts.push(`${fact.unresolvedImports.count} unresolved import${fact.unresolvedImports.count === 1 ? "" : "s"}` +
+                ` (${fact.unresolvedImports.sample.join(", ")})`);
+        }
+        if (fact.unboundCalls.count > 0) {
+            parts.push(`${fact.unboundCalls.count} unbound call${fact.unboundCalls.count === 1 ? "" : "s"}` +
+                ` (${fact.unboundCalls.sample.join(", ")})`);
+        }
+        lines.push(`  ${fact.path}: ${parts.join("; ")}`);
+    }
+    lines.push("  Any of these could hide a dependent the radius does not name.");
+    return lines;
+}
+export function summarizeCoverage(facts) {
+    const summary = {
+        files: 0,
+        clean: 0,
+        withUnresolvedImports: 0,
+        withUnboundCalls: 0,
+        blindSpots: 0,
+        unanalyzed: 0,
+        totalUnresolvedImports: 0,
+        totalUnboundCalls: 0,
+    };
+    for (const fact of facts.values()) {
+        summary.files += 1;
+        if (fact.clean)
+            summary.clean += 1;
+        if (fact.unresolvedImports.count > 0)
+            summary.withUnresolvedImports += 1;
+        if (fact.unboundCalls.count > 0)
+            summary.withUnboundCalls += 1;
+        if (fact.blindSpot)
+            summary.blindSpots += 1;
+        if (fact.unanalyzed)
+            summary.unanalyzed += 1;
+        summary.totalUnresolvedImports += fact.unresolvedImports.count;
+        summary.totalUnboundCalls += fact.unboundCalls.count;
+    }
+    return summary;
+}

package/dist/lib/index/delivery.js

@@ -0,0 +1,66 @@
+import { byCodeUnit } from "./order.js";
+/** Format ranked retrieval into the one response an agent needs to act. */
+export function answerRetrieval(query, candidates, options = {}) {
+    const limit = options.limit ?? 10;
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const threshold = options.materialityThreshold ?? 3;
+    const excluded = options.excludePaths ?? new Set();
+    const leased = options.leasedPaths ?? new Set();
+    const unexcluded = [...candidates].filter((candidate) => !excluded.has(candidate.page.target_path));
+    // A module page's target_path is a directory, so serving one answers "where
+    // do I edit?" with a folder. It cost 15% of slots on the retrieval benchmark
+    // — slots that can never contain the file the agent has to open. Directories
+    // still rank (their member list is real evidence), but they queue behind
+    // every file and only appear once files have run out.
+    const byRank = (a, b) => Number(Boolean(b.verified)) - Number(Boolean(a.verified)) || b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id);
+    // A chunk is an indexing artefact, never an answer: it names a span of a file
+    // an agent would open whole. Collapsing happens before fusion, so one
+    // arriving here means that collapse was bypassed.
+    const deliverable = unexcluded.filter((candidate) => candidate.page.page_type !== "chunk");
+    const files = deliverable.filter((candidate) => candidate.page.page_type !== "module").sort(byRank);
+    const modules = deliverable.filter((candidate) => candidate.page.page_type === "module").sort(byRank);
+    const ranked = [...files, ...modules];
+    const results = ranked
+        .slice(offset, offset + limit)
+        .map((candidate) => {
+        const isLeased = leased.has(candidate.page.target_path);
+        const bounds = candidate.page.span;
+        return {
+            ...candidate,
+            leased: isLeased,
+            ...(isLeased ? { warning: "active lease: do not start here" } : {}),
+            // One span per file, deliberately. Several spans from one file would
+            // make a limit of ten return fewer than ten files, which silently
+            // redefines the recall the whole benchmark is graded on.
+            ...(bounds && candidate.page.body
+                ? {
+                    span: {
+                        file_path: candidate.page.target_path,
+                        start_line: bounds.start_line,
+                        end_line: bounds.end_line,
+                        skeleton_context: candidate.page.summary,
+                        span_content: candidate.page.body,
+                    },
+                }
+                : {}),
+        };
+    });
+    const nextOffset = offset + results.length;
+    const hasMore = ranked.length > nextOffset;
+    return {
+        query,
+        fired: ranked.length > threshold,
+        results,
+        files_served: results.length,
+        reasons: results.map((item) => item.reason ?? (item.verified ? "compiler-verified candidate" : "retrieval-ranked candidate")),
+        iteration: {
+            offset,
+            limit,
+            excluded_candidates: candidates.length - ranked.length,
+            returned_paths: results.map((item) => item.page.target_path),
+            next_offset: hasMore ? nextOffset : null,
+            has_more: hasMore,
+            continue_reason: hasMore ? "more_candidates" : results.length ? "no_more_candidates" : "no_unexcluded_candidates",
+        },
+    };
+}