@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/rtm/dataflow-taint.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATAFLOW_LIMITS = void 0;
+exports.taintDataFlow = taintDataFlow;
+/**
+ * What this pass does NOT model. Carried in every result, for the same reason REQ-138 carries
+ * `TAINT_LIMITS`: a screening signal that does not state its blind spots is read as a proof.
+ */
+exports.DATAFLOW_LIMITS = [
+    'no field sensitivity (obj.a and obj.b are one value)',
+    'no aliasing',
+    'no path sensitivity',
+    'no container/element tracking',
+    'no reflection or dynamic dispatch',
+    'sink matching is by callee NAME with no receiver type — RE.exec(s) is indistinguishable from child_process.exec(s)',
+    'no anonymous-function parameters (arrow/function-expression params are not bound)',
+    'not statement-order sensitive — a variable tainted anywhere in a function is tainted throughout it',
+    'reports reachability of tainted data to a sink, never exploitability',
+];
+const DEFAULT_MAX_ITERATIONS = 10;
+const DEFAULT_MAX_FINDINGS = 100;
+/** Source patterns are path-shaped fragments of an expression (`req.body` in `req.body.cmd`), so substring is correct here. */
+const matchesText = (text, patterns) => {
+    const t = text.toLowerCase();
+    return patterns.some((p) => p && t.includes(p.toLowerCase()));
+};
+/** A callee NAME is matched exactly — see `DataFlowTaintConfig.sinks` for the two false positives substring matching produced. */
+const matchesName = (name, patterns) => {
+    const n = name.toLowerCase();
+    return patterns.some((p) => p && p.toLowerCase() === n);
+};
+/**
+ * A FUNCTION's identity is `(file, qualifiedName)`, and a VARIABLE's is that plus its name.
+ *
+ * The file is not decoration. Measured while writing the ambiguity test: keying on the qualified
+ * name alone made two files that each declare `function run(...)` collapse into ONE function, which
+ * both defeated the ambiguity refusal below AND let taint leak across files — a variable tainted in
+ * `a.ts` marked a same-named variable in `b.ts` as tainted, a finding with no flow behind it.
+ */
+const fid = (file, fn) => `${file}|${fn}`;
+const key = (fnId, name) => `${fnId}::${name}`;
+/** Sanitizer KILL. Applied before every other rule: a sanitized expression is clean whatever it reads. */
+const isSanitized = (e, cfg) => e.callees.some((c) => matchesName(c, cfg.sanitizers));
+/**
+ * Taint propagation to a fixpoint.
+ *
+ * Pure: no I/O, no clock, no randomness. Facts are visited in a stable order and findings are
+ * deduped and sorted, so the same input always produces byte-identical output.
+ */
+function taintDataFlow(factSet, cfg) {
+    const maxIterations = cfg.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const maxFindings = cfg.maxFindings ?? DEFAULT_MAX_FINDINGS;
+    // Flatten with file provenance, in a stable order.
+    const files = [...factSet].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    const defs = files.flatMap(({ file, facts }) => facts.defs.map((d) => ({ ...d, file })));
+    const calls = files.flatMap(({ file, facts }) => facts.calls.map((c) => ({ ...c, file })));
+    const returns = files.flatMap(({ file, facts }) => facts.returns.map((r) => ({ ...r, file })));
+    const params = files.flatMap(({ file, facts }) => facts.params.map((p) => ({ ...p, file })));
+    // Callee name -> the functions declaring it. A name declaring MORE THAN ONE function is
+    // ambiguous, and rule 4 refuses to bind through it: `addCallEdges` makes the same call, because a
+    // wrong binding silently poisons every finding derived from it while a missing one is a disclosed
+    // gap. `Class.method` is indexed by its last segment too, so a method call resolves.
+    //
+    // Built from EVERY fact kind, not just `params`. Measured: indexing only functions that declare a
+    // parameter made a zero-argument function unresolvable, so `const y = src()` could never receive
+    // `src`'s tainted return — the whole RETURN→CALL-SITE rule was dead for that very common shape.
+    const fnsByName = new Map();
+    const declare = (file, fn) => {
+        if (!fn || fn === '<module>')
+            return; // <module> is not callable; indexing it would invite bogus binds
+        for (const n of [fn, fn.includes('.') ? fn.slice(fn.lastIndexOf('.') + 1) : null]) {
+            if (!n)
+                continue;
+            if (!fnsByName.has(n))
+                fnsByName.set(n, new Set());
+            fnsByName.get(n).add(fid(file, fn));
+        }
+    };
+    for (const p of params)
+        declare(p.file, p.fn);
+    for (const r of returns)
+        declare(r.file, r.fn);
+    for (const d of defs)
+        declare(d.file, d.fn);
+    for (const c of calls)
+        declare(c.file, c.fn);
+    const resolveUnique = (callee) => {
+        const s = fnsByName.get(callee);
+        return s && s.size === 1 ? [...s][0] : null;
+    };
+    const paramAt = (fnId, index) => params.find((p) => fid(p.file, p.fn) === fnId && p.index === index);
+    // fn -> the functions it calls that are known to return tainted data (rule 5 needs this per round).
+    const returnsByFn = new Map();
+    for (const r of returns) {
+        const id = fid(r.file, r.fn);
+        if (!returnsByFn.has(id))
+            returnsByFn.set(id, []);
+        returnsByFn.get(id).push(r);
+    }
+    const tainted = new Map();
+    const taint = (k, step, from) => {
+        if (tainted.has(k))
+            return false;
+        tainted.set(k, { step, from });
+        return true;
+    };
+    /**
+     * The key under which a source-bearing expression is tainted when it is not bound to a variable.
+     *
+     * A source does not have to be assigned before it is used. `exec(req.body.cmd)` is the most direct
+     * injection shape there is, and a rule that only taints DEFS reports nothing for it — measured, on
+     * a version of this pass that 27 tests called green. The same hole swallowed `run(req.body.cmd)`
+     * and `return process.argv[2]`. So a source occurrence anywhere gets a pseudo-variable, and every
+     * rule reaches it through the one `carrier` predicate below.
+     */
+    const srcKey = (fnId, text) => key(fnId, `<source>${text}`);
+    /**
+     * An expression carries taint iff it is not sanitized AND either reads a tainted variable of `fn`
+     * or is itself a source. Returns the origin key so the flow path can be replayed from it.
+     */
+    const carrier = (e, fnId) => {
+        if (isSanitized(e, cfg))
+            return null;
+        for (const r of e.refs) {
+            const k = key(fnId, r);
+            if (tainted.has(k))
+                return k;
+        }
+        const sk = srcKey(fnId, e.text);
+        return tainted.has(sk) ? sk : null;
+    };
+    // SOURCE is not part of the loop: it depends on nothing the loop can change. It covers every place
+    // an expression appears — a def's initialiser, a call argument, and a returned value.
+    const markSource = (e, fnId, file, line, detail) => {
+        // The `isSanitized` half here is DEFENCE IN DEPTH, and deliberately not mutation-discriminated:
+        // `carrier` is the real gate, and it rejects the same expression before this entry can be read
+        // (the pseudo key is derived from the expression's own text, so only that expression retrieves
+        // it). Deleting this line leaves every test green. It stays so that a future change to
+        // `carrier`'s lookup cannot silently resurrect sanitized sources — not as a tested behaviour.
+        if (isSanitized(e, cfg) || !matchesText(e.text, cfg.sources))
+            return;
+        const k = srcKey(fnId, e.text);
+        taint(k, { rule: 'source', variable: k, file, line, detail }, null);
+    };
+    for (const d of defs)
+        markSource(d.expr, fid(d.file, d.fn), d.file, d.line, `${d.name} = ${d.expr.text}`);
+    for (const r of returns)
+        markSource(r.expr, fid(r.file, r.fn), r.file, r.line, `return ${r.expr.text}`);
+    for (const c of calls) {
+        for (let i = 0; i < c.args.length; i++) {
+            markSource(c.args[i], fid(c.file, c.fn), c.file, c.line, `${c.callee}(…) argument ${i} = ${c.args[i].text}`);
+        }
+    }
+    // A def whose initialiser IS a source names the variable directly, which reads better in a flow
+    // path than the pseudo-variable would. The pseudo entry above still exists and is harmless.
+    for (const d of defs) {
+        if (isSanitized(d.expr, cfg) || !matchesText(d.expr.text, cfg.sources))
+            continue;
+        const k = key(fid(d.file, d.fn), d.name);
+        taint(k, { rule: 'source', variable: k, file: d.file, line: d.line, detail: `${d.name} = ${d.expr.text}` }, null);
+    }
+    let converged = false;
+    for (let iter = 0; iter < maxIterations; iter++) {
+        let changed = false;
+        // ASSIGN — a def reading a tainted variable of the same function.
+        for (const d of defs) {
+            const k = key(fid(d.file, d.fn), d.name);
+            if (tainted.has(k))
+                continue;
+            const from = carrier(d.expr, fid(d.file, d.fn));
+            if (from) {
+                changed = taint(k, { rule: 'assign', variable: k, file: d.file, line: d.line, detail: `${d.name} = ${d.expr.text}` }, from) || changed;
+            }
+        }
+        // RETURN→CALL-SITE — a def invoking a function whose return expression is tainted.
+        for (const d of defs) {
+            const k = key(fid(d.file, d.fn), d.name);
+            if (tainted.has(k) || isSanitized(d.expr, cfg))
+                continue;
+            for (const calleeName of d.expr.callees) {
+                const target = resolveUnique(calleeName);
+                if (!target)
+                    continue;
+                const rs = returnsByFn.get(target) ?? [];
+                const tr = rs.find((r) => carrier(r.expr, target));
+                if (!tr)
+                    continue;
+                changed = taint(k, { rule: 'return', variable: k, file: d.file, line: d.line, detail: `${d.name} = ${calleeName}(…) returning tainted` }, carrier(tr.expr, target)) || changed;
+                break;
+            }
+        }
+        // ARG→PARAM — position binds; an ambiguous callee binds nothing.
+        for (const c of calls) {
+            for (let i = 0; i < c.args.length; i++) {
+                const from = carrier(c.args[i], fid(c.file, c.fn));
+                if (!from)
+                    continue;
+                const target = resolveUnique(c.callee);
+                if (!target)
+                    continue;
+                const p = paramAt(target, i);
+                if (!p)
+                    continue;
+                const k = key(target, p.name);
+                changed = taint(k, { rule: 'arg-param', variable: k, file: c.file, line: c.line, detail: `${c.callee}(…) argument ${i} binds ${p.name}` }, from) || changed;
+            }
+        }
+        if (!changed) {
+            converged = true;
+            break;
+        }
+    }
+    /** Walk a taint fact back to its source, oldest step first. */
+    const replay = (k) => {
+        const steps = [];
+        const seen = new Set();
+        let cur = k;
+        while (cur && tainted.has(cur) && !seen.has(cur)) {
+            seen.add(cur);
+            const e = tainted.get(cur);
+            steps.unshift(e.step);
+            cur = e.from;
+        }
+        return steps;
+    };
+    // SINK — reported after the fixpoint, so a finding always reflects the complete taint state.
+    const all = [];
+    for (const c of calls) {
+        if (!matchesName(c.callee, cfg.sinks))
+            continue;
+        for (let i = 0; i < c.args.length; i++) {
+            const from = carrier(c.args[i], fid(c.file, c.fn));
+            if (!from)
+                continue;
+            all.push({
+                file: c.file, fn: c.fn, callee: c.callee, line: c.line, argIndex: i, argText: c.args[i].text,
+                flow: [...replay(from), {
+                        rule: 'sink', variable: from, file: c.file, line: c.line,
+                        detail: `${c.callee}(…) argument ${i} = ${c.args[i].text}`,
+                    }],
+            });
+        }
+    }
+    // `argText` is part of the key, not decoration. Measured without it: `exec(a); exec(b);` written on
+    // ONE line collapsed to a single finding and `exec(b)` disappeared — a silent under-report, the
+    // failure mode this pass exists to avoid. Two calls that are genuinely identical (`exec(raw)`
+    // twice on one line) still collapse, which is the deduplication that was actually wanted.
+    const dedupKey = (f) => `${f.file}|${f.fn}|${f.callee}|${String(f.line).padStart(9, '0')}|${f.argIndex}|${f.argText}`;
+    const seen = new Set();
+    const unique = all.filter((f) => { const k = dedupKey(f); if (seen.has(k))
+        return false; seen.add(k); return true; });
+    unique.sort((a, b) => (dedupKey(a) < dedupKey(b) ? -1 : dedupKey(a) > dedupKey(b) ? 1 : 0));
+    const findings = unique.slice(0, maxFindings);
+    return {
+        kind: 'data-flow',
+        findings,
+        tainted: [...tainted.keys()].sort(),
+        limits: [...exports.DATAFLOW_LIMITS],
+        truncated: unique.length - findings.length,
+        converged,
+    };
+}

