@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/maintenance-analysis.js

@@ -0,0 +1,288 @@
+"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.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
+// @implements A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const spec_types_1 = require("../../spec/spec-types");
+const cpg_scanner_1 = require("../../cpg/cpg-scanner");
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const test_scope_1 = require("../../rtm/test-scope");
+const root_1 = require("../../project/root");
+const test_evidence_1 = require("../../review/test-evidence");
+const temporal_prior_1 = require("../../review/temporal-prior");
+const commit_text_1 = require("../../review/commit-text");
+const bundler_1 = require("../../context/bundler");
+const tier_1 = require("../../semantic/tier");
+const vector_cache_1 = require("../../semantic/vector-cache");
+const embedder_1 = require("../../semantic/embedder");
+const maintenance_analyze_1 = require("../maintenance-analyze");
+const maintenance_evidence_1 = require("../maintenance-evidence");
+const defuse_bound_1 = require("../defuse-bound");
+function createMaintenanceAnalysisHandlers(context) {
+    return {
+        async maintenance_analyze(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            // This tool is advertised as read-only. Do not attach ScanFileCache: its normal save/prune
+            // behavior mutates `.ax/cpg_cache` even though the analysis itself is observational.
+            const scanner = new cpg_scanner_1.CpgScanner();
+            const scanned = scanner.scan(root, root);
+            const skipped = scanner.scanSkipped();
+            const specs = (0, spec_types_1.filterGoverned)(await context.listSpecs());
+            const anchors = (0, test_scope_1.scanTestAnchors)(root);
+            const detail = context.basisFor(root, true);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            const supportedExtensions = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
+            const knownCodeExtensions = new Set(['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r']);
+            const unsupportedLanguages = new Set();
+            try {
+                const files = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 8 * 1024 * 1024 }).split('\0');
+                for (const file of files) {
+                    const ext = path.extname(file).toLowerCase();
+                    if (knownCodeExtensions.has(ext) && !supportedExtensions.has(ext))
+                        unsupportedLanguages.add(ext);
+                }
+            }
+            catch {
+                // A non-git tree cannot be enumerated cheaply without reimplementing the scanner's ignore
+                // rules. Surface the missing axis rather than claiming every language was covered.
+                unsupportedLanguages.add('not-enumerated(non-git)');
+            }
+            const graph = new rtm_graph_1.RtmGraph();
+            try {
+                // @implements A-SPEC-292 — the resolution loop's own tally of what it declined to link.
+                const { resolution } = (0, rtm_builder_1.buildRtm)(specs, scanned, graph);
+                // @implements A-SPEC-293 — what constrains this change, not just what it touches.
+                const { decisions, citations } = context.collectDecisions(root, scanned, specs);
+                (0, rtm_builder_1.addDecisionEdges)(decisions, citations, graph);
+                const common = {
+                    request: a.request,
+                    scanned,
+                    specs,
+                    graph,
+                    testAnchors: anchors,
+                    basis: {
+                        head,
+                        loadedBuild: detail.loadedBuild,
+                        diskBuild: detail.diskBuild ?? 'unknown',
+                        specFingerprint: `count:${specs.length}/fp:${detail.specs ?? 'unknown'}`,
+                    },
+                    changedFiles: a.changedFiles,
+                    // @implements A-SPEC-290 — the stored run record. Freshness is judged inside the analysis
+                    // against its own basis, so a record from another commit is reported as stale rather than
+                    // quietly used.
+                    runtimeEvidence: (0, test_evidence_1.readTestEvidence)(root),
+                    resolution,
+                    coverage: {
+                        scannedFiles: scanned.length,
+                        skippedFiles: skipped.map((entry) => entry.file),
+                        unsupportedLanguages: [...unsupportedLanguages],
+                        historyStatus: 'not-requested',
+                    },
+                };
+                // @implements A-SPEC-478 — resolve the tier and precompute the query vector at the
+                // async edge; the sync analysis receives only a closure over cached vectors. Any failure
+                // (no tier, no module, no key, embed error) leaves `semantic` undefined = today's behavior.
+                let semantic;
+                try {
+                    const rt = (0, embedder_1.makeTierEmbedder)((0, tier_1.resolveSemanticTier)(), new vector_cache_1.VectorCache(root));
+                    if (rt !== null) {
+                        const qv = await rt.embedQuery(a.request);
+                        semantic = { label: rt.label, queryVector: qv, cachedDocVector: rt.cachedDocVector };
+                    }
+                }
+                catch { /* the hot path never breaks on the semantic layer */ }
+                const preliminary = (0, maintenance_analyze_1.analyzeMaintenance)({ ...common, history: [], semantic });
+                const candidateFiles = preliminary.candidates.map((candidate) => candidate.file);
+                const limit = Math.max(0, Math.min(100, Math.floor(a.historyLimit ?? 20)));
+                const history = [];
+                let historyStatus = limit === 0 || candidateFiles.length === 0 ? 'not-requested' : 'unavailable';
+                if (limit > 0 && candidateFiles.length > 0) {
+                    try {
+                        const raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'log', `-${limit}`, '--date=short', '--format=%H%x00%ad%x00%s', '--name-only', '--', ...candidateFiles], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 2 * 1024 * 1024 });
+                        let current = null;
+                        for (const line of raw.split('\n')) {
+                            if (line.includes('\0')) {
+                                const [commit, date, subject] = line.split('\0');
+                                current = { commit, date, subject, files: [] };
+                                history.push(current);
+                            }
+                            else if (current && line.trim() !== '') {
+                                // git C-quotes any non-ASCII pathname here (core.quotepath). Left raw, it never
+                                // matched a candidate file, so the rationale came back empty while historyStatus
+                                // still reported `available` — a silent false negative with confident provenance.
+                                current.files.push((0, maintenance_analyze_1.unquoteGitPath)(line.trim()));
+                            }
+                        }
+                        historyStatus = 'available';
+                    }
+                    catch { /* history is evidence enrichment, not a prerequisite */ }
+                }
+                // Preserve localization rank for context: `impacts.direct` is deliberately sorted for a
+                // stable evidence contract, but sorting is not relevance. Seeding from it once selected a
+                // lexically earlier vendored symbol while the first ranked hit correctly named live code.
+                const directSeed = preliminary.candidates
+                    .flatMap((candidate) => candidate.symbols)
+                    .flatMap((qualifiedName) => graph.codeNodeIds(qualifiedName))[0];
+                const specSeed = preliminary.candidateSpecs.find((id) => id.startsWith('A-SPEC-'));
+                const seedId = directSeed ?? (specSeed ? `SPEC:${specSeed}` : undefined);
+                const budget = Math.max(100, Math.min(10_000, Math.floor(a.contextBudget ?? 2_000)));
+                const contextBundle = seedId
+                    ? new bundler_1.ContextBundler(graph, context.buildContentSource(specs, scanned)).getContextBundle(seedId, budget)
+                    : null;
+                // @implements A-SPEC-378
+                // Change recency over a WIDE window and ALL files — the enrichment history above is
+                // deliberately narrow (candidate files, 20 commits) and cannot serve as a prior: a file the
+                // lexical layer never ranked has no history there, which is precisely the file recency is
+                // supposed to promote. Failure is silent and total: no prior means the previous ranking,
+                // never a partial one, because a prior built from half the history would reorder on evidence
+                // nobody could audit.
+                const changePrior = {};
+                try {
+                    const prior = (0, temporal_prior_1.temporalPrior)(root, 'HEAD', 300);
+                    for (const [file, age] of prior.recency)
+                        changePrior[file] = 1 + Math.pow(0.5, age / 10);
+                }
+                catch { /* no history, no prior — the ranking falls back to lexical evidence alone */ }
+                // @implements A-SPEC-388
+                // What each file's commits have SAID, normalised to 0..1. Measured on history sampled away
+                // from the benchmarker's own recent work (A-SPEC-387): Top-1 0.244 -> 0.333 here and 0.400 ->
+                // 0.500 on a second repository, Top-10 recall 0.393 -> 0.601 there. Precision falls on both,
+                // and that is the trade, not a footnote to it.
+                const commitTextBoost = {};
+                try {
+                    const profile = (0, commit_text_1.commitTextProfile)(root, 'HEAD', 400);
+                    const ranked = (0, commit_text_1.rankByCommitText)(a.request, profile, 300);
+                    const top = ranked[0]?.score ?? 0;
+                    if (top > 0)
+                        for (const hit of ranked)
+                            commitTextBoost[hit.file] = hit.score / top;
+                }
+                catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
+                const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
+                    semantic,
+                    ...common,
+                    coverage: { ...common.coverage, historyStatus },
+                    history,
+                    changePrior,
+                    commitTextBoost,
+                    contextBundle,
+                    groundTruth: a.groundTruth,
+                    defUse,
+                });
+                // @implements A-SPEC-573.4 — def-use for the TOP CANDIDATES ONLY. Extracting it for the whole
+                // repository costs +88.8% (measured 2026-09-08), well past this slice's budget; the first pass
+                // says which handful of files are worth parsing, and the second pass reads their data flow.
+                // Every step is fail-open: a parse failure, an unsupported language or a missing file leaves
+                // the candidate's symbols exactly as the first pass produced them.
+                const firstPass = analyzeWith();
+                const analysis = (() => {
+                    const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((c) => c.file);
+                    if (targets.length === 0)
+                        return firstPass;
+                    const defUse = {};
+                    try {
+                        const { TreeSitterTsParser, hasDataFlowWalk } = require('../../cpg/language-parser');
+                        const { langForPath } = require('../../cpg/cpg-scanner');
+                        const parser = new TreeSitterTsParser();
+                        for (const file of targets) {
+                            try {
+                                // The LANGUAGE matters: the first wiring omitted it and parsed Python as TypeScript,
+                                // which produced wrong facts and cost the second corpus 0.2376 -> 0.1741 on the
+                                // symbol axis. A language with no walk is skipped rather than guessed at.
+                                const lang = langForPath(file);
+                                if (!hasDataFlowWalk(lang))
+                                    continue;
+                                const facts = parser.extractDataFlow(fs.readFileSync(path.join(root, file), 'utf8'), lang);
+                                if (facts !== undefined)
+                                    defUse[file] = facts;
+                            }
+                            catch { /* one unreadable or unparseable file must not cost the other nine */ }
+                        }
+                    }
+                    catch {
+                        return firstPass;
+                    }
+                    return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
+                })();
+                // @implements A-SPEC-268 — persistence is OPT-IN. The tool is advertised read-only, and a
+                // regression pins that a cold project gains no `.ax/cpg_cache`; writing evidence by default
+                // would break that contract for every caller who only wanted to look.
+                // One shape either way: `persistedTo` is present-or-undefined rather than a union, so a
+                // caller never has to narrow the result to ask whether anything was written.
+                const result = { ...analysis };
+                // @implements A-SPEC-418 — first line, because everything below it was computed without specs.
+                const blind = context.specStoreBlindReason(root, specs.length);
+                if (blind !== null)
+                    result.unknowns = [blind, ...result.unknowns];
+                if (a.persist) {
+                    // @implements A-SPEC-277 — record WHAT WAS ANALYSED, not just which paths. HEAD cannot see
+                    // an uncommitted edit to the analysed file; a content digest can.
+                    const fileDigests = {};
+                    for (const file of analysis.impacts.files) {
+                        const digest = context.fileDigestOf(root, file);
+                        if (digest)
+                            fileDigests[file] = digest;
+                    }
+                    // The artifact takes the WHOLE analysis, never the bounded one below: a file has no
+                    // context window, and the calibration that scores this prediction must score what the
+                    // product actually predicted.
+                    result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
+                }
+                // @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
+                // 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
+                // it, which is why AGENTS.md step 3 had never once been obeyed with `persist: true`.
+                // `persistedTo` rides along so the caller knows where the whole thing is.
+                const bounded = (0, maintenance_analyze_1.boundAnalysis)(result);
+                if (JSON.stringify(bounded).length !== JSON.stringify(result).length)
+                    bounded.bounded = true;
+                return bounded;
+            }
+            finally {
+                graph.close();
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts

@@ -0,0 +1,40 @@
+interface MaintenanceEvidenceContext {
+    foreignRootReason(root: string): string | null;
+    projectRootOf(root: string): string;
+    refusal(reason: string): Error;
+    fileDigestOf(root: string, relativePath: string): string | null;
+}
+/** Raw handlers: the public facade attaches basis exactly once. */
+export declare function createMaintenanceEvidenceHandlers(context: MaintenanceEvidenceContext): {
+    maintenance_outcome(a: {
+        root: string;
+        digest: string;
+        actualFiles?: string[];
+        actualSymbols?: string[];
+        actualTests?: string[];
+        actualClassification?: string;
+    }): Promise<import("../maintenance-evidence").EvidenceArtifact>;
+    impact_gate_check(a: {
+        root: string;
+        target: string;
+        digest?: string;
+    }): Promise<import("../../guardrail/impact-gate").EditEvidenceVerdict>;
+    maintenance_calibration(a: {
+        root: string;
+        minSamples?: number;
+    }): Promise<{
+        artifacts: number;
+        unreadable: string[];
+        skippedSchema: number;
+        schema: string;
+        n: number;
+        withoutClassification: number;
+        bins: import("../maintenance-evidence").CalibrationBin[];
+        brierScore: number | null;
+        falsePositives: number;
+        falseNegatives: number;
+        minSamples: number;
+        status: "measured" | "insufficient-data";
+    }>;
+};
+export {};

package/dist/holmes/mcp/handlers/maintenance-evidence.js

@@ -0,0 +1,104 @@
+"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.createMaintenanceEvidenceHandlers = createMaintenanceEvidenceHandlers;
+// @implements A-SPEC-603
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const maintenance_evidence_1 = require("../maintenance-evidence");
+const impact_gate_1 = require("../../guardrail/impact-gate");
+const root_1 = require("../../project/root");
+/** Raw handlers: the public facade attaches basis exactly once. */
+function createMaintenanceEvidenceHandlers(context) {
+    return {
+        // @implements A-SPEC-268
+        async maintenance_outcome(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            return (0, maintenance_evidence_1.recordOutcome)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), a.digest, {
+                actualFiles: a.actualFiles,
+                actualSymbols: a.actualSymbols,
+                actualTests: a.actualTests,
+                actualClassification: a.actualClassification,
+            }, new Date().toISOString());
+        },
+        // @implements A-SPEC-277
+        async impact_gate_check(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            let artifact = null;
+            if (a.digest) {
+                const file = path.join(root, maintenance_evidence_1.EVIDENCE_DIR, (0, maintenance_evidence_1.digestFilename)(a.digest));
+                // A digest naming an artifact this project never stored is NOT the same as no evidence at
+                // all — say which one happened rather than collapsing both into "refused".
+                if (!fs.existsSync(file))
+                    throw context.refusal(`이 프로젝트에 저장된 분석이 아닙니다: ${a.digest}`);
+                artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+            }
+            return (0, impact_gate_1.evaluateEditEvidence)({
+                target: a.target.replace(/\\/g, '/'),
+                artifact,
+                currentHead: head,
+                currentTargetDigest: context.fileDigestOf(root, a.target),
+            });
+        },
+        // @implements A-SPEC-268
+        async maintenance_calibration(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            const read = (0, maintenance_evidence_1.readArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR));
+            // Corrupt and off-schema records travel WITH the score. A calibration that quietly dropped
+            // them would report a clean number over an unstated subset of the evidence.
+            return {
+                ...(0, maintenance_evidence_1.computeCalibration)(read.artifacts, { minSamples: a.minSamples }),
+                artifacts: read.artifacts.length,
+                unreadable: read.unreadable,
+                skippedSchema: read.skippedSchema,
+            };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/operator-inspection.d.ts

@@ -0,0 +1,167 @@
+import { Spec } from '../../spec/spec-parser';
+import { SpecStore } from '../../spec/spec-store';
+import type { Approval } from '../../guardrail/risk-gate';
+export interface OperatorInspectionContext {
+    listSpecs(): Promise<Spec[]>;
+    readSpec: SpecStore['read'];
+    specsRoot(): unknown;
+    assertStoreReachable(tool: string, root: unknown): void;
+    resolver(specs: Spec[]): (id: string) => Spec | null;
+    resolveLedgerRoot(root?: string): {
+        ok: true;
+        root: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    fetchJson(url: string): Promise<any>;
+    /** A-SPEC-642 — the shared approval channel and queue hint, for the reconciliation act. */
+    resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
+        kind: string;
+        target: string;
+    }, now: string): {
+        approval: Approval;
+        source: 'env' | 'grant';
+        root?: string;
+    } | undefined;
+    refusalQueueHint(root: string | undefined, request: {
+        kind: string;
+        target: string;
+        why: string;
+    }): string;
+}
+export declare function createOperatorInspectionHandlers(context: OperatorInspectionContext): {
+    /**
+     * @implements A-SPEC-538.2
+     * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+     * state, and the concrete blockers still standing between it and approval — so a caller need not
+     * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+     * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+     * acts it describes. No writes, no ledger append.
+     */
+    approval_status(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+    } | {
+        graphPreview?: {
+            impact?: import("../../rtm/impact-advisory").ImpactAdvisory;
+            density?: Array<import("../../rtm/anchor-density").AnchorDensityFinding>;
+            cycles?: {
+                findings: Array<import("../../cpg/cycle-detect").CycleFinding>;
+                note: string;
+            };
+            architecture?: Array<import("../../cpg/arch-observe").ArchObservation>;
+            graphAsOf?: string;
+            graph?: {
+                status: "current" | "stale" | "unverified";
+                sourceCommit: string | null;
+                head: string | null;
+            };
+            unavailable?: "empty" | "unreadable";
+        } | undefined;
+        id: string;
+        type?: string;
+        status: string;
+        sealed: boolean;
+        approvedDigest?: string;
+        parents: import("../../spec/approval-status").ParentApproval[];
+        blockers: string[];
+        resealBlockers: string[];
+        ok: boolean;
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-538.3
+     * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+     * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+     * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+     * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+     * error.
+     */
+    ledger_timeline(a: {
+        root?: string;
+        id?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        events?: undefined;
+    } | {
+        ok: boolean;
+        events: import("../../governance/ledger-timeline").TimelineEntry[];
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-642
+     * The one exit from a merged cross-replica double-spend. Under out-of-band authority of kind
+     * `ledger-reconcile` for that nonce, append `nonce-double-spend-reconciled` on THIS replica's chain
+     * naming the nonce and every consuming event's hash; `verifyAll`, the Stop hook, baseline trust and
+     * the ledger-conflict refusals then clear. Nothing is erased: both consumptions stay in their
+     * chains, and a later consumption of the same nonce is a new, open double-spend. Refuses to extend
+     * a broken chain, because a reconciliation that itself cannot be verified lifts nothing.
+     */
+    ledger_reconcile(a: {
+        root?: string;
+        nonce: string;
+        rationale?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        reconciled?: undefined;
+        nonce?: undefined;
+        pending?: undefined;
+        code?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        reconciled: boolean;
+        nonce: string;
+        pending: string[];
+        reason: string;
+        code?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+        reconciled?: undefined;
+        nonce?: undefined;
+        pending?: undefined;
+        events?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        reconciled: boolean;
+        nonce: string;
+        events: {
+            replicaId: string | null;
+            seq: number;
+            hash: string;
+            ts: string;
+        }[];
+        remaining: string[];
+        reason?: undefined;
+        pending?: undefined;
+        code?: undefined;
+    }>;
+    rtm_dashboard(a: {
+        root?: string;
+        port?: number;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        url?: undefined;
+        running?: undefined;
+        census?: undefined;
+    } | {
+        ok: boolean;
+        url: string;
+        running: boolean;
+        census: import("../../server/dashboard-launcher").DashboardCensus;
+        reason?: undefined;
+    }>;
+};