@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/review/test-outcomes.js

@@ -40,7 +40,9 @@ exports.appendOutcomes = appendOutcomes;
 exports.readOutcomes = readOutcomes;
 exports.buildOutcomeRecords = buildOutcomeRecords;
 exports.groupOutcomesByAspec = groupOutcomesByAspec;
-// @implements A-SPEC-534.3
+// @implements A-SPEC-534.3, A-SPEC-625
+// @implements A-SPEC-645
+const execution_context_1 = require("../project/execution-context");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const replica_id_1 = require("../governance/replica-id");
@@ -66,9 +68,16 @@ function isOutcomesFilename(name) {
  */
 function appendOutcomes(root, records) {
     try {
-        const file = path.join(root, '.ax', 'ledger', outcomesFilename((0, replica_id_1.resolveReplicaId)(root)));
+        const prepared = records.map(r => {
+            const execution = (0, execution_context_1.observationExecution)(root, r);
+            return execution ? { ...r, execution } : r;
+        });
+        const attributed = prepared.find(r => r.execution)?.execution;
+        if (attributed && prepared.some(r => !r.execution || r.execution.replicaId !== attributed.replicaId))
+            return false;
+        const file = path.join(root, '.ax', 'ledger', outcomesFilename(attributed?.replicaId ?? (0, replica_id_1.resolveReplicaId)(root)));
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.appendFileSync(file, records.map((r) => `${JSON.stringify(r)}\n`).join(''));
+        fs.appendFileSync(file, prepared.map((r) => `${JSON.stringify(r)}\n`).join(''));
         return true;
     }
     catch {
@@ -110,6 +119,11 @@ function readOutcomes(root) {
                 const r = JSON.parse(s);
                 if (r && typeof r === 'object' && typeof r.aspec === 'string' && typeof r.outcome === 'string'
                     && typeof r.ts === 'string' && typeof r.head === 'string') {
+                    if ('execution' in r) {
+                        r.execution = (0, execution_context_1.validateExecution)(r.execution);
+                        if (name !== outcomesFilename(r.execution.replicaId))
+                            continue;
+                    }
                     out.push({ r: r, i: i++ });
                 }
             }
@@ -136,12 +150,16 @@ function buildOutcomeRecords(outcomeByFile, anchors, head, ts) {
  * Group outcomes by A-SPEC, keeping only records stamped with the given baseline `head` — a stale
  * record from another commit cannot vouch for the current work (the isFresh discipline). Pure.
  */
-function groupOutcomesByAspec(records, head) {
+function groupOutcomesByAspec(records, head, 
+/** @implements A-SPEC-645 — maps a record's display id to the id the entity carries now (from the ledger's renames). */
+canonical) {
     const out = {};
     for (const r of records) {
         if (r.head !== head)
             continue;
-        (out[r.aspec] ??= []).push({ outcome: r.outcome, ts: r.ts });
+        const execution = 'execution' in r ? (0, execution_context_1.validateExecution)(r.execution) : undefined;
+        const key = canonical ? canonical(r.aspec) : r.aspec; // A-SPEC-645 — evidence follows the entity
+        (out[key] ??= []).push({ outcome: r.outcome, ts: r.ts, ...(execution ? { execution } : {}) });
     }
     return out;
 }

package/dist/holmes/review/test-runner.d.ts

@@ -106,10 +106,28 @@ export declare function jestEntry(cwd: string): string | null;
  */
 export declare function runJestOutcomes(files: string[], cwd: string): Record<string, TestOutcome>;
 /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
+/**
+ * @implements A-SPEC-647
+ * Per-file RED-first outcome from the same JUnit XML `parseJUnitXmlCounts` reads. Measured 2026-09-14
+ * in an external pytest project: a ranged test_run executed the anchored case and recorded NOTHING,
+ * because classification was jest-only — a Python project could never produce the red-assertion→green
+ * sequence ART-8 reads. `<error>` (collection/import/setup) is a red-error, `<failure>` (an assertion)
+ * a red-assertion, executed cases without either are green; a file with only skipped cases says nothing.
+ */
+export declare function parseJUnitXmlOutcomes(xml: string, ext?: string): Record<string, TestOutcome>;
+/**
+ * @implements A-SPEC-647
+ * The ecosystems a project's OWN test files belong to, by file-name convention, under a bounded walk
+ * that skips vendored trees and virtualenvs. Measured: a full-tier run with no impacted list assumed
+ * the jest suite on a pytest-only project, ran nothing and reported passed:false. This repository's
+ * Python tests live under `reference/`, so it detects jest only and its runs are unchanged.
+ */
+export declare function detectProjectEcosystems(cwd: string): Ecosystem[];
 export declare function runPytest(files: string[], mode: TestRunPlan['mode'], cwd: string): {
     passed: boolean;
     tail: string;
     executed: Record<string, number>;
+    outcomes: Record<string, TestOutcome>;
 };
 /**
  * @implements A-SPEC-137.2

package/dist/holmes/review/test-runner.js

@@ -42,6 +42,8 @@ exports.classifyJestOutcomes = classifyJestOutcomes;
 exports.parseJUnitXmlCounts = parseJUnitXmlCounts;
 exports.jestEntry = jestEntry;
 exports.runJestOutcomes = runJestOutcomes;
+exports.parseJUnitXmlOutcomes = parseJUnitXmlOutcomes;
+exports.detectProjectEcosystems = detectProjectEcosystems;
 exports.runPytest = runPytest;
 exports.parseCargoTest = parseCargoTest;
 exports.runCargo = runCargo;
@@ -53,6 +55,7 @@ exports.tailOf = tailOf;
 exports.failedTestSummary = failedTestSummary;
 exports.summarizeJestJson = summarizeJestJson;
 // @implements A-SPEC-102.1
+// @implements A-SPEC-647
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -325,6 +328,105 @@ function runJestOutcomes(files, cwd) {
 }
 /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
 // @implements A-SPEC-502.1 — exported for the wiring test (a fake venv python capturing argv).
+/**
+ * @implements A-SPEC-647
+ * Per-file RED-first outcome from the same JUnit XML `parseJUnitXmlCounts` reads. Measured 2026-09-14
+ * in an external pytest project: a ranged test_run executed the anchored case and recorded NOTHING,
+ * because classification was jest-only — a Python project could never produce the red-assertion→green
+ * sequence ART-8 reads. `<error>` (collection/import/setup) is a red-error, `<failure>` (an assertion)
+ * a red-assertion, executed cases without either are green; a file with only skipped cases says nothing.
+ */
+function parseJUnitXmlOutcomes(xml, ext = 'py') {
+    const flags = new Map();
+    for (const m of xml.matchAll(/<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g)) {
+        const attrs = m[1] ?? '';
+        const body = m[3] ?? '';
+        let file = /\bfile="([^"]*)"/.exec(attrs)?.[1];
+        if (!file) {
+            const cls = /\bclassname="([^"]*)"/.exec(attrs)?.[1];
+            if (!cls)
+                continue;
+            const parts = cls.split('.').filter(Boolean);
+            if (ext === 'py') {
+                while (parts.length > 1 && /^[A-Z]/.test(parts[parts.length - 1]))
+                    parts.pop();
+            }
+            if (parts.length === 0)
+                continue;
+            file = `${parts.join('/')}.${ext}`;
+        }
+        const key = file.split('\\').join('/');
+        const f = flags.get(key) ?? { error: false, failure: false, executed: false };
+        if (/<error\b/.test(body))
+            f.error = true;
+        else if (/<failure\b/.test(body))
+            f.failure = true;
+        if (!/<skipped\b/.test(body))
+            f.executed = true;
+        flags.set(key, f);
+    }
+    const out = {};
+    for (const [file, f] of flags) {
+        if (f.error)
+            out[file] = 'red-error';
+        else if (f.failure)
+            out[file] = 'red-assertion';
+        else if (f.executed)
+            out[file] = 'green';
+    }
+    return out;
+}
+/**
+ * @implements A-SPEC-647
+ * The ecosystems a project's OWN test files belong to, by file-name convention, under a bounded walk
+ * that skips vendored trees and virtualenvs. Measured: a full-tier run with no impacted list assumed
+ * the jest suite on a pytest-only project, ran nothing and reported passed:false. This repository's
+ * Python tests live under `reference/`, so it detects jest only and its runs are unchanged.
+ */
+function detectProjectEcosystems(cwd) {
+    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'dist-tools', 'build', 'vendor', 'third_party', 'reference']);
+    const found = new Set();
+    const walk = (dir, depth) => {
+        if (depth > 6)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (entries.some((e) => e.isFile() && e.name === 'pyvenv.cfg'))
+            return; // a virtualenv is not the project
+        for (const e of entries) {
+            const name = e.name;
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(name) || (name.startsWith('.') && name !== '.'))
+                    continue;
+                if (name === '__tests__')
+                    found.add('jest');
+                walk(path.join(dir, name), depth + 1);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            if (/\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/.test(name))
+                found.add('jest');
+            else if (/^(test_[^/]*|[^/]*_test)\.py$/.test(name) || name === 'conftest.py')
+                found.add('pytest');
+            else if (/_test\.go$/.test(name))
+                found.add('go');
+            else if (name === 'Cargo.toml')
+                found.add('rust');
+            else if (name === 'build.gradle' || name === 'build.gradle.kts')
+                found.add('java');
+            else if (/\.csproj$/.test(name))
+                found.add('dotnet');
+        }
+    };
+    walk(cwd, 0);
+    return [...found].sort();
+}
 function runPytest(files, mode, cwd) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-pytest-'));
     const report = path.join(dir, 'report.xml');
