@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/oracle-gap.d.ts

@@ -0,0 +1,32 @@
+import type { Spec } from '../spec/spec-parser';
+/**
+ * The distance between "a test file claims this requirement" and "a test checks it".
+ *
+ * Traceability here runs from an A-SPEC to a test FILE: an `@implements` anchor makes the link and
+ * the constitution gate enforces it. The anchor is a line at the top of a file, and it says nothing
+ * about whether any assertion inside that file examines the requirement. A suite can be green, the
+ * anchor present, the gate satisfied, and the criterion untested.
+ *
+ * What is countable without executing anything: whether the requirement's vocabulary appears in the
+ * NAMES of the tests that claim it. A test whose describe and it titles share no significant word
+ * with the spec does not even mention what it claims to verify.
+ *
+ * **This is a lower bound and not an oracle check.** Sharing words does not mean the assertion
+ * examines the requirement, and sharing none does not prove it fails to — a test named
+ * `returns 404 for unknown ids` may verify a requirement about error handling that uses none of
+ * those words. What the count measures is how much of the traceability claim rests on the anchor
+ * alone. Calling it anything stronger would repeat the mistake this repository has made before.
+ */
+export interface OracleGap {
+    /** A-SPECs with at least one anchored test file. */
+    claimed: number;
+    /** Of those, how many have NO test title sharing a significant term with the spec. */
+    titlesShareNothing: number;
+    /** Mean share of the spec's terms appearing in the titles of tests that claim it. */
+    meanTitleOverlap: number | null;
+    /** Specs whose anchored test files could not be read — unmeasured, not clean. */
+    unreadable: number;
+}
+/** Test titles in a file: the strings passed to describe/it/test. */
+export declare function testTitles(source: string): string[];
+export declare function oracleGap(specs: readonly Spec[], anchors: Readonly<Record<string, readonly string[]>>, root: string): OracleGap;

