@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/project/workspace-identity.js

@@ -0,0 +1,181 @@
+"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.WorkspaceIdentityError = void 0;
+exports.workspaceIdentity = workspaceIdentity;
+// @implements A-SPEC-623
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const root_1 = require("./root");
+class WorkspaceIdentityError extends Error {
+    code;
+    holmesRefusal = true;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkspaceIdentityError';
+    }
+}
+exports.WorkspaceIdentityError = WorkspaceIdentityError;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const errno = (e, code) => e?.code === code;
+function directory(file, optional = false) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (optional && errno(e, 'ENOENT'))
+            return false;
+        throw e;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new WorkspaceIdentityError('unsafe-path', 'Identity directories must be real directories, not symlinks.');
+    return true;
+}
+function readRecord(file, local) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (errno(e, 'ENOENT'))
+            return null;
+        throw e;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new WorkspaceIdentityError('unsafe-path', 'Identity must be a regular file, not a symlink.');
+    let value;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino)
+            throw new WorkspaceIdentityError('identity-changed', 'Identity changed while opening; retry.');
+        try {
+            value = JSON.parse(fs.readFileSync(fd, 'utf8'));
+        }
+        catch (e) {
+            if (e instanceof SyntaxError)
+                throw new WorkspaceIdentityError('invalid-identity', 'Identity contains invalid JSON; preserve and repair it explicitly.');
+            throw e;
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const schema = local ? 'holmes-workspace-replica/1' : 'holmes-workspace/1';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new WorkspaceIdentityError('invalid-identity', 'Identity must be a schema-versioned object.');
+    const record = value, keys = local ? ['schema', 'workspaceId', 'replicaId'] : ['schema', 'workspaceId'];
+    if (record.schema !== schema || Object.keys(record).length !== keys.length || keys.some(k => !(k in record))
+        || typeof record.workspaceId !== 'string' || !uuid.test(record.workspaceId)
+        || (local && (typeof record.replicaId !== 'string' || !uuid.test(record.replicaId)))) {
+        throw new WorkspaceIdentityError('invalid-identity', 'Unsupported schema, fields or identifier; existing identity was not replaced.');
+    }
+    return local ? record : record;
+}
+/** Complete bytes first, then one atomic no-replace link. Never fall back to overwriting a winner. */
+function publish(file, record) {
+    const temp = path.join(path.dirname(file), `.identity-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    let owned = false;
+    try {
+        const fd = fs.openSync(temp, 'wx', 0o600);
+        owned = true;
+        try {
+            fs.writeFileSync(fd, JSON.stringify(record) + '\n');
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        try {
+            fs.linkSync(temp, file);
+        }
+        catch (e) {
+            if (!errno(e, 'EEXIST'))
+                throw e;
+        }
+    }
+    finally {
+        if (owned)
+            fs.unlinkSync(temp);
+    }
+}
+function workspaceIdentity(rootArg, operation = 'status') {
+    if (!['status', 'initialize', 'register'].includes(operation))
+        throw new WorkspaceIdentityError('invalid-operation', 'Use status, initialize or register.');
+    const resolved = (0, root_1.resolveProjectRoot)(rootArg, { includeGit: false });
+    if (resolved.marker !== '.ax')
+        throw new WorkspaceIdentityError('missing-workspace', 'An existing Holmes .ax workspace marker is required.');
+    const ax = path.join(resolved.root, '.ax'), state = path.join(ax, 'state');
+    directory(ax);
+    const canonicalFile = path.join(ax, 'workspace.json'), localFile = path.join(state, 'workspace-replica.json');
+    let canonical = readRecord(canonicalFile, false);
+    let local = directory(state, true) ? readRecord(localFile, true) : null;
+    if (local && (!canonical || local.workspaceId !== canonical.workspaceId))
+        throw new WorkspaceIdentityError('workspace-mismatch', 'Local registration does not belong to the canonical workspace; it was preserved.');
+    if (!canonical) {
+        if (operation === 'status')
+            return { ok: true, state: 'legacy' };
+        if (operation === 'register')
+            throw new WorkspaceIdentityError('uninitialized', 'Initialize and share the canonical workspace identity before registering a replica.');
+        publish(canonicalFile, { schema: 'holmes-workspace/1', workspaceId: (0, node_crypto_1.randomUUID)() });
+        canonical = readRecord(canonicalFile, false);
+        if (!canonical)
+            throw new WorkspaceIdentityError('identity-changed', 'Canonical identity disappeared during initialization; retry.');
+    }
+    if (!local && operation !== 'status') {
+        try {
+            fs.mkdirSync(state);
+        }
+        catch (e) {
+            if (!errno(e, 'EEXIST'))
+                throw e;
+        }
+        directory(state);
+        publish(localFile, { schema: 'holmes-workspace-replica/1', workspaceId: canonical.workspaceId, replicaId: (0, node_crypto_1.randomUUID)() });
+        local = readRecord(localFile, true);
+        if (!local)
+            throw new WorkspaceIdentityError('identity-changed', 'Local registration disappeared during initialization; retry.');
+    }
+    const current = readRecord(canonicalFile, false);
+    if (!current || current.workspaceId !== canonical.workspaceId || (local && local.workspaceId !== canonical.workspaceId)) {
+        throw new WorkspaceIdentityError('workspace-mismatch', 'Workspace identity changed during registration; preserve records and resolve the mismatch.');
+    }
+    return local
+        ? { ok: true, state: 'registered', workspaceId: canonical.workspaceId, replicaId: local.replicaId }
+        : { ok: true, state: 'initialized', workspaceId: canonical.workspaceId };
+}

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

@@ -1,3 +1,4 @@
+import { ExecutionContext } from '../project/execution-context';
 import { TestOutcome } from './test-runner';
 export declare const OUTCOMES_FILE: string;
 export declare function outcomesFilename(replica: string): string;
@@ -10,6 +11,7 @@ export declare function isOutcomesFilename(name: string): boolean;
  * still dirty, which is exactly when the Stop gate reads them.
  */
 export interface OutcomeRecord {
+    execution?: ExecutionContext;
     aspec: string;
     outcome: TestOutcome;
     ts: string;
@@ -44,7 +46,10 @@ export declare function buildOutcomeRecords(outcomeByFile: Record<string, TestOu
  * 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.
  */
-export declare function groupOutcomesByAspec(records: OutcomeRecord[], head: string): Record<string, Array<{
+export declare function groupOutcomesByAspec(records: OutcomeRecord[], head: string, 
+/** @implements A-SPEC-645 — maps a record's display id to the id the entity carries now (from the ledger's renames). */
+canonical?: (id: string) => string): Record<string, Array<{
     outcome: TestOutcome;
     ts: string;
+    execution?: ExecutionContext;
 }>>;

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,38 @@ 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() };
+        // @implements A-SPEC-651.1 — launch from the canonical spelling: pytest keys its JUnit `file`
+        // attribute relative to its rootdir, and an 8.3 invocation dir made that key climb out of the
+        // project (`../../…/tests/test_calc.py`, measured 2026-09-14 on Windows).
+        const out = (0, node_child_process_1.execFileSync)(python, args, { cwd: fs.existsSync(cwd) ? (0, root_1.canonicalPath)(cwd) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: RUNNER_MAX_BUFFER, env: (0, root_1.cleanTestEnv)() });
+        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 +776,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;