package/dist/holmes/rtm/gap-analyzer.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeConvergenceGaps = computeConvergenceGaps;
+function computeConvergenceGaps(scanned, specs, testAnchors) {
+    const approvedAspecs = specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved').map((s) => s.id);
+    const implemented = new Set();
+    const unanchoredFiles = [];
+    for (const f of scanned) {
+        const ids = f.implementsSpecs ?? [];
+        if (ids.length === 0)
+            unanchoredFiles.push(f.sourcePath);
+        for (const id of ids)
+            implemented.add(id);
+    }
+    const unimplementedSpecs = approvedAspecs.filter((id) => !implemented.has(id)).sort();
+    const tested = new Set();
+    for (const ids of Object.values(testAnchors ?? {}))
+        for (const id of ids)
+            tested.add(id);
+    const untestedSpecs = testAnchors
+        ? approvedAspecs.filter((id) => implemented.has(id) && !tested.has(id)).sort()
+        : [];
+    const gapCount = unimplementedSpecs.length + unanchoredFiles.length + untestedSpecs.length;
+    const denom = Math.max(1, approvedAspecs.length + scanned.length);
+    const score = Math.max(0, 1 - gapCount / denom);
+    return { unimplementedSpecs, unanchoredFiles: [...unanchoredFiles].sort(), untestedSpecs, score };
+}