@@ -351,14 +453,35 @@ function runPytest(files, mode, cwd) {
             return {};
         }
     };
+    // @implements A-SPEC-647 — per-file outcomes from the same report; in a scoped run a planned file the
+    // failed run never reached (no case at all — a collection error before its cases) is a red-error, so a
+    // RED that never ran is not mistaken for evidence of nothing.
+    const readOutcomes = (passed) => {
+        let outcomes = {};
+        try {
+            outcomes = parseJUnitXmlOutcomes(fs.readFileSync(report, 'utf8'));
+        }
+        catch {
+            outcomes = {};
+        }
+        if (mode === 'scoped' && !passed) {
+            for (const f of files) {
+                const key = f.split('\\').join('/');
+                if (path.basename(key) === 'conftest.py' || outcomes[key])
+                    continue;
+                outcomes[key] = 'red-error';
+            }
+        }
+        return outcomes;
+    };
     try {
         const out = (0, node_child_process_1.execFileSync)(python, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: RUNNER_MAX_BUFFER, env: (0, root_1.cleanTestEnv)() });
-        return { passed: true, tail: tailOf(out), executed: read() };
+        return { passed: true, tail: tailOf(out), executed: read(), outcomes: readOutcomes(true) };
     }
     catch (e) {
         const err = e;
         // A red pytest run still writes the XML, so execution evidence survives — same property as jest.
-        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: read() };
+        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: read(), outcomes: readOutcomes(false) };
     }
     finally {
         try {
@@ -650,8 +773,13 @@ function runTestScope(scope, cwd) {
     // to a caller that only sees passed=true.
     let assumedJest = false;
     if (plan.mode === 'full' && groups.size === 0) {
-        groups.set('jest', []);
-        assumedJest = true;
+        // @implements A-SPEC-647 — run what the project HAS; assume jest only when nothing is detected.
+        for (const eco of detectProjectEcosystems(cwd))
+            groups.set(eco, []);
+        if (groups.size === 0) {
+            groups.set('jest', []);
+            assumedJest = true;
+        }
     }
     if (groups.size > 0) {
         const runners = { jest: runJest, pytest: runPytest, go: runGo, rust: runCargo, java: runGradle, dotnet: runDotnet };

package/dist/holmes/rtm/graph-store.d.ts

@@ -42,6 +42,23 @@ export interface OpenedGraph {
     reason: string | null;
     /** Record the basis for this graph's CURRENT contents. Call after building. */
     commitBasis(): void;
+    /**
+     * @implements A-SPEC-631 — finish with the graph. In `publishable` mode a non-reusable graph
+     * lives in a private temporary database: `publish()` closes it and replaces the live file by one
+     * atomic rename; `discard()` closes it and removes the temporary file. In the default in-place
+     * mode both simply close the handle. Exactly one of them is called, exactly once.
+     */
+    publish(): void;
+    discard(): void;
+}
+export interface ReuseOptions {
+    /**
+     * @implements A-SPEC-631 — never touch the live file: when the stored graph cannot be reused,
+     * hand back an EMPTY graph in a private temporary database beside it instead of clearing the live
+     * file in place (which let concurrent readers see zero nodes and a killed rebuild leave an empty,
+     * basis-less file). The caller builds into it, `commitBasis()`, then `publish()`.
+     */
+    publishable?: boolean;
 }
 /**
  * Open the graph at `dbPath`, reusing its contents only if `expected` still holds.
@@ -50,4 +67,36 @@ export interface OpenedGraph {
  * to fail: the caller always receives a usable graph, empty when the stored one could not be
  * trusted, so "the cache is broken" degrades to "this call is slower" rather than to an outage.
  */
-export declare function openReusableGraph(dbPath: string, expected: GraphBasis): OpenedGraph;
+export declare function openReusableGraph(dbPath: string, expected: GraphBasis, opts?: ReuseOptions): OpenedGraph;
+/** Age after which a `.tmp-*` / `.bak-*` sibling of the live graph is treated as abandoned by a dead publisher. */
+export declare const GRAPH_STALE_MS: number;
+export type PublishedGraph = {
+    status: 'absent' | 'unreadable' | 'empty';
+    graph: null;
+    graphAsOf?: string;
+} | {
+    status: 'current' | 'stale' | 'unverified';
+    graph: RtmGraph;
+    sourceCommit: string | null;
+    head: string | null;
+    graphAsOf?: string;
+};
+/**
+ * Build a complete graph in a private temporary database, commit `basis`, close it, and replace
+ * the live file atomically. The live file is never opened for writing and never cleared; a build
+ * that throws leaves it untouched and removes the temporary file. Returns the published counts.
+ */
+export declare function publishGraph(livePath: string, basis: GraphBasis, build: (graph: RtmGraph) => void): {
+    nodes: number;
+    edges: number;
+};
+/**
+ * Open the live graph WITHOUT mutating it and say what it is: absent, unreadable (open or metadata
+ * failed — the file is left for the next publication to replace, never deleted here), empty (a
+ * schema with no nodes — the state an interrupted in-place rebuild used to leave behind), or a
+ * served graph whose basis commit is current / stale against `head`, or unverified when either side
+ * is unknown. Served statuses return an OPEN handle the caller must close.
+ */
+export declare function openPublishedGraph(livePath: string, head: string | null): PublishedGraph;
+/** HEAD of the repository at `root`, or null outside Git — the only freshness input a consumer pays for (no scan). */
+export declare function headCommitOf(root: string, env?: NodeJS.ProcessEnv): string | null;

package/dist/holmes/rtm/graph-store.js

@@ -33,13 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRAPH_STALE_MS = void 0;
 exports.specFingerprint = specFingerprint;
 exports.scanDigest = scanDigest;
 exports.openReusableGraph = openReusableGraph;
+exports.publishGraph = publishGraph;
+exports.openPublishedGraph = openPublishedGraph;
+exports.headCommitOf = headCommitOf;
 // @implements A-SPEC-282
+// @implements A-SPEC-631
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
 const rtm_graph_1 = require("./rtm-graph");
 const BASIS_FIELDS = [
     'graphSchema', 'extractorVersion', 'sourceCommit', 'specFingerprint', 'scanDigest',
@@ -88,8 +94,10 @@ function readStoredBasis(graph) {
  * to fail: the caller always receives a usable graph, empty when the stored one could not be
  * trusted, so "the cache is broken" degrades to "this call is slower" rather than to an outage.
  */
-function openReusableGraph(dbPath, expected) {
+function openReusableGraph(dbPath, expected, opts = {}) {
     fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    if (opts.publishable)
+        return openPublishable(dbPath, expected);
     let graph;
     let reason = null;
     try {
@@ -126,11 +134,244 @@ function openReusableGraph(dbPath, expected) {
     const commitBasis = () => {
         graph.writeMeta(Object.fromEntries(BASIS_FIELDS.map((f) => [f, expected[f]])));
     };
+    const finish = () => graph.close();
     if (reason) {
         // Not reusable means EMPTY. Handing back a partially-stale graph would be worse than no cache:
         // the caller would build on top of facts whose basis it has just been told it cannot trust.
         graph.clear();
-        return { graph, reusable: false, reason, commitBasis };
+        return { graph, reusable: false, reason, commitBasis, publish: finish, discard: finish };
+    }
+    return { graph, reusable: true, reason: null, commitBasis, publish: finish, discard: finish };
+}
+// ---------------------------------------------------------------------------------------------
+// @implements A-SPEC-631 — publication and inspection of the LIVE graph.
+//
+// Before this, rtm_impact (and therefore every Stop-hook refresh) opened `.ax/rtm.sqlite` through
+// openReusableGraph, which CLEARS the file in place when the basis moved and rebuilds into it. Any
+// reader in that window — an approval computing its impact advisory — saw zero nodes and reported
+// "no impact"; a refresher killed after the clear left the file empty and basis-less for everyone.
+// Reproduced with the built product on 2026-09-13. The live file therefore changes only by rename
+// of a complete, basis-committed temporary database, and readers classify what they find.
+// ---------------------------------------------------------------------------------------------
+/** Age after which a `.tmp-*` / `.bak-*` sibling of the live graph is treated as abandoned by a dead publisher. */
+exports.GRAPH_STALE_MS = 10 * 60_000;
+const removeQuietly = (p) => { try {
+    fs.rmSync(p, { force: true });
+}
+catch { /* best effort */ } };
+const uniqueSibling = (livePath, kind) => `${livePath}.${kind}-${process.pid}-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
+/**
+ * Replace the live file with the finished temporary database. One rename is atomic on POSIX and
+ * replaces a closed file on Windows. When the live file is held open elsewhere on Windows the
+ * direct rename is refused (EPERM/EBUSY/EACCES); only then fall back to the rename-aside sequence,
+ * where an ENOENT on the aside step means a sibling publisher already replaced the file and is not
+ * an error — executing that sequence unconditionally was what made one of four concurrent reindexes
+ * fail before.
+ */
+function replaceLive(tempPath, livePath) {
+    try {
+        fs.renameSync(tempPath, livePath);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')
+            throw error;
+    }
+    const backup = uniqueSibling(livePath, 'bak');
+    let hadBackup = false;
+    try {
+        fs.renameSync(livePath, backup);
+        hadBackup = true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        fs.renameSync(tempPath, livePath);
+    }
+    catch (error) {
+        if (hadBackup && !fs.existsSync(livePath)) {
+            try {
+                fs.renameSync(backup, livePath);
+            }
+            catch { /* preserve the publication error */ }
+        }
+        throw error;
+    }
+    if (hadBackup)
+        removeQuietly(backup);
+}
+/** Remove `.tmp-*` / `.bak-*` siblings (and their SQLite sidecars) older than the stale bound; younger ones may belong to a live publisher. */
+function sweepAbandoned(livePath) {
+    const dir = path.dirname(livePath), base = path.basename(livePath);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith(`${base}.tmp-`) && !name.startsWith(`${base}.bak-`))
+            continue;
+        const p = path.join(dir, name);
+        try {
+            if (Date.now() - fs.statSync(p).mtimeMs > exports.GRAPH_STALE_MS)
+                fs.rmSync(p, { force: true });
+        }
+        catch { /* raced with its owner or already gone */ }
+    }
+}
+/**
+ * Build a complete graph in a private temporary database, commit `basis`, close it, and replace
+ * the live file atomically. The live file is never opened for writing and never cleared; a build
+ * that throws leaves it untouched and removes the temporary file. Returns the published counts.
+ */
+function publishGraph(livePath, basis, build) {
+    fs.mkdirSync(path.dirname(livePath), { recursive: true });
+    const tempPath = uniqueSibling(livePath, 'tmp');
+    let nodes = 0, edges = 0;
+    try {
+        const graph = new rtm_graph_1.RtmGraph(tempPath);
+        try {
+            build(graph);
+            graph.writeMeta(Object.fromEntries(BASIS_FIELDS.map((f) => [f, basis[f]])));
+            nodes = graph.nodeCount();
+            edges = graph.edgeCount();
+        }
+        finally {
+            graph.close(); // checkpoints WAL and drops the temporary database's sidecars
+        }
+        replaceLive(tempPath, livePath);
+    }
+    catch (error) {
+        for (const suffix of ['', '-wal', '-shm', '-journal'])
+            removeQuietly(tempPath + suffix);
+        throw error;
+    }
+    sweepAbandoned(livePath);
+    return { nodes, edges };
+}
+/**
+ * Open the live graph WITHOUT mutating it and say what it is: absent, unreadable (open or metadata
+ * failed — the file is left for the next publication to replace, never deleted here), empty (a
+ * schema with no nodes — the state an interrupted in-place rebuild used to leave behind), or a
+ * served graph whose basis commit is current / stale against `head`, or unverified when either side
+ * is unknown. Served statuses return an OPEN handle the caller must close.
+ */
+function openPublishedGraph(livePath, head) {
+    let graphAsOf;
+    try {
+        graphAsOf = fs.statSync(livePath).mtime.toISOString();
+    }
+    catch {
+        return { status: 'absent', graph: null };
+    }
+    let graph;
+    try {
+        graph = new rtm_graph_1.RtmGraph(livePath);
+    }
+    catch {
+        return { status: 'unreadable', graph: null, graphAsOf };
+    }
+    let meta, nodes;
+    try {
+        meta = graph.readMeta();
+        nodes = graph.nodeCount();
+    }
+    catch {
+        try {
+            graph.close();
+        }
+        catch { /* preserve the classification */ }
+        return { status: 'unreadable', graph: null, graphAsOf };
+    }
+    if (nodes === 0) {
+        graph.close();
+        return { status: 'empty', graph: null, graphAsOf };
+    }
+    const sourceCommit = typeof meta.sourceCommit === 'string' && meta.sourceCommit !== '' ? meta.sourceCommit : null;
+    const status = sourceCommit === null || head === null ? 'unverified' : sourceCommit === head ? 'current' : 'stale';
+    return { status, graph, sourceCommit, head, graphAsOf };
+}
+/**
+ * The `publishable` mode of openReusableGraph. Reads the live file without mutating it; when it
+ * cannot be reused (absent, unreadable, no basis, a moved field) the returned graph is an empty
+ * private temporary database whose `publish()` replaces the live file atomically. The live file is
+ * never created, cleared or deleted here — an unreadable one is left for publication to replace.
+ */
+function openPublishable(livePath, expected) {
+    const basisMeta = () => Object.fromEntries(BASIS_FIELDS.map((f) => [f, expected[f]]));
+    let live = null;
+    let reason = null;
+    if (!fs.existsSync(livePath))
+        reason = 'no stored graph — nothing to reuse';
+    else {
+        try {
+            live = new rtm_graph_1.RtmGraph(livePath);
+        }
+        catch {
+            reason = 'stored graph was unreadable (left for publication to replace)';
+        }
+        if (live !== null) {
+            const stored = readStoredBasis(live);
+            if (!stored)
+                reason = 'no stored basis — nothing to reuse';
+            else {
+                const moved = BASIS_FIELDS.find((field) => stored[field] !== expected[field]);
+                if (moved)
+                    reason = `${moved} changed since the stored graph was built`;
+            }
+        }
+    }
+    if (reason === null && live !== null) {
+        const handle = live;
+        const finish = () => handle.close();
+        return { graph: handle, reusable: true, reason: null, commitBasis: () => handle.writeMeta(basisMeta()), publish: finish, discard: finish };
+    }
+    if (live !== null) {
+        try {
+            live.close();
+        }
+        catch { /* the handle is not reused */ }
+    }
+    const tempPath = uniqueSibling(livePath, 'tmp');
+    const graph = new rtm_graph_1.RtmGraph(tempPath);
+    const cleanup = () => { for (const suffix of ['', '-wal', '-shm', '-journal'])
+        removeQuietly(tempPath + suffix); };
+    return {
+        graph,
+        reusable: false,
+        reason,
+        commitBasis: () => graph.writeMeta(basisMeta()),
+        publish: () => {
+            try {
+                graph.close();
+                replaceLive(tempPath, livePath);
+            }
+            catch (error) {
+                cleanup();
+                throw error;
+            }
+            sweepAbandoned(livePath);
+        },
+        discard: () => { try {
+            graph.close();
+        }
+        finally {
+            cleanup();
+        } },
+    };
+}
+/** HEAD of the repository at `root`, or null outside Git — the only freshness input a consumer pays for (no scan). */
+function headCommitOf(root, env = process.env) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+        return /^[0-9a-f]{40}$/.test(out) ? out : null;
+    }
+    catch {
+        return null;
     }
-    return { graph, reusable: true, reason: null, commitBasis };
 }

package/dist/holmes/rtm/incremental.d.ts

@@ -59,4 +59,5 @@ export declare function applyIncremental(graph: RtmGraph, changes: ChangeSet, ct
     buildOptions?: BuildRtmOptions;
 }): {
     callEdgesResolved: boolean;
+    importsResolved: boolean;
 };

package/dist/holmes/rtm/incremental.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyIncremental = applyIncremental;
+// @implements A-SPEC-644
 const rtm_builder_1 = require("./rtm-builder");
 /**
  * Reduces every add/modify/delete/rename case to one primitive: replace file
@@ -55,13 +56,21 @@ function applyIncremental(graph, changes, ctx) {
         replaceFile(f);
     }
     if (!ctx.allScanned)
-        return { callEdgesResolved: false };
+        return { callEdgesResolved: false, importsResolved: false };
     // @implements A-SPEC-573.5 — `calls_ambiguous` is rebuilt by the same pass, so it must be cleared
     // by the same pass. Missing it left a stale candidate edge behind when an ambiguity RESOLVED
     // (the second definer was deleted), and incremental stopped converging with a full rebuild —
     // caught by A-SPEC-280's convergence property, which is exactly what it is for.
+    const scanned = ctx.allScanned();
     graph.removeEdgesByRel('calls');
     graph.removeEdgesByRel('calls_ambiguous');
-    (0, rtm_builder_1.addCallEdges)(ctx.allScanned(), graph, ctx.buildOptions);
-    return { callEdgesResolved: true };
+    (0, rtm_builder_1.addCallEdges)(scanned, graph, ctx.buildOptions);
+    // @implements A-SPEC-644 — the same whole-scan rule for imports. FILE nodes and `imports` edges are
+    // written by `addImportEdges` over the whole scan (A-SPEC-289) and never by the per-file subgraph, so
+    // measured 2026-09-14 an update that added an import produced no FILE node and no edge, and one that
+    // deleted the import target left a stale FILE node. Clear the kind and the relation, then re-resolve.
+    graph.removeEdgesByRel('imports');
+    graph.removeNodesByKind('FILE');
+    (0, rtm_builder_1.addImportEdges)(scanned, graph, ctx.buildOptions);
+    return { callEdgesResolved: true, importsResolved: true };
 }

package/dist/holmes/rtm/localize.js

@@ -163,6 +163,10 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     // be recovered lexically, however many terms it has.
     const citations = citationsIn(issueText, new Set(specs.map((s) => s.id)));
     const citedSet = new Set(citations.cited);
+    // @implements A-SPEC-619 — explicit architecture-contract evidence is a ranking key,
+    // not a bonus that unrelated lexical repetition can dilute out of the result window.
+    const priorityCitations = new Set(specs.filter(s => s.type === 'A-SPEC' && citedSet.has(s.id)).map(s => s.id));
+    const directlyCitedFiles = new Set();
     if (terms.length === 0 && citations.cited.length === 0) {
         return { terms: [], hits: [], matchedSpecs: [], unknownCitations: citations.unknown };
     }
@@ -314,6 +318,8 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
             why.push(`implements matched spec(s) ${viaSpecs.join(', ')} (${viaSpecs.length}/${anchors.length} anchors)`);
         }
         const citedAnchors = anchors.filter((id) => citedSet.has(id));
+        if (anchors.some(id => priorityCitations.has(id)))
+            directlyCitedFiles.add(f.sourcePath);
         if (citedAnchors.length > 0) {
             // Normalized by anchor count for the same reason the lexical spec bonus is (A-SPEC-270):
             // otherwise a hub file would collect this bonus for every citation anyone ever writes.
@@ -361,6 +367,7 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     // project where the vendored code really is the answer. The score halving stays, so the relative
     // order WITHIN each group is unchanged.
     hits.sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) || // live source before vendored
+        Number(directlyCitedFiles.has(b.file)) - Number(directlyCitedFiles.has(a.file)) ||
         b.score - a.score || // then by evidence strength
         a.file.localeCompare(b.file)); // then deterministic path order
     return { terms, hits: hits.slice(0, topN), matchedSpecs: matchedSpecs.sort(), unknownCitations: citations.unknown };