package/dist/holmes/review/oracle-gap.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testTitles = testTitles;
+exports.oracleGap = oracleGap;
+// @implements A-SPEC-391
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const localize_1 = require("../rtm/localize");
+/** Test titles in a file: the strings passed to describe/it/test. */
+function testTitles(source) {
+    const out = [];
+    const re = /\b(?:describe|it|test)\s*(?:\.\w+)?\s*\(\s*(['"`])((?:\\.|(?!\1)[\s\S])*)\1/g;
+    let m;
+    while ((m = re.exec(source)) !== null)
+        out.push(m[2]);
+    return out;
+}
+function oracleGap(specs, anchors, root) {
+    const filesBySpec = new Map();
+    for (const [file, ids] of Object.entries(anchors)) {
+        for (const id of ids)
+            (filesBySpec.get(id) ?? filesBySpec.set(id, []).get(id)).push(file);
+    }
+    let claimed = 0, shareNothing = 0, unreadable = 0, overlapSum = 0, overlapCount = 0;
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const files = filesBySpec.get(s.id);
+        if (!files || files.length === 0)
+            continue;
+        claimed++;
+        const specTerms = new Set((0, localize_1.significantTerms)(`${s.title} ${Object.values(s.sections).join(' ')}`));
+        if (specTerms.size === 0)
+            continue;
+        const titleTerms = new Set();
+        let read = 0;
+        for (const file of files) {
+            let source;
+            try {
+                source = fs.readFileSync(path.join(root, file), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            read++;
+            for (const title of testTitles(source))
+                for (const t of (0, localize_1.significantTerms)(title))
+                    titleTerms.add(t);
+        }
+        if (read === 0) {
+            unreadable++;
+            continue;
+        }
+        let shared = 0;
+        for (const t of specTerms)
+            if (titleTerms.has(t))
+                shared++;
+        if (shared === 0)
+            shareNothing++;
+        overlapSum += shared / specTerms.size;
+        overlapCount++;
+    }
+    return {
+        claimed,
+        titlesShareNothing: shareNothing,
+        meanTitleOverlap: overlapCount === 0 ? null : overlapSum / overlapCount,
+        unreadable,
+    };
+}

package/dist/holmes/review/point-in-time-replay.d.ts

@@ -0,0 +1,41 @@
+export type Materialized = {
+    ok: true;
+    files: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export interface Fidelity {
+    /** Files whose materialized bytes were compared against the commit's blob. */
+    checked: number;
+    /** Repo-relative paths whose bytes differ from the commit. Empty means the tree is faithful. */
+    mismatches: string[];
+}
+/**
+ * @implements A-SPEC-315
+ * Every failure carries a CLASSIFICATION prefix — `unsafe-pathspec`, `destination-not-empty`,
+ * `git-ls-tree-failed`, `empty-pathspec`, `archive-or-extract-failed` — followed by the original
+ * detail. Two full-suite runs went red here in two different tests and both reported only `false`;
+ * isolation, two clean full runs and a 320-call concurrency probe all passed, so the cause is still
+ * unknown. Deliberately NO retry: a retry would hide whatever is actually happening.
+ *
+ * Lay out the tree a commit recorded, WITHOUT touching the working tree or index.
+ *
+ * `git archive` reads straight from the object database, so no checkout, stash or index write is
+ * involved — the caller's uncommitted work is untouched, which is the property this whole slice
+ * exists to obtain. The alternative (checkout into the same worktree) would destroy user state.
+ */
+export declare function materializeTreeAt(repoRoot: string, commitish: string, pathspec: string, destDir: string, opts?: {
+    /**
+     * @implements A-SPEC-303
+     * Permit a second pathspec from the SAME commit into the same destination — a project is its
+     * code AND its specs, and one scan should see both as they were. Opt-in on purpose: making it
+     * the default would quietly restore the mixed-tree hazard the emptiness rule exists to prevent.
+     */
+    allowNonEmpty?: boolean;
+}): Materialized;
+/**
+ * Confirm the materialized tree really is that commit. The leak this slice removes is invisible by
+ * construction, so it must be asserted rather than assumed: a wrong tree still produces numbers.
+ */
+export declare function verifyTreeFidelity(repoRoot: string, commitish: string, pathspec: string, destDir: string): Fidelity;

package/dist/holmes/review/point-in-time-replay.js

@@ -0,0 +1,161 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeTreeAt = materializeTreeAt;
+exports.verifyTreeFidelity = verifyTreeFidelity;
+// @implements A-SPEC-297
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * A pathspec is ours to control, but a caller mistake here writes outside the destination, so it is
+ * checked rather than trusted: repo-relative, no escape, no absolute root.
+ */
+function pathspecIsSafe(pathspec) {
+    if (pathspec === '' || path.isAbsolute(pathspec))
+        return false;
+    const normalized = path.normalize(pathspec);
+    return !normalized.startsWith('..') && !normalized.split(path.sep).includes('..');
+}
+function git(repoRoot, args) {
+    return (0, node_child_process_1.execFileSync)('git', ['-C', repoRoot, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+/** `path mode sha` triples the commit records for the pathspec, keyed by repo-relative path. */
+function blobsAt(repoRoot, commitish, pathspec) {
+    const out = git(repoRoot, ['ls-tree', '-r', `${commitish}^{tree}`, '--', pathspec]);
+    const blobs = new Map();
+    for (const line of out.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const [meta, file] = line.split('\t');
+        const parts = meta.split(/\s+/);
+        if (parts[1] !== 'blob')
+            continue; // submodules and trees are not files we can compare
+        blobs.set(file, parts[2]);
+    }
+    return blobs;
+}
+/**
+ * @implements A-SPEC-315
+ * Every failure carries a CLASSIFICATION prefix — `unsafe-pathspec`, `destination-not-empty`,
+ * `git-ls-tree-failed`, `empty-pathspec`, `archive-or-extract-failed` — followed by the original
+ * detail. Two full-suite runs went red here in two different tests and both reported only `false`;
+ * isolation, two clean full runs and a 320-call concurrency probe all passed, so the cause is still
+ * unknown. Deliberately NO retry: a retry would hide whatever is actually happening.
+ *
+ * Lay out the tree a commit recorded, WITHOUT touching the working tree or index.
+ *
+ * `git archive` reads straight from the object database, so no checkout, stash or index write is
+ * involved — the caller's uncommitted work is untouched, which is the property this whole slice
+ * exists to obtain. The alternative (checkout into the same worktree) would destroy user state.
+ */
+function materializeTreeAt(repoRoot, commitish, pathspec, destDir, opts) {
+    if (!pathspecIsSafe(pathspec))
+        return { ok: false, reason: `unsafe-pathspec: ${pathspec}` };
+    if (!opts?.allowNonEmpty && fs.existsSync(destDir) && fs.readdirSync(destDir).length > 0) {
+        // Extracting over existing files yields a tree that is partly one commit and partly another —
+        // and it would still score, silently and wrongly.
+        return { ok: false, reason: `destination-not-empty: destination is not empty: ${destDir}` };
+    }
+    fs.mkdirSync(destDir, { recursive: true });
+    let blobs;
+    try {
+        blobs = blobsAt(repoRoot, commitish, pathspec);
+    }
+    catch (err) {
+        // The original message is kept, not replaced: a classification that DISCARDS the detail makes
+        // diagnosis worse, not better.
+        return { ok: false, reason: `git-ls-tree-failed: unknown or unreadable commit-ish ${commitish}: ${err.message}` };
+    }
+    if (blobs.size === 0) {
+        // Zero files is not a score of zero. Nothing was measured.
+        return { ok: false, reason: `empty-pathspec: no files at ${commitish} for pathspec ${pathspec}` };
+    }
+    // @implements A-SPEC-329
+    // The tar goes through a FILE, not through tar's stdin. Feeding a multi-megabyte buffer to
+    // `execFileSync('tar', …, { input })` failed intermittently under full-suite load with
+    // `spawnSync tar EPIPE` — observed three times, and only nameable because A-SPEC-315 had added
+    // failure classifications instead of the retry that would have hidden it. A retry would have
+    // masked a fixable bug; removing the pipe removes the failure mode rather than surviving it.
+    //
+    // The scratch file lives OUTSIDE the destination: inside, it would mix with the extracted tree and
+    // the fidelity check would see a file the commit never had.
+    const tarPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'pit-tar-')), 'tree.tar');
+    try {
+        const tar = (0, node_child_process_1.execFileSync)('git', ['-C', repoRoot, 'archive', '--format=tar', commitish, '--', pathspec], { maxBuffer: 512 * 1024 * 1024 });
+        fs.writeFileSync(tarPath, tar);
+        (0, node_child_process_1.execFileSync)('tar', ['-x', '-C', destDir, '-f', tarPath], { maxBuffer: 512 * 1024 * 1024 });
+    }
+    catch (err) {
+        return { ok: false, reason: `archive-or-extract-failed: could not materialize ${commitish}: ${err.message}` };
+    }
+    finally {
+        // Removed on every path — a scratch file that survives a failure is litter in the temp dir.
+        fs.rmSync(path.dirname(tarPath), { recursive: true, force: true });
+    }
+    return { ok: true, files: [...blobs.keys()].sort() };
+}
+/** Git's blob id: sha1 over `blob <byteLength>\0` followed by the content. */
+function blobId(content) {
+    return crypto.createHash('sha1').update(`blob ${content.length}\0`).update(content).digest('hex');
+}
+/**
+ * Confirm the materialized tree really is that commit. The leak this slice removes is invisible by
+ * construction, so it must be asserted rather than assumed: a wrong tree still produces numbers.
+ */
+function verifyTreeFidelity(repoRoot, commitish, pathspec, destDir) {
+    let blobs;
+    try {
+        blobs = blobsAt(repoRoot, commitish, pathspec);
+    }
+    catch {
+        return { checked: 0, mismatches: [`<unreadable commit-ish: ${commitish}>`] };
+    }
+    const mismatches = [];
+    let checked = 0;
+    for (const [file, expected] of blobs) {
+        const onDisk = path.join(destDir, file);
+        checked++;
+        if (!fs.existsSync(onDisk)) {
+            mismatches.push(file);
+            continue;
+        }
+        if (blobId(fs.readFileSync(onDisk)) !== expected)
+            mismatches.push(file);
+    }
+    return { checked, mismatches: mismatches.sort() };
+}

package/dist/holmes/review/rank-diagnosis.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Why the shipped harness lost on recall (S-404), decomposed.
+ *
+ * "Recall is low" has two completely different causes and they call for opposite fixes: either the
+ * answer never became a candidate (admission — widen the pool, add a retrieval channel), or it was
+ * a candidate and something else outranked it (ordering — change the scoring, and widening the pool
+ * does nothing). Thirteen rejected retrieval mechanisms were all attempts at the first one. This
+ * module measures which it actually is, so the next attempt is aimed at the measured cause.
+ *
+ * On the eight blind jarvis cases of A-SPEC-404 the answer is unambiguous, and it is the second:
+ * every truth file was already in the pool.
+ */
+export interface PooledTruth {
+    file: string;
+    /** Position in the full candidate pool, best first. `-1` when the file never entered it. */
+    rank: number;
+    /** Lexical/spec score before the history re-rank. Zero means only commit history reached it. */
+    lexical: number;
+}
+export interface RankDiagnosis {
+    truthTotal: number;
+    /** Answers the pipeline never proposed at any depth — the admission failure. */
+    notInPool: number;
+    /** Answers that landed inside the reported cut. */
+    insideCut: number;
+    /** Answers present in the pool but ranked past the cut — the ordering failure. */
+    pooledBelowCut: number;
+    /** Pooled answers the lexical/spec layer scored at zero (reached only through commit history). */
+    pooledWithZeroLexical: number;
+    /** Recall the cut could reach if ordering were perfect. 1 means ranking is the only obstacle. */
+    cutRecallCeiling: number;
+}
+export declare function diagnoseRanking(cases: ReadonlyArray<{
+    truth: readonly PooledTruth[];
+}>, cut: number): RankDiagnosis;
+/**
+ * Measured 2026-08-29 on the eight A-SPEC-404 blind jarvis cases, through the shipped pipeline
+ * (localizeIssue at pool 500, then the recency x commit-text re-rank of A-SPEC-378/388).
+ */
+export declare const S405_POOLED_TRUTH: ReadonlyArray<{
+    truth: readonly PooledTruth[];
+}>;
+export declare const S405_DIAGNOSIS: RankDiagnosis;

package/dist/holmes/review/rank-diagnosis.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S405_DIAGNOSIS = exports.S405_POOLED_TRUTH = void 0;
+exports.diagnoseRanking = diagnoseRanking;
+function diagnoseRanking(cases, cut) {
+    let truthTotal = 0;
+    let notInPool = 0;
+    let insideCut = 0;
+    let pooledBelowCut = 0;
+    let pooledWithZeroLexical = 0;
+    for (const c of cases) {
+        for (const t of c.truth) {
+            truthTotal += 1;
+            if (t.rank < 0) {
+                notInPool += 1;
+                continue;
+            }
+            if (t.rank < cut)
+                insideCut += 1;
+            else
+                pooledBelowCut += 1;
+            if (t.lexical === 0)
+                pooledWithZeroLexical += 1;
+        }
+    }
+    return {
+        truthTotal,
+        notInPool,
+        insideCut,
+        pooledBelowCut,
+        pooledWithZeroLexical,
+        cutRecallCeiling: truthTotal === 0 ? 0 : (truthTotal - notInPool) / truthTotal,
+    };
+}
+/**
+ * Measured 2026-08-29 on the eight A-SPEC-404 blind jarvis cases, through the shipped pipeline
+ * (localizeIssue at pool 500, then the recency x commit-text re-rank of A-SPEC-378/388).
+ */
+exports.S405_POOLED_TRUTH = [
+    {
+        "truth": [
+            {
+                "file": "src/gateway/handlers.py",
+                "rank": 6,
+                "lexical": 0
+            },
+            {
+                "file": "src/gateway/persona.py",
+                "rank": 87,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/structured_logger.py",
+                "rank": 93,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/gateway/self_review.py",
+                "rank": 27,
+                "lexical": 0
+            },
+            {
+                "file": "src/llm_providers/base_cli.py",
+                "rank": 2,
+                "lexical": 32.271010116342076
+            },
+            {
+                "file": "src/llm_providers/claude_cli.py",
+                "rank": 0,
+                "lexical": 40.47872273076396
+            },
+            {
+                "file": "src/main.py",
+                "rank": 6,
+                "lexical": 8.415456200622677
+            },
+            {
+                "file": "src/web_server.py",
+                "rank": 44,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/llm_providers/base_cli.py",
+                "rank": 14,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/gateway/hardening_apply.py",
+                "rank": 24,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/core/memory_audit.py",
+                "rank": 12,
+                "lexical": 0
+            },
+            {
+                "file": "src/core/profile.py",
+                "rank": 2,
+                "lexical": 0
+            },
+            {
+                "file": "src/proactive.py",
+                "rank": 0,
+                "lexical": 139.77894930506255
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/core/memory_gate.py",
+                "rank": 7,
+                "lexical": 0.7049978210990919
+            },
+            {
+                "file": "src/graph_memory.py",
+                "rank": 0,
+                "lexical": 57.809821330125516
+            },
+            {
+                "file": "src/knowledge_distiller.py",
+                "rank": 6,
+                "lexical": 0
+            }
+        ]
+    },
+    {
+        "truth": [
+            {
+                "file": "src/tools/capabilities.py",
+                "rank": 7,
+                "lexical": 0
+            },
+            {
+                "file": "src/tools/changelog.py",
+                "rank": 8,
+                "lexical": 0
+            }
+        ]
+    }
+];
+exports.S405_DIAGNOSIS = diagnoseRanking(exports.S405_POOLED_TRUTH, 10);

package/dist/holmes/review/replay-calibration.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Does the confidence number mean anything?
+ *
+ * Goal Phase D asks for the closed loop, and the mechanism has been verified for a while — what is
+ * missing is data (`.ax/evidence` is n=0). Filling that directory with synthetic records would be
+ * worse than leaving it empty: it is a user-visible governance ledger the user deliberately chose
+ * not to git-ignore, and calibration computed from replay would read as calibration observed in use.
+ * So this measures in a temporary ledger and says plainly what it measured.
+ *
+ * The question it CAN answer honestly is not the one `computeCalibration` scores. That function
+ * grades classification correctness, and point-in-time replay carries no ground truth for "new
+ * requirement vs change to an existing one" — inventing that label would be scoring our own guess
+ * against our own guess. What replay does carry is the files the commit actually touched, so the
+ * answerable question is whether a HIGHER confidence goes with a MORE accurate answer.
+ *
+ * The prior is not neutral. The confidence formula is
+ * `0.55 + 0.15·(direct symbols exist) + 0.15·(tests found) + 0.1·(history found)` — it counts
+ * whether evidence is PRESENT, never whether it is any good. A number built that way can be
+ * expected to correlate weakly with accuracy, and if it does, saying so is the finding: a confidence
+ * that does not track correctness sells unearned certainty to whoever reads it.
+ */
+export interface ConfidenceObservation {
+    confidence: number;
+    /** Per-case recall of the ranked answer against what the commit really changed. */
+    accuracy: number;
+}
+export interface ConfidenceCalibration {
+    n: number;
+    /** Pearson correlation between confidence and accuracy; null when confidence never varies. */
+    correlation: number | null;
+    /** Distinct confidence values observed — a formula that emits one value cannot rank anything. */
+    distinctConfidences: number;
+    /** Mean accuracy among the cases at or above the median confidence, and below it. */
+    meanAccuracyHigh: number | null;
+    meanAccuracyLow: number | null;
+    /** Brier-style mean squared gap between the promise and the delivery. */
+    meanSquaredGap: number | null;
+}
+export declare function confidenceCalibration(obs: readonly ConfidenceObservation[]): ConfidenceCalibration;
+/**
+ * @implements A-SPEC-359
+ * Does ANY quantity the analysis already computes predict how accurate it will be?
+ *
+ * The confidence field does not (A-SPEC-357: correlation -0.062, and the confident cases were
+ * marginally *less* accurate than the ambiguous ones). Before proposing a better formula, the honest
+ * step is to find out whether a better formula is possible at all with the signals to hand — a
+ * search that can come back empty, and an empty result is publishable.
+ *
+ * A signal counts only when both corpora agree on its SIGN. A correlation seen in one repository can
+ * be a property of that repository, which this work has now been caught by twice.
+ */
+export interface SignalCorrelation {
+    signal: string;
+    correlation: number | null;
+    n: number;
+}
+export declare function correlate(pairs: readonly {
+    x: number;
+    y: number;
+}[]): number | null;
+/** Signals that agree in sign across corpora AND clear the threshold in both. */
+export declare function agreeingSignals(a: readonly SignalCorrelation[], b: readonly SignalCorrelation[], threshold: number): string[];