@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/review/semantic-arm.js

@@ -0,0 +1,717 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileTokens = fileTokens;
+exports.corpusIdf = corpusIdf;
+exports.rankIdf = rankIdf;
+exports.normalisedIdf = normalisedIdf;
+exports.rankWeighted = rankWeighted;
+exports.rankExpanded = rankExpanded;
+exports.matchedSpecsWeighted = matchedSpecsWeighted;
+exports.rankBreadthDamped = rankBreadthDamped;
+exports.anchorCoverage = anchorCoverage;
+exports.rankCoverageAware = rankCoverageAware;
+exports.rankCitationConditioned = rankCitationConditioned;
+exports.rankCapped = rankCapped;
+exports.rankUncitedCapped = rankUncitedCapped;
+exports.rankWithCallHop = rankWithCallHop;
+exports.ablate = ablate;
+exports.rankSpecLiftLimited = rankSpecLiftLimited;
+exports.rankWithBonusScale = rankWithBonusScale;
+exports.rankSpecReorderOnly = rankSpecReorderOnly;
+const localize_1 = require("../rtm/localize");
+const edge_quality_1 = require("./edge-quality");
+/**
+ * An alternative ranker, scored beside the product's — never in place of it.
+ *
+ * Goal Phase C asks for the semantic layer as an ARM: added to graph-off / current / enhanced and
+ * scored on the same corpus, adopted only if the measurement moves. Nothing here is wired into
+ * `localizeIssue`; if the numbers below do not beat the current arm, the honest outcome is a
+ * recorded negative result, which this repository already has several of.
+ *
+ * The mechanism is the oldest fix for the failure mode the current scorer has: every term is worth
+ * the same. `significantTerms` drops stop-words, but a corpus has its OWN ubiquitous vocabulary that
+ * no global stop-list knows — in this repository `spec`, `holmes` and `test` appear nearly
+ * everywhere, and matching one of them is close to no evidence at all. Precision, not recall, is
+ * what that costs, and precision is the axis Phase C targets.
+ */
+const tokensOf = (s) => new Set((0, localize_1.significantTerms)(s));
+/** Tokens of a file as the ranker sees it: its symbol names and its path. */
+function fileTokens(f) {
+    const out = tokensOf(f.sourcePath);
+    for (const sym of f.symbols)
+        for (const t of tokensOf(sym.qualifiedName))
+            out.add(t);
+    return out;
+}
+/**
+ * Inverse document frequency over the scanned corpus.
+ *
+ * Smoothed (`(N+1)/(df+1)`) and floored at zero: a term present in every file must be WEAK evidence,
+ * never negative evidence. Unsmoothed IDF would make it exactly 0 and let a file that matches only
+ * ubiquitous terms tie with a file that matches nothing, which reads as "no opinion" when the truth
+ * is "a little opinion".
+ */
+function corpusIdf(scanned) {
+    const df = new Map();
+    for (const f of scanned)
+        for (const t of fileTokens(f))
+            df.set(t, (df.get(t) ?? 0) + 1);
+    const n = scanned.length;
+    const idf = new Map();
+    for (const [t, d] of df)
+        idf.set(t, Math.max(Math.log((n + 1) / (d + 1)), 1e-6));
+    return idf;
+}
+/**
+ * Rank files by IDF-weighted term overlap.
+ *
+ * Symbol matches stay worth 3× a path match, as in the product's scorer — changing two things at
+ * once would leave the measurement unable to say which one moved. The only difference from the
+ * current arm is that each match is multiplied by how rare its term is in this corpus.
+ */
+function rankIdf(issueText, scanned, topN) {
+    const terms = new Set((0, localize_1.significantTerms)(issueText));
+    if (terms.size === 0 || scanned.length === 0)
+        return [];
+    const idf = corpusIdf(scanned);
+    const hits = [];
+    for (const f of scanned) {
+        let score = 0;
+        for (const sym of f.symbols) {
+            const st = tokensOf(sym.qualifiedName);
+            for (const t of terms)
+                if (st.has(t))
+                    score += 3 * (idf.get(t) ?? 0);
+        }
+        const pt = tokensOf(f.sourcePath);
+        for (const t of terms)
+            if (pt.has(t))
+                score += idf.get(t) ?? 0;
+        if (score > 0)
+            hits.push({ file: f.sourcePath, score });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, topN);
+}
+/**
+ * IDF, rescaled so the MEAN weight over the corpus vocabulary is 1.
+ *
+ * Without this the arm would not be a one-variable change. Raw IDF values sit well below 1 on a
+ * corpus of a few hundred files, so every lexical contribution shrinks at once while the spec-anchor
+ * bonus (+4/sqrt(anchors)) and the citation bonus (+20/sqrt(anchors)) keep their size — the arm would
+ * then be measuring how much the graph bonuses dominate, not how much term rarity helps. Rescaling
+ * keeps the lexical term's total magnitude comparable and changes only its DISTRIBUTION across
+ * terms, which is the hypothesis under test.
+ *
+ * An unseen term weighs exactly 1: a word absent from the corpus is not evidence against a file, and
+ * mapping it to 0 would silently delete the request's most distinctive vocabulary.
+ */
+function normalisedIdf(scanned) {
+    const idf = corpusIdf(scanned);
+    const vals = [...idf.values()];
+    if (vals.length === 0)
+        return idf;
+    const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+    if (mean <= 0)
+        return new Map([...idf.keys()].map((t) => [t, 1]));
+    const out = new Map();
+    for (const [t, v] of idf)
+        out.set(t, v / mean);
+    return out;
+}
+const CITATION_BONUS = 20;
+const isVendorPath = (p) => /(^|\/)(reference|vendor|vendors|third_party|third-party|external)\//i.test(p);
+/**
+ * The product's scorer with the term weight lifted out as a parameter.
+ *
+ * This mirrors `localizeIssue` deliberately and the mirror is load-bearing, so a test pins it: with
+ * `() => 1` this function must return the product's ranking and its scores EXACTLY. If someone
+ * changes the product's scoring and not this one, that test goes red rather than the replay quietly
+ * reporting a difference between rankers that is really a difference between vintages.
+ */
+function rankWeighted(issueText, scanned, specs, topN, weight, 
+/**
+ * @implements A-SPEC-352
+ * Weighted spec gate. Absent = the product's `overlap >= 2` count.
+ *
+ * Passed in here rather than reimplemented by the caller for a reason paid for three times: the
+ * first IDF arm hand-rolled a scorer and silently dropped the spec and citation bonuses; a probe
+ * of this very gate hand-rolled one again and dropped the citation path, whose +20 bonus is the
+ * largest single gain this repository has measured. Both produced confident, worthless numbers.
+ * Every arm goes through this function so the features it does NOT vary cannot go missing.
+ */
+gateThreshold) {
+    const terms = (0, localize_1.significantTerms)(issueText);
+    const citations = (0, localize_1.citationsIn)(issueText, new Set(specs.map((s) => s.id)));
+    const citedSet = new Set(citations.cited);
+    if (terms.length === 0 && citations.cited.length === 0)
+        return [];
+    const termSet = new Set(terms);
+    const matchedSpecs = gateThreshold === undefined
+        ? (() => {
+            const out = [];
+            for (const s of specs) {
+                if (s.type !== 'A-SPEC')
+                    continue;
+                const st = tokensOf(`${s.title} ${Object.values(s.sections).join(' ')}`);
+                let overlap = 0;
+                for (const t of termSet)
+                    if (st.has(t))
+                        overlap++;
+                if (overlap >= 2 || (overlap === 1 && termSet.size <= 3))
+                    out.push(s.id);
+            }
+            return out;
+        })()
+        : matchedSpecsWeighted(issueText, specs, weight, gateThreshold);
+    for (const id of citations.cited)
+        if (!matchedSpecs.includes(id))
+            matchedSpecs.push(id);
+    const matchedSpecSet = new Set(matchedSpecs);
+    const hits = [];
+    for (const f of scanned) {
+        let score = 0;
+        for (const sym of f.symbols) {
+            const st = tokensOf(sym.qualifiedName);
+            const hit = [...termSet].filter((t) => st.has(t));
+            for (const t of hit)
+                score += 3 * weight(t);
+        }
+        const pt = tokensOf(f.sourcePath);
+        for (const t of termSet)
+            if (pt.has(t))
+                score += weight(t);
+        const anchors = [...new Set(f.implementsSpecs ?? [])];
+        const viaSpecs = anchors.filter((id) => matchedSpecSet.has(id));
+        if (viaSpecs.length > 0)
+            score += Math.round(4 * viaSpecs.length / Math.sqrt(anchors.length) * 100) / 100;
+        const citedAnchors = anchors.filter((id) => citedSet.has(id));
+        if (citedAnchors.length > 0) {
+            score += Math.round(CITATION_BONUS * citedAnchors.length / Math.sqrt(anchors.length) * 100) / 100;
+        }
+        if (isVendorPath(f.sourcePath) && score > 0)
+            score = score / 2;
+        if (score > 0)
+            hits.push({ file: f.sourcePath, score });
+    }
+    hits.sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file));
+    return hits.slice(0, topN);
+}
+/**
+ * The spec graph, undirected.
+ *
+ * `dependsOn` points from a child to its parent, so the semantically interesting neighbour — another
+ * A-SPEC under the same H-SPEC — is TWO hops away: up to the parent and back down. Walking the
+ * edges in one direction only would make siblings unreachable and the expansion would look useless
+ * for a reason that is about the walk, not about the idea.
+ */
+function specAdjacency(specs) {
+    const known = new Set(specs.map((s) => s.id));
+    const adj = new Map();
+    const link = (a, b) => {
+        (adj.get(a) ?? adj.set(a, []).get(a)).push(b);
+        (adj.get(b) ?? adj.set(b, []).get(b)).push(a);
+    };
+    for (const s of specs)
+        for (const p of s.dependsOn ?? [])
+            if (known.has(p))
+                link(s.id, p);
+    return adj;
+}
+/**
+ * Rank with GraphRAG-style expansion over the spec graph.
+ *
+ * The gap this addresses is the one graph retrieval exists for: the answer does not contain the
+ * request's words, but it is the neighbour of something that does. The lexical layer scores a file
+ * only if the request's terms reach the file or a spec it anchors — one hop. A sibling requirement,
+ * written in different words for the same feature, is invisible however closely it is related.
+ *
+ * Deliberately weaker than a hit at every hop: the bonus is the matched-spec bonus times `decay^k`.
+ * A neighbour is evidence, not an answer, and if decay ever let it outrank a direct match the
+ * retrieval would be trading the answer for its neighbourhood. A test pins that ordering.
+ *
+ * Everything else is `rankWeighted` unchanged — the one-variable rule from A-SPEC-349 applies here
+ * too, or a win could not be attributed to expansion rather than to weighting.
+ */
+function rankExpanded(issueText, scanned, specs, topN, weight, opts) {
+    const base = rankWeighted(issueText, scanned, specs, scanned.length, weight);
+    if (opts.hops <= 0 || opts.decay <= 0)
+        return base.slice(0, topN);
+    // Which specs the request matched — recomputed exactly as `rankWeighted` does, so the two agree.
+    const terms = new Set((0, localize_1.significantTerms)(issueText));
+    const citations = (0, localize_1.citationsIn)(issueText, new Set(specs.map((s) => s.id)));
+    const matched = new Set(citations.cited);
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const st = tokensOf(`${s.title} ${Object.values(s.sections).join(' ')}`);
+        let overlap = 0;
+        for (const t of terms)
+            if (st.has(t))
+                overlap++;
+        if (overlap >= 2 || (overlap === 1 && terms.size <= 3))
+            matched.add(s.id);
+    }
+    if (matched.size === 0)
+        return base.slice(0, topN);
+    const adj = specAdjacency(specs);
+    const hopOf = new Map([...matched].map((id) => [id, 0]));
+    let wave = [...matched];
+    for (let k = 1; k <= opts.hops && wave.length > 0; k++) {
+        const next = [];
+        for (const id of wave)
+            for (const n of adj.get(id) ?? []) {
+                if (hopOf.has(n))
+                    continue; // first arrival wins: the shortest path is the strongest claim
+                hopOf.set(n, k);
+                next.push(n);
+            }
+        wave = next;
+    }
+    const score = new Map(base.map((h) => [h.file, h.score]));
+    for (const f of scanned) {
+        const anchors = [...new Set(f.implementsSpecs ?? [])];
+        if (anchors.length === 0)
+            continue; // expansion reaches files THROUGH specs; anchor or nothing
+        let bonus = 0;
+        for (const id of anchors) {
+            const k = hopOf.get(id);
+            if (k === undefined || k === 0)
+                continue; // hop 0 is already in the base score
+            bonus += 4 * Math.pow(opts.decay, k) / Math.sqrt(anchors.length);
+        }
+        if (bonus > 0)
+            score.set(f.sourcePath, (score.get(f.sourcePath) ?? 0) + Math.round(bonus * 100) / 100);
+    }
+    return [...score.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([file, s]) => ({ file, score: s }))
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * Which A-SPECs the request is taken to have matched — the entry point into the knowledge graph.
+ *
+ * The product's rule counts overlapping terms: two shared words admit a spec, one does not (unless
+ * the request is very short). That treats a shared `handler` exactly like a shared `quarantine`, and
+ * it costs more here than it does in file scoring: an admitted spec sprays its bonus over EVERY file
+ * anchoring it, so one wrongly-opened gate promotes a whole group of unrelated files at once.
+ *
+ * Weighing the overlap instead of counting it means a request has to bring either several ordinary
+ * words or one genuinely distinctive one. With `weight = () => 1` and `threshold = 2` this is the
+ * product's original rule exactly, which is what makes any measured difference attributable.
+ *
+ * A-SPEC only: files anchor A-SPECs, so admitting any other kind can never pull a file through the
+ * hop and would only overstate what influenced the ranking.
+ */
+function matchedSpecsWeighted(issueText, specs, weight, threshold) {
+    const terms = new Set((0, localize_1.significantTerms)(issueText));
+    const out = [];
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const st = tokensOf(`${s.title} ${Object.values(s.sections).join(' ')}`);
+        let mass = 0;
+        for (const t of terms)
+            if (st.has(t))
+                mass += weight(t);
+        // The short-request escape hatch survives: a three-word request cannot reach a threshold built
+        // for prose, and dropping it would change two things at once.
+        if (mass >= threshold || (mass > 0 && terms.size <= 3))
+            out.push(s.id);
+    }
+    return out;
+}
+/**
+ * The spec bonus, damped by how much code the spec covers.
+ *
+ * The existing normalisation divides by how many anchors a FILE carries (A-SPEC-270) — it answers
+ * "how much of this file's identity is this spec?". It never asks the other question: "how much of
+ * this spec's territory is this file?". A spec spanning twenty files says little about any one of
+ * them; a spec covering one says a great deal, and today they pay the same +4.
+ *
+ * That asymmetry is invisible in a repository with hundreds of narrow specs and decisive in one with
+ * a few broad ones — which is exactly where the measured precision loss appeared (A-SPEC-362: on a
+ * 54-spec corpus the product loses Top-5 recall and Top-10 precision to plain word matching, and the
+ * weighting-only arm is indistinguishable from that baseline).
+ *
+ * sqrt, matching the existing normalisation's shape: a one-file spec is untaxed, a twenty-file spec
+ * is damped by ~4.5x rather than erased. Damping to zero would delete the very hop that carries all
+ * of this harness's measured advantage.
+ */
+function rankBreadthDamped(issueText, scanned, specs, topN, weight, gateThreshold) {
+    const filesPerSpec = new Map();
+    for (const f of scanned) {
+        for (const id of new Set(f.implementsSpecs ?? []))
+            filesPerSpec.set(id, (filesPerSpec.get(id) ?? 0) + 1);
+    }
+    const base = rankWeighted(issueText, scanned, specs, scanned.length, weight, gateThreshold);
+    const byFile = new Map(scanned.map((f) => [f.sourcePath, f]));
+    const adjusted = base.map((hit) => {
+        const f = byFile.get(hit.file);
+        const anchors = [...new Set(f?.implementsSpecs ?? [])];
+        if (anchors.length === 0)
+            return hit;
+        // Recover the spec component and re-pay it damped, leaving the lexical part untouched: the arm
+        // must differ from the product in this one term only.
+        let credited = 0, damped = 0;
+        for (const id of anchors) {
+            const breadth = filesPerSpec.get(id) ?? 1;
+            const share = 4 / Math.sqrt(anchors.length);
+            credited += share;
+            damped += share / Math.sqrt(breadth);
+        }
+        // `credited` overstates when the gate admitted only some anchors, so scale by what the base
+        // actually paid rather than subtracting a number it may never have added.
+        const paid = Math.min(credited, hit.score);
+        return { file: hit.file, score: hit.score - paid + paid * (credited === 0 ? 1 : damped / credited) };
+    });
+    return adjusted
+        .filter((h) => h.score > 0)
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * How much of the corpus carries an `@implements` anchor at all.
+ *
+ * The spec layer's evidence is only representative when a decent share of the tree is governed. If
+ * five files in a thousand carry anchors, matching one of their specs says something about those
+ * five and nothing about the other nine hundred and ninety-five — yet the bonus is paid at full
+ * strength and displaces lexically correct candidates.
+ */
+function anchorCoverage(scanned, specs = []) {
+    if (scanned.length === 0)
+        return 0;
+    // RESOLVED anchors, not merely present ones. The first version of this counted files carrying any
+    // `@implements` marker and returned exactly 1.000 on both corpora — a metric that separated
+    // nothing, and the two arms it fed were byte-identical at every spec density. Thinning the spec
+    // store does not remove the markers in the code; it strands them. A marker pointing at a spec that
+    // is not in the store is precisely the sparse-layer condition, so it must count as UNCOVERED.
+    const known = new Set(specs.map((s) => s.id));
+    if (known.size === 0)
+        return 0;
+    return scanned.filter((f) => (f.implementsSpecs ?? []).some((id) => known.has(id))).length / scanned.length;
+}
+/**
+ * The spec bonus scaled by how much of the tree the spec layer actually covers.
+ *
+ * Measured on one repository with only the spec count varied (A-SPEC-364): 585 specs gave Top-10
+ * recall 0.770, but 146 gave 0.253 and 59 gave 0.264 — BELOW the 0.305 of no spec layer at all. A
+ * partly populated spec store is worse than an empty one, and every project that adopts Holmes
+ * passes through that valley on its way to the peak. jarvis, at 54 specs, is sitting in it.
+ *
+ * Scaling by coverage makes the layer fade in rather than switch on: at zero coverage the ranking is
+ * exactly the lexical arm (the floor a project starts from), and at full coverage the bonus is
+ * unchanged (the peak this repository measures). No threshold, because a threshold would create a
+ * cliff where authoring one more spec changes every ranking at once.
+ */
+function rankCoverageAware(issueText, scanned, specs, topN, weight, gateThreshold) {
+    const coverage = anchorCoverage(scanned, specs);
+    const withSpecs = rankWeighted(issueText, scanned, specs, scanned.length, weight, gateThreshold);
+    if (coverage >= 1)
+        return withSpecs.slice(0, topN);
+    const withoutSpecs = new Map(rankWeighted(issueText, scanned, [], scanned.length, weight, gateThreshold).map((h) => [h.file, h.score]));
+    // Interpolate between the two arms rather than rescaling the bonus in place: the spec layer also
+    // decides WHICH specs matched and which files were admitted, and a bonus-only adjustment would
+    // leave those effects at full strength while claiming to have damped them.
+    const merged = new Map();
+    for (const h of withSpecs) {
+        const lexical = withoutSpecs.get(h.file) ?? 0;
+        merged.set(h.file, lexical + (h.score - lexical) * coverage);
+    }
+    for (const [file, score] of withoutSpecs)
+        if (!merged.has(file))
+            merged.set(file, score);
+    return [...merged.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([file, score]) => ({ file, score }))
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * The gate, chosen by whether the request names a spec at all.
+ *
+ * No single threshold serves both conditions. Measured over 60 point-in-time cases (A-SPEC-369):
+ *
+ *   threshold 1 — cited Top-10 recall 0.770, uncited 0.275 (a no-graph baseline gets 0.357)
+ *   threshold 4 — cited 0.743 and Top-1 0.333 → 0.283, uncited 0.349
+ *
+ * Under a citation, the named spec locates the request in the corpus, and the specs that merely
+ * share vocabulary with it are corroborated rather than speculative — the permissive gate pays. With
+ * no citation, those same matches are twenty-six unanchored guesses per case whose bonuses bury the
+ * lexical signal, and the strict gate keeps them out.
+ *
+ * The condition is read from the request itself, and only a citation the store can RESOLVE counts:
+ * a stray `A-SPEC-999` in a bug report must not unlock the permissive path.
+ */
+function rankCitationConditioned(issueText, scanned, specs, topN, weight, citedThreshold, uncitedThreshold) {
+    const cited = (0, localize_1.citationsIn)(issueText, new Set(specs.map((s) => s.id))).cited.length > 0;
+    return rankWeighted(issueText, scanned, specs, topN, weight, cited ? citedThreshold : uncitedThreshold);
+}
+/**
+ * Drop the lexically-matched specs when too many of them match.
+ *
+ * Conditioning on whether the request cited a spec repaired this repository and cost the second
+ * corpus its lead, because that corpus cites nothing and would always take the strict path. Both
+ * measurements point at the same underlying quantity: HOW MANY specs the request matched. jarvis
+ * matches 0.87 per case, this repository 26.6 (A-SPEC-367).
+ *
+ * One matching spec is a claim about where the request belongs. Twenty-six matching specs is a fact
+ * about the request's vocabulary — it was written in words the corpus uses everywhere — and their
+ * bonuses, spread over a hundred anchored files, bury the lexical ranking that would otherwise work.
+ *
+ * A citation is never capped: it names something rather than resembling it, and it is the one signal
+ * in this scorer measured to carry the localization result.
+ */
+function rankCapped(issueText, scanned, specs, topN, weight, gateThreshold, maxMatchedSpecs) {
+    const known = new Set(specs.map((s) => s.id));
+    const cited = new Set((0, localize_1.citationsIn)(issueText, known).cited);
+    const lexical = matchedSpecsWeighted(issueText, specs, weight, gateThreshold)
+        .filter((id) => !cited.has(id));
+    if (lexical.length <= maxMatchedSpecs)
+        return rankWeighted(issueText, scanned, specs, topN, weight, gateThreshold);
+    // Over the cap: keep only the specs the request NAMED. Passing just those reproduces the citation
+    // path exactly, with no lexical spec matching left to admit anything else.
+    const citedSpecs = specs.filter((s) => cited.has(s.id));
+    return rankWeighted(issueText, scanned, citedSpecs, topN, weight, gateThreshold);
+}
+/**
+ * The cap, applied only to requests that named nothing.
+ *
+ * The two halves the measurements each found: a citation corroborates the specs that merely share
+ * vocabulary with the request, so with one present they help (dropping them cost Top-10 recall
+ * 0.770 → 0.743). Without one, a large number of matches is a fact about the request's wording
+ * rather than evidence, and their bonuses bury the lexical ranking (0.275 against a 0.357 baseline).
+ * A SMALL number of matches with no citation is still meaningful — that is the second corpus, at
+ * 0.87 matches per case, and capping it there threw away the modest lead it had.
+ *
+ * So: exempt cited requests, and cap only the uncited ones that matched more specs than a request
+ * can plausibly be about.
+ */
+function rankUncitedCapped(issueText, scanned, specs, topN, weight, gateThreshold, maxMatchedSpecs) {
+    const cited = (0, localize_1.citationsIn)(issueText, new Set(specs.map((s) => s.id))).cited.length > 0;
+    if (cited)
+        return rankWeighted(issueText, scanned, specs, topN, weight, gateThreshold);
+    return rankCapped(issueText, scanned, specs, topN, weight, gateThreshold, maxMatchedSpecs);
+}
+/**
+ * One `calls` hop out from the lexical hits, added at a discount.
+ *
+ * With no citation the spec layer is off and the ranking is exactly what grepping the request's
+ * words would produce. The call graph is the only structure left that could beat it, and A-SPEC-318
+ * measured the opportunity: 13 missed files one `calls` hop away, all 58 hop edges being calls, none
+ * imports or inherits. That was measured under cited requests, where the spec layer had already
+ * found most of the answer — uncited, the lexical hits are the only seed, so the hop has more to add.
+ *
+ * Half the seed's score, and never more: a callee is evidence about the seed's neighbourhood, not
+ * about itself. If a hop could outrank a direct hit, the ranking would be trading the answer for its
+ * surroundings, which is the failure the spec-graph expansion arm was rejected for.
+ */
+function rankWithCallHop(issueText, scanned, specs, topN, weight, gateThreshold, maxMatchedSpecs, 
+/** @implements A-SPEC-394 — use import edges to bind names the global map calls ambiguous. */
+importAware = false) {
+    const base = rankUncitedCapped(issueText, scanned, specs, scanned.length, weight, gateThreshold, maxMatchedSpecs);
+    if (base.length === 0)
+        return [];
+    // Symbol -> the file declaring it. A name declared in two files is ambiguous and is not followed:
+    // a wrong hop is a confident false positive, a missing one is a disclosed gap.
+    const declaredIn = new Map();
+    for (const f of scanned) {
+        for (const sym of f.symbols) {
+            const bare = sym.qualifiedName.includes('.')
+                ? sym.qualifiedName.slice(sym.qualifiedName.lastIndexOf('.') + 1) : sym.qualifiedName;
+            for (const key of new Set([sym.qualifiedName, bare])) {
+                declaredIn.set(key, declaredIn.has(key) && declaredIn.get(key) !== f.sourcePath ? null : f.sourcePath);
+            }
+        }
+    }
+    // @implements A-SPEC-394
+    // Per-file disambiguation from imports (A-SPEC-393). The global map above discards a name declared
+    // twice; here a file that imports exactly one of the declaring modules binds to that one. This is
+    // the SAME hop as before on a BETTER edge set — a re-test of a rejected mechanism under a changed
+    // premise, not a new mechanism.
+    const declaredEverywhere = new Map();
+    for (const f of scanned) {
+        for (const sym of f.symbols) {
+            const bare = sym.qualifiedName.includes('.')
+                ? sym.qualifiedName.slice(sym.qualifiedName.lastIndexOf('.') + 1) : sym.qualifiedName;
+            for (const key of new Set([sym.qualifiedName, bare])) {
+                (declaredEverywhere.get(key) ?? declaredEverywhere.set(key, new Set()).get(key)).add(f.sourcePath);
+            }
+        }
+    }
+    const knownPaths = new Set(scanned.map((f) => f.sourcePath));
+    const importsOf = new Map();
+    if (importAware) {
+        for (const f of scanned) {
+            const set = new Set();
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'imports')
+                    continue;
+                const target = (0, edge_quality_1.resolveImport)(f.sourcePath, e.to, knownPaths);
+                if (target)
+                    set.add(target);
+            }
+            importsOf.set(f.sourcePath, set);
+        }
+    }
+    const resolveFrom = (fromFile, name) => {
+        const direct = declaredIn.get(name);
+        if (direct)
+            return direct;
+        if (!importAware)
+            return null;
+        const all = declaredEverywhere.get(name);
+        if (!all || all.size < 2)
+            return null;
+        const imported = [...all].filter((t) => importsOf.get(fromFile)?.has(t));
+        return imported.length === 1 ? imported[0] : null;
+    };
+    const score = new Map(base.map((h) => [h.file, h.score]));
+    const byPath = new Map(scanned.map((f) => [f.sourcePath, f]));
+    for (const hit of base) {
+        const f = byPath.get(hit.file);
+        for (const e of f?.edges ?? []) {
+            if (e.rel !== 'calls')
+                continue;
+            const target = resolveFrom(hit.file, e.to);
+            if (!target || target === hit.file)
+                continue;
+            const bonus = hit.score / 2;
+            if ((score.get(target) ?? 0) < bonus)
+                score.set(target, bonus);
+        }
+    }
+    return [...score.entries()]
+        .filter(([, v]) => v > 0)
+        .map(([file, s]) => ({ file, score: s }))
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+function ablate(issueText, scanned, specs, topN, opts) {
+    const weights = opts.idf ? normalisedIdf(scanned) : null;
+    const weight = (t) => (weights ? (weights.get(t) ?? 1) : 1);
+    const hits = rankWeighted(issueText, scanned, opts.specBonus ? specs : [], scanned.length, weight, 1);
+    const adjusted = opts.vendorDemotion
+        ? hits
+        // The demotion is applied inside `rankWeighted`; undoing it is a doubling, which restores the
+        // pre-demotion score exactly because the demotion is a halving.
+        : hits.map((h) => ({ file: h.file, score: isVendorPath(h.file) ? h.score * 2 : h.score }));
+    return [...adjusted]
+        .sort((a, b) => (opts.vendorDemotion ? Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) : 0) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * @implements A-SPEC-396
+ * Limit how many files each matched spec may lift.
+ *
+ * The ablation isolated the cost: turning the spec bonus off restores the baseline exactly, so that
+ * layer buys Top-1 (0.244 → 0.267 here, 0.400 → 0.433 on jarvis) and sells precision (0.156 → 0.104).
+ *
+ * Three earlier attempts all changed WHICH specs are admitted — breadth damping, coverage scaling,
+ * a cap on matched specs — and all three were rejected. This changes something else: once a spec is
+ * admitted, every file anchoring it rises together, and that simultaneity is the shape of the
+ * precision loss. Ranking a spec's anchored files by their own lexical evidence and lifting only the
+ * strongest few keeps the top of the list while leaving the tail alone.
+ *
+ * The cost is explicit: a file with no lexical evidence can no longer be lifted by its spec alone,
+ * so the layer loses the files it uniquely contributed. Whether that trade is positive is the
+ * measurement, not the assumption.
+ */
+function rankSpecLiftLimited(issueText, scanned, specs, topN, weight, gateThreshold, liftPerSpec) {
+    const withSpecs = rankWeighted(issueText, scanned, specs, scanned.length, weight, gateThreshold);
+    const lexicalOnly = new Map(rankWeighted(issueText, scanned, [], scanned.length, weight, gateThreshold).map((h) => [h.file, h.score]));
+    const known = new Set(specs.map((s) => s.id));
+    const cited = new Set((0, localize_1.citationsIn)(issueText, known).cited);
+    const admitted = new Set([...cited, ...matchedSpecsWeighted(issueText, specs, weight, gateThreshold)]);
+    // For each admitted spec, keep only its strongest anchored files by LEXICAL score. Ties break on
+    // path so the choice is reproducible rather than dependent on scan order.
+    const allowed = new Set();
+    for (const id of admitted) {
+        const anchored = scanned
+            .filter((f) => (f.implementsSpecs ?? []).includes(id))
+            .map((f) => ({ file: f.sourcePath, lex: lexicalOnly.get(f.sourcePath) ?? 0 }))
+            .sort((a, b) => b.lex - a.lex || a.file.localeCompare(b.file))
+            .slice(0, Math.max(0, liftPerSpec));
+        for (const a of anchored)
+            allowed.add(a.file);
+    }
+    return withSpecs
+        .map((h) => ({ file: h.file, score: allowed.has(h.file) ? h.score : (lexicalOnly.get(h.file) ?? 0) }))
+        .filter((h) => h.score > 0)
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * @implements A-SPEC-397
+ * The spec bonus with its magnitude as a parameter.
+ *
+ * Four arms failed to recover the 0.052 of precision the layer costs, and each changed a different
+ * thing: which specs are admitted (breadth damping, coverage scaling, a cap on matches) and how far
+ * an admitted one reaches (the lift limit). Magnitude was never touched.
+ *
+ * The default is 4 per anchor against a lexical symbol hit worth 3 and a path hit worth 1, so a
+ * single matched spec outweighs a symbol match — a file whose only evidence is one anchor can
+ * outrank a file whose name actually contains the request's words. That is a plausible source of the
+ * tail pollution and it is the last untried one.
+ *
+ * Reducing it should cost Top-1 as it recovers precision, so both are reported: a setting that fixes
+ * one by destroying the other is not a fix.
+ */
+function rankWithBonusScale(issueText, scanned, specs, topN, weight, gateThreshold, bonusScale) {
+    const withSpecs = rankWeighted(issueText, scanned, specs, scanned.length, weight, gateThreshold);
+    if (bonusScale === 1)
+        return withSpecs.slice(0, topN);
+    const lexical = new Map(rankWeighted(issueText, scanned, [], scanned.length, weight, gateThreshold).map((h) => [h.file, h.score]));
+    // Scale only the spec-derived part: the difference between the two arms IS the bonus, so this
+    // needs no assumption about how the bonus was computed and cannot drift from it.
+    return withSpecs
+        .map((h) => {
+        const lex = lexical.get(h.file) ?? 0;
+        return { file: h.file, score: lex + (h.score - lex) * bonusScale };
+    })
+        .filter((h) => h.score > 0)
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}
+/**
+ * @implements A-SPEC-398
+ * The spec bonus may REORDER, but may not ADMIT.
+ *
+ * Five arms failed to recover the 0.052 of precision the spec layer costs, and counting the lists
+ * showed why none of them could: the baseline returns 7.09 files per case and the product returns
+ * 9.27, filling all ten slots in 36 of 45 cases against the baseline's 16. The layer is not ranking
+ * the same set differently — it is **adding about two files per case**, and those additions are
+ * mostly wrong. Every arm so far reordered or rescaled; none declined to add.
+ *
+ * So: a file with lexical evidence keeps its bonus and can move up. A file whose only evidence is an
+ * anchor does not enter the list at all.
+ *
+ * The cost is the one thing the spec layer uniquely did — reaching a file the request's words never
+ * touch. That is a real loss and the measurement has to weigh it, not assume it away.
+ */
+function rankSpecReorderOnly(issueText, scanned, specs, topN, weight, gateThreshold) {
+    const withSpecs = rankWeighted(issueText, scanned, specs, scanned.length, weight, gateThreshold);
+    const lexical = new Map(rankWeighted(issueText, scanned, [], scanned.length, weight, gateThreshold).map((h) => [h.file, h.score]));
+    return withSpecs
+        .filter((h) => (lexical.get(h.file) ?? 0) > 0) // admitted by words, reordered by specs
+        .sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file))
+        .slice(0, topN);
+}