package/dist/holmes/rtm/git-changes.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNameStatus = parseNameStatus;
+exports.assertSafeRev = assertSafeRev;
+exports.gitChangedFiles = gitChangedFiles;
+const node_child_process_1 = require("node:child_process");
+// @implements A-SPEC-113.1
+/**
+ * Pure parser for `git diff --name-status` output. Paths are already
+ * repo-relative POSIX paths as emitted by git — no path normalization here.
+ *
+ * Recognized status codes (one per tab-separated line):
+ *  - `A\tpath`            -> added
+ *  - `M\tpath`             -> modified
+ *  - `D\tpath`             -> deleted
+ *  - `R<score>\tfrom\tto`  -> renamed { from, to }
+ *  - `C<score>\tfrom\tto`  -> treated as an add of `to` (a copy introduces a
+ *    new file at `to`; the original at `from` is untouched, so there is no
+ *    corresponding delete/replace to emit for it).
+ *
+ * Blank lines are ignored. Unrecognized status codes are ignored rather than
+ * throwing, so a git version with an unfamiliar status letter degrades
+ * gracefully instead of crashing the whole reindex.
+ */
+function parseNameStatus(raw) {
+    const changes = { added: [], modified: [], deleted: [], renamed: [] };
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const cols = line.split('\t');
+        const status = cols[0];
+        if (status === 'A' && cols[1]) {
+            changes.added.push(cols[1]);
+        }
+        else if (status === 'M' && cols[1]) {
+            changes.modified.push(cols[1]);
+        }
+        else if (status === 'D' && cols[1]) {
+            changes.deleted.push(cols[1]);
+        }
+        else if (/^R\d+$/.test(status) && cols[1] && cols[2]) {
+            changes.renamed.push({ from: cols[1], to: cols[2] });
+        }
+        else if (/^C\d+$/.test(status) && cols[2]) {
+            changes.added.push(cols[2]);
+        }
+    }
+    return changes;
+}
+/**
+ * Rejects any git rev/ref that begins with `-`. Without this, a value like
+ * `--output=/victim/file` passed as `base`/`head` to `git diff` is parsed by
+ * git as an OPTION (not a positional ref), letting an attacker make git write
+ * or truncate an arbitrary file (audit B1, argument-injection). Defense in
+ * depth alongside the `--end-of-options` guard below.
+ */
+function assertSafeRev(v) {
+    if (/^-/.test(v)) {
+        throw new Error(`unsafe git ref (leading dash): ${v}`);
+    }
+}
+/**
+ * Thin, side-effecting wrapper: invokes real git and hands the raw output to
+ * the pure parser above. Kept isolated here so `parseNameStatus` stays
+ * testable on a raw string with no process/filesystem dependency.
+ */
+function gitChangedFiles(repoRoot, base, head) {
+    assertSafeRev(base);
+    assertSafeRev(head);
+    const raw = (0, node_child_process_1.execFileSync)('git', ['-C', repoRoot, 'diff', '--name-status', '--end-of-options', base, head], { encoding: 'utf8' });
+    return parseNameStatus(raw);
+}

package/dist/holmes/rtm/incremental.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyIncremental = applyIncremental;
+const rtm_builder_1 = require("./rtm-builder");
+/**
+ * Reduces every add/modify/delete/rename case to one primitive: replace file
+ * F's subgraph. Processing order is deterministic: deleted, renamed, added,
+ * modified.
+ *
+ * - deleted F: graph.removeBySource(F) — no re-add.
+ * - renamed {from,to}: graph.removeBySource(from); then `to` is treated as added.
+ * - added/modified F: graph.removeBySource(F); scanOne(F); if non-null,
+ *   buildFileSubgraph(sf, specs, graph).
+ *
+ * removeBySource runs before any re-add — including for a pure add — so the
+ * operation is idempotent: re-applying the same ChangeSet has no net effect
+ * beyond the first application.
+ *
+ * SPEC-file changes (paths under .ax/specs/) are out of scope here: scanOne
+ * returns null for non-code files, so only their removeBySource side (a
+ * no-op, since SPEC nodes are keyed on the spec's own sourcePath — see
+ * buildRtm/rtm-builder) would run. Incremental SPEC-node updates are
+ * deferred to a full spec reload for now.
+ */
+function applyIncremental(graph, changes, ctx) {
+    const replaceFile = (f) => {
+        graph.removeBySource(f);
+        const sf = ctx.scanOne(f);
+        if (sf)
+            (0, rtm_builder_1.buildFileSubgraph)(sf, ctx.specs, graph);
+    };
+    for (const f of changes.deleted) {
+        graph.removeBySource(f);
+    }
+    for (const { from, to } of changes.renamed) {
+        graph.removeBySource(from);
+        replaceFile(to);
+    }
+    for (const f of changes.added) {
+        replaceFile(f);
+    }
+    for (const f of changes.modified) {
+        replaceFile(f);
+    }
+}

package/dist/holmes/rtm/localize.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.significantTerms = significantTerms;
+exports.localizeIssue = localizeIssue;
+const STOP = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'when', 'then', 'from', 'into', 'not', 'but', 'are',
+    'was', 'were', 'have', 'has', 'had', 'does', 'did', 'should', 'would', 'could', 'will', 'can',
+    'error', 'bug', 'issue', 'fix', 'fails', 'failed', 'failing', 'broken', 'wrong', 'incorrect',
+    'file', 'code', 'test', 'tests', 'function', 'method', 'value', 'return', 'returns',
+]);
+// Compute cap (review D5): terms beyond this bound add noise, not signal, and the per-symbol scan is
+// O(terms × symbols) — a pasted 0.5MB issue must not stall the synchronous MCP handler.
+const MAX_TERMS = 64;
+/**
+ * Significant tokens of the text, UNICODE-aware (review D2: the old [^a-z0-9] split dropped every
+ * non-ASCII codepoint, so Korean issue text — and this repo's Korean spec titles — tokenized to
+ * NOTHING and localization was a silent no-op). Letters/digits of any script are token chars;
+ * camelCase/snake are split; Latin tokens need length>=3, non-ASCII (e.g. Korean) length>=2.
+ */
+function significantTerms(text) {
+    const raw = text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase -> camel Case
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => {
+        const minLen = /[^\x00-\x7f]/.test(t) ? 2 : 3;
+        return t.length >= minLen && !STOP.has(t);
+    });
+    return [...new Set(raw)].slice(0, MAX_TERMS);
+}
+const tokensOf = (s) => new Set(significantTerms(s));
+function localizeIssue(issueText, scanned, specs, topN = 10) {
+    const terms = significantTerms(issueText);
+    if (terms.length === 0)
+        return { terms: [], hits: [], matchedSpecs: [] };
+    const termSet = new Set(terms);
+    // 1) A-SPECs whose title/section text shares terms with the issue (RTM entry points). Restricted
+    //    to A-SPEC: files anchor A-SPECs only, so other spec kinds can never pull a file through the
+    //    hop and reporting them overstated what influenced the ranking (review D7). Threshold (review
+    //    D6): short issues (<=3 terms) match on a single overlapping term; longer issues need >=2 so
+    //    one common word doesn't fan out across the whole spec set.
+    const matchedSpecs = [];
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const specText = `${s.title} ${Object.values(s.sections).join(' ')}`;
+        const st = tokensOf(specText);
+        let overlap = 0;
+        for (const t of termSet)
+            if (st.has(t))
+                overlap++;
+        if (overlap >= 2 || (overlap === 1 && termSet.size <= 3))
+            matchedSpecs.push(s.id);
+    }
+    const matchedSpecSet = new Set(matchedSpecs);
+    // Vendored/mirrored trees (review D4): an identical copy under reference/vendor must not outrank —
+    // or lexically tie-break above — the live source. Their scores are halved and ties break toward
+    // non-vendor paths.
+    const isVendorPath = (p) => /(^|\/)(reference|vendor|vendors|third_party|third-party|external)\//i.test(p);
+    // 2) Score each scanned file: symbol-name matches (strong), path matches (weak),
+    //    implements-a-matched-spec (graph bonus the lexical layer cannot see).
+    const hits = [];
+    for (const f of scanned) {
+        const why = [];
+        let score = 0;
+        const matchedSymbols = [];
+        for (const sym of f.symbols) {
+            const symTokens = tokensOf(sym.qualifiedName);
+            const hitTerms = [...termSet].filter((t) => symTokens.has(t));
+            if (hitTerms.length > 0) {
+                score += 3 * hitTerms.length;
+                matchedSymbols.push(sym.qualifiedName);
+                why.push(`symbol ${sym.qualifiedName} matches [${hitTerms.join(', ')}]`);
+            }
+        }
+        const pathTokens = tokensOf(f.sourcePath);
+        const pathHits = [...termSet].filter((t) => pathTokens.has(t));
+        if (pathHits.length > 0) {
+            score += pathHits.length;
+            why.push(`path matches [${pathHits.join(', ')}]`);
+        }
+        // Dedupe: a file may carry the same @implements anchor many times (once per code section);
+        // each spec must count ONCE toward the bonus (live smoke showed 4x inflation otherwise).
+        const viaSpecs = [...new Set(f.implementsSpecs ?? [])].filter((id) => matchedSpecSet.has(id));
+        if (viaSpecs.length > 0) {
+            score += 4 * viaSpecs.length;
+            why.push(`implements matched spec(s) ${viaSpecs.join(', ')}`);
+        }
+        if (isVendorPath(f.sourcePath) && score > 0) {
+            score = score / 2;
+            why.push('vendored path — score halved');
+        }
+        if (score > 0)
+            hits.push({ file: f.sourcePath, score, matchedSymbols, viaSpecs, why });
+    }
+    hits.sort((a, b) => b.score - a.score ||
+        Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) || // ties: live source before vendor
+        a.file.localeCompare(b.file)); // then deterministic path order
+    return { terms, hits: hits.slice(0, topN), matchedSpecs: matchedSpecs.sort() };
+}