@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/cpg/language-parser-walk.js

@@ -43,6 +43,32 @@ const LANG_CONFIG = {
         funcTypes: ['function_declaration'],
         methodTypes: ['method_definition'],
         funcIsMethodInClass: false,
+        // @implements A-SPEC-301
+        // Contracts are deliberately NOT emitted, and this is a measured decision rather than an
+        // oversight. This repository has 192 interfaces and 54 type aliases that the graph does not
+        // know about — about a quarter of its top-level declarations — and in TypeScript the interface
+        // IS the contract, so Phase 5's contract-level impact has no object to reason about.
+        //
+        // Emitting them was implemented and measured on the point-in-time replay corpus (2026-08-28):
+        //
+        //             hit rate            recall
+        //   Top-1     0.250 -> 0.333      0.194 -> 0.278     better
+        //   Top-3     0.500 -> 0.500      0.331 -> 0.331     unchanged
+        //   Top-5     0.583 -> 0.583      0.470 -> 0.470     unchanged
+        //   Top-10    0.833 -> 0.750      0.690 -> 0.607     WORSE
+        //
+        // 246 extra candidates sharpen the top of the ranking and crowd true files out of the tail. The
+        // A-SPEC-297 floor on Top-10 recall (0.62) caught it. Operating principle 11 is explicit that a
+        // graph extension must show an improvement, and this one shows a trade, so it was reverted.
+        // A-SPEC-302 tried the obvious next design — contracts as nodes, excluded from localization
+        // scoring — and measured it: every replay metric came back EXACTLY at baseline
+        // (Top-1 0.250/0.194, Top-10 0.833/0.690). So S-301's Top-1 gain came entirely from scoring
+        // contract names, and removing them from scoring removes the gain with it. What remains is 246
+        // nodes and 4 edges with no measured downstream benefit, because nothing consumes contract nodes
+        // yet. Operating principle 11 forbids exactly that, so this was declined too.
+        //
+        // What would justify it: building the CONSUMER and the nodes in one slice, so the benefit is
+        // measurable in the same experiment. Nodes first, benefit later, is the shape that keeps failing.
     },
     python: {
         classTypes: ['class_definition'],
@@ -84,9 +110,22 @@ LANG_CONFIG.tsx = LANG_CONFIG.typescript;
 // only when lexically inside a class, and recursing into ANY def resets
 // enclosingClass to null for its children, so a def nested inside a def is
 // never mistaken for a method of the outer class).
+// @implements A-SPEC-291
+// Symbols are qualified by the FULL path of named scopes, exactly as `namedScopeOf` qualifies an
+// edge's caller. The two used to disagree: this walk qualified only by an enclosing CLASS, so a
+// function nested in a function came out bare (`inner`) and an object-literal method was not emitted
+// at all, while the edge walk named the caller `outer.inner` / `makeHandlers.doThing`. The builder
+// requires a caller to be a real node in its file, so every such edge was dropped — measured
+// 2026-08-28, 1,307 relations in this repository (591 in TypeScript, 9.4%), including every call
+// made by the MCP handler surface, which lives in methods of an object a function returns.
+//
+// `scope` carries whether each segment is a class, because `kind` still distinguishes a method of a
+// class from a plain nested function. An unnamed scope (a function EXPRESSION) contributes no
+// segment — the edge walk does not count it either, so the two stay aligned.
 function walkSymbols(tree, config) {
     const out = [];
-    const visit = (node, enclosingClass) => {
+    const pathOf = (scope, name) => [...scope.map((s) => s.name), name].join('.');
+    const visit = (node, scope) => {
         const type = node.type;
         if (config.classTypes.includes(type)) {
             const nameNode = node.childForFieldName('name');
@@ -95,65 +134,68 @@ function walkSymbols(tree, config) {
                 out.push({
                     name,
                     kind: 'class',
-                    qualifiedName: name,
+                    qualifiedName: pathOf(scope, name),
                     startLine: node.startPosition.row + 1,
                     endLine: node.endPosition.row + 1,
                 });
             }
-            const childClass = name || enclosingClass;
+            const childScope = name ? [...scope, { name, isClass: true }] : scope;
             for (let i = 0; i < node.childCount; i++)
-                visit(node.child(i), childClass);
+                visit(node.child(i), childScope);
             return;
         }
         if (config.funcTypes.includes(type)) {
             const nameNode = node.childForFieldName('name');
             const name = nameNode ? nameNode.text : undefined;
+            let childScope = scope;
             if (name) {
-                const isMethod = config.funcIsMethodInClass && !!enclosingClass;
-                const kind = isMethod ? 'method' : 'function';
-                const qualifiedName = isMethod ? `${enclosingClass}.${name}` : name;
+                // A method only when the IMMEDIATE enclosing scope is a class — the same question the old
+                // `enclosingClass` flag answered, now asked of the path's last segment. Python's nested-def
+                // reset rule falls out of this for free: a def inside a def has a function as its immediate
+                // scope, so it is a function, and its qualified name states the nesting rather than hiding it.
+                const enclosing = scope[scope.length - 1];
+                const isMethod = config.funcIsMethodInClass && !!enclosing && enclosing.isClass;
                 out.push({
                     name,
-                    kind,
-                    qualifiedName,
+                    kind: isMethod ? 'method' : 'function',
+                    qualifiedName: pathOf(scope, name),
                     startLine: node.startPosition.row + 1,
                     endLine: node.endPosition.row + 1,
                 });
+                childScope = [...scope, { name, isClass: false }];
             }
-            // Nested-def reset rule (see funcIsMethodInClass doc above): only
-            // context-sensitive languages (Python) reset enclosingClass to null
-            // here; languages with a dedicated methodTypes node (TypeScript) carry
-            // enclosingClass through unchanged, matching original behavior.
-            const childEnclosing = config.funcIsMethodInClass ? null : enclosingClass;
             for (let i = 0; i < node.childCount; i++)
-                visit(node.child(i), childEnclosing);
+                visit(node.child(i), childScope);
             return;
         }
         if (config.methodTypes.includes(type)) {
             const nameNode = node.childForFieldName('name');
-            if (nameNode) {
+            let childScope = scope;
+            // An object-literal method is emitted only when the scope path can QUALIFY it. Nested inside
+            // a named function it is nameable — `makeHandlers.doThing` — and the edge walk already called
+            // it that, so emitting it is what makes the two agree. At the top level there is nothing to
+            // qualify it with, and a bare `foo` symbol would collide with any real function of that name
+            // and corrupt resolution for both: that is the spurious-unqualified-method case the previous
+            // rule existed to prevent, and it still holds.
+            if (nameNode && scope.length > 0) {
                 const name = nameNode.text;
-                // Only emit method symbols for genuine class members
-                // (enclosingClass !== null). Skip object-literal methods, which have
-                // no enclosing class, to avoid spurious unqualified method symbols.
-                if (enclosingClass) {
-                    out.push({
-                        name,
-                        kind: 'method',
-                        qualifiedName: `${enclosingClass}.${name}`,
-                        startLine: node.startPosition.row + 1,
-                        endLine: node.endPosition.row + 1,
-                    });
-                }
+                out.push({
+                    name,
+                    kind: 'method',
+                    qualifiedName: pathOf(scope, name),
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+                childScope = [...scope, { name, isClass: false }];
             }
             for (let i = 0; i < node.childCount; i++)
-                visit(node.child(i), enclosingClass);
+                visit(node.child(i), childScope);
             return;
         }
         for (let i = 0; i < node.childCount; i++)
-            visit(node.child(i), enclosingClass);
+            visit(node.child(i), scope);
     };
-    visit(tree.rootNode, null);
+    visit(tree.rootNode, []);
     return out;
 }
 // @implements A-SPEC-121.6
@@ -488,11 +530,26 @@ function extractSymbolsFromTree(tree, lang = 'typescript') {
 // identifier segment); `scopeTypes` are the class/function nodes whose `name` builds the enclosing
 // qualified path (so a method's edges resolve to `Class.method`, matching the symbol walk).
 const EDGE_CONFIG = {
+    // @implements A-SPEC-300
+    // Go had the same defect, found by measuring rather than by assuming it was Rust-only: the symbol
+    // walk qualifies a method by its RECEIVER type (`Store.Load`) while the edge walk used the bare
+    // `name` field, so Go method calls never became edges either.
     go: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_declaration', 'method_declaration'] },
-    rust: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_item'] },
+    // @implements A-SPEC-300
+    // `impl_item`/`trait_item` must open a qualifying scope, exactly as the symbol walk does: a method
+    // in `impl Greet for En` is the symbol `En.hello`, but its edges came out qualified as bare
+    // `hello`, so the caller matched no node and EVERY Rust method call was dropped (measured:
+    // callerNotNamed 1 of 1). Same defect C++ had under A-SPEC-287.
+    rust: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_item', 'impl_item', 'trait_item'] },
     java: { callTypes: ['method_invocation'], calleeField: 'name', scopeTypes: ['class_declaration', 'method_declaration'] },
     csharp: { callTypes: ['invocation_expression'], calleeField: 'function', scopeTypes: ['class_declaration', 'method_declaration'] },
-    cpp: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_definition'] },
+    // @implements A-SPEC-287
+    // C++ listed only `function_definition`, so a member function's edges came out qualified as bare
+    // `run` while the symbol walk (which treats class_specifier/struct_specifier as scopes) emitted
+    // `Child.run`. The builder requires the caller to be a real node in that file, so EVERY C++ edge
+    // was dropped and the language contributed symbols and no edges at all. This is not a new rule —
+    // it is the rule this table's own comment states, which java and csharp already follow.
+    cpp: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['class_specifier', 'struct_specifier', 'function_definition'] },
 };
 // The callee's bare name: a plain identifier is itself; a member/selector/scoped/field node
 // (`o.m`, `self.c`, `mod::f`, `this.C`) unwraps to its LAST identifier segment — the method name.
@@ -515,6 +572,23 @@ function calleeNameOf(node) {
 // The shared table-driven edge walk. `from` is the enclosing definition's QUALIFIED name (so it
 // matches the symbol node id and can be resolved), `to` is the bare callee name. A call the config
 // cannot read emits nothing — never a guessed edge.
+// @implements A-SPEC-300
+// The receiver's type name for a Go method, descending through pointer and generic forms —
+// `(s Store)`, `(s *Store)`, `(s *Store[T])` all yield `Store`. Mirrors the symbol walk so edge
+// qualification and symbol qualification cannot drift apart.
+function goReceiverTypeName(methodDeclNode) {
+    const receiver = methodDeclNode.childForFieldName('receiver');
+    if (!receiver)
+        return null;
+    const paramDecl = receiver.namedChild(0);
+    let t = paramDecl && paramDecl.childForFieldName('type');
+    for (let hops = 0; t && hops < 5; hops++) {
+        if (t.type === 'type_identifier')
+            return t.text;
+        t = t.childForFieldName('type') ?? t.namedChild(0);
+    }
+    return null;
+}
 function walkEdges(tree, cfg) {
     const out = [];
     const scope = new Set(cfg.scopeTypes);
@@ -524,6 +598,21 @@ function walkEdges(tree, cfg) {
     // `declarator` fields to the first identifier — otherwise a C++ function's edges would qualify to
     // `<module>` and never resolve to its bare symbol name.
     const scopeName = (n) => {
+        // @implements A-SPEC-300
+        // Nodes whose qualifying name is NOT in a `name` field. `impl_item` has no name at all — the
+        // type it implements for lives in `type` — and a Go `method_declaration` has a `name`, but the
+        // symbol walk qualifies it by the receiver type, so using `name` here would disagree with the
+        // node ids that actually exist.
+        if (n.type === 'impl_item') {
+            const t = n.childForFieldName('type');
+            return t ? (t.childForFieldName('name')?.text ?? calleeNameOf(t) ?? t.text) : null;
+        }
+        if (n.type === 'method_declaration' && n.childForFieldName('receiver')) {
+            const recv = goReceiverTypeName(n);
+            const nm2 = n.childForFieldName('name');
+            if (recv && nm2)
+                return `${recv}.${nm2.text}`;
+        }
         const nm = n.childForFieldName('name');
         if (nm)
             return nm.text;
@@ -636,6 +725,26 @@ function extractEdgesFromTree(tree, lang = 'typescript') {
         return nm ? nm.text : null;
     };
     const visit = (node, scope) => {
+        if (node.type === 'class_declaration' || node.type === 'interface_declaration') {
+            // @implements A-SPEC-288
+            // `class Child extends Base` and `interface A extends B` are syntactically unambiguous, so
+            // this costs no precision. Only a plain identifier base is taken: `extends mixin(Base)` is
+            // computed and cannot be read statically, and `implements` is a different relation that this
+            // slice deliberately leaves out. Both stay gaps rather than guesses.
+            const nm = node.childForFieldName('name');
+            const heritage = (node.namedChildren ?? []).find((c) => c.type === 'class_heritage' || c.type === 'extends_type_clause');
+            if (nm && heritage) {
+                for (const clause of [heritage, ...(heritage.namedChildren ?? [])]) {
+                    if (clause.type === 'implements_clause')
+                        continue;
+                    for (const c of clause.namedChildren ?? []) {
+                        if (c.type === 'identifier' || c.type === 'type_identifier') {
+                            out.push({ from: nm.text, to: c.text, rel: 'inherits' });
+                        }
+                    }
+                }
+            }
+        }
         if (node.type === 'import_statement') {
             const src = node.childForFieldName('source') ?? (node.namedChildren && node.namedChildren.find((c) => c.type === 'string'));
             if (src)
@@ -673,6 +782,8 @@ function extractEdgesFromTree(tree, lang = 'typescript') {
         }
         const named = namedScopeOf(node);
         const childScope = named ? scope.concat(named) : scope;
+        // Type parameters are scoped to their declaration; collect them before descending so a use of
+        // `C` inside `function identity<C>(v: C)` is never mistaken for the contract `C`.
         for (let i = 0; i < node.childCount; i++)
             visit(node.child(i), childScope);
     };
@@ -719,7 +830,41 @@ function walkPythonEdges(tree) {
         return n.text;
     };
     const visit = (node) => {
-        if (node.type === 'import_statement') {
+        if (node.type === 'class_definition') {
+            // @implements A-SPEC-286
+            // `class Child(Base)` is syntactically unambiguous, so this costs no precision. Excluded:
+            // keyword arguments (`metaclass=Meta` is not a base) and starred/dynamic forms, which produce
+            // NOTHING rather than a guess — a wrong edge silently corrupts every impact answer that walks
+            // it, while a missing one shows up as a gap.
+            const name = node.childForFieldName('name');
+            const supers = node.childForFieldName('superclasses');
+            if (name && supers) {
+                for (const arg of supers.namedChildren ?? []) {
+                    if (arg.type === 'keyword_argument')
+                        continue;
+                    let base = null;
+                    if (arg.type === 'identifier')
+                        base = arg.text;
+                    // `mod.Base` -> `Base`, and `Generic[T]` -> `Generic`: same convention the call walk uses.
+                    else if (arg.type === 'attribute') {
+                        const a = arg.childForFieldName('attribute');
+                        base = a ? a.text : null;
+                    }
+                    else if (arg.type === 'subscript') {
+                        const v = arg.childForFieldName('value');
+                        if (v && v.type === 'identifier')
+                            base = v.text;
+                        else if (v && v.type === 'attribute') {
+                            const a = v.childForFieldName('attribute');
+                            base = a ? a.text : null;
+                        }
+                    }
+                    if (base)
+                        out.push({ from: enclosing(name), to: base, rel: 'inherits' });
+                }
+            }
+        }
+        else if (node.type === 'import_statement') {
             for (const c of node.namedChildren ?? []) {
                 const m = moduleName(c);
                 if (m)

package/dist/holmes/cpg/language-parser.d.ts

@@ -26,7 +26,7 @@ export interface CodeSymbol {
 export interface CodeEdge {
     from: string;
     to: string;
-    rel: 'calls' | 'imports';
+    rel: 'calls' | 'imports' | 'inherits';
 }
 export type TsLang = 'typescript' | 'tsx' | 'python' | 'csharp' | 'java' | 'go' | 'rust' | 'cpp';
 /**

package/dist/holmes/governance/ledger-rechain.d.ts

@@ -22,4 +22,16 @@ export type RechainResult = {
 } | {
     refused: string;
 };
+/**
+ * @implements A-SPEC-455
+ * Is the COMMITTED mainline a hash+seq prefix of the working copy?
+ *
+ * Exported so the turn boundary asks the same question the rechain CLI asks. It was inline here,
+ * and inline meant it ran only when an operator invoked a command — the fourth instance in one day
+ * of a judgement that is right and enforced in exactly one place.
+ *
+ * Duplicating it instead would be the mistake A-SPEC-449 measured: the config rule knew the
+ * copy/move family and the code rule did not, because the vocabulary lived in two copies.
+ */
+export declare function mainlineIsPrefix(mainline: ProvenanceEvent[], working: ProvenanceEvent[]): boolean;
 export declare function rechainLedger(mainline: ProvenanceEvent[], working: ProvenanceEvent[], key?: string): RechainResult;

package/dist/holmes/governance/ledger-rechain.js

@@ -2,6 +2,7 @@
 // @implements A-SPEC-256.1
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.acceptsAsMainline = acceptsAsMainline;
+exports.mainlineIsPrefix = mainlineIsPrefix;
 exports.rechainLedger = rechainLedger;
 /**
  * Re-chain a forked ledger against an EXPLICIT mainline — never a greedy one.
@@ -36,14 +37,28 @@ const bodyOf = (e) => {
     const { seq: _s, prevHash: _p, hash: _h, ...body } = e;
     return body;
 };
+/**
+ * @implements A-SPEC-455
+ * Is the COMMITTED mainline a hash+seq prefix of the working copy?
+ *
+ * Exported so the turn boundary asks the same question the rechain CLI asks. It was inline here,
+ * and inline meant it ran only when an operator invoked a command — the fourth instance in one day
+ * of a judgement that is right and enforced in exactly one place.
+ *
+ * Duplicating it instead would be the mistake A-SPEC-449 measured: the config rule knew the
+ * copy/move family and the code rule did not, because the vocabulary lived in two copies.
+ */
+function mainlineIsPrefix(mainline, working) {
+    return mainline.length <= working.length
+        && mainline.every((e, i) => working[i] !== undefined && working[i].hash === e.hash && working[i].seq === e.seq);
+}
 function rechainLedger(mainline, working, key) {
     // The working file is ALREADY-VERIFIED only when it verifies under the current key AND carries
     // the mainline as a hash-prefix (round-4): the adoption arm belongs to COMMITTED mainline
     // candidates only — applied to the working copy it certified a keyless re-signed replacement as
     // "no change" (reproduced forgery), and a rolled-back verifying prefix as "no change" (leaving
     // committed history unrestored — the working copy shorter than the committed mainline).
-    const mainlineIsPrefixOfWorking = mainline.length <= working.length
-        && mainline.every((e, i) => working[i] !== undefined && working[i].hash === e.hash && working[i].seq === e.seq);
+    const mainlineIsPrefixOfWorking = mainlineIsPrefix(mainline, working);
     if ((0, provenance_chain_1.verifyChain)(working, key).ok && mainlineIsPrefixOfWorking) {
         return { events: working, orphanCount: 0, alreadyVerified: true };
     }

package/dist/holmes/governance/provenance-ledger.js

@@ -183,6 +183,27 @@ class ProvenanceLedger {
             if (!r.ok)
                 broken.push({ replicaId: c.replicaId, file: c.file, detail: r.detail, brokenAt: r.brokenAt });
         }
+        // @implements A-SPEC-458
+        // Cross-replica double-spend. consumeNonceExclusively's lock is per-file, so two machines can
+        // each spend the same single-use nonce offline and the merge is chain-valid — each chain
+        // verifies. The comment there promised this is "DETECTED afterwards in the merged ledger";
+        // measured 2026-08-30, nothing did. A single-use nonce appearing in two `nonce-consumed`
+        // records is always a violation (REQ-141): there is no legitimate re-spend. Counted by the raw
+        // input value, the same rule isNonceConsumed matches on — one consume path writes one form, so
+        // a real double-spend records the same value twice.
+        const counts = new Map();
+        for (const e of this.loadAll()) {
+            if (e.kind !== 'nonce-consumed')
+                continue;
+            for (const inp of e.inputs ?? [])
+                counts.set(inp, (counts.get(inp) ?? 0) + 1);
+        }
+        for (const [nonce, n] of counts) {
+            if (n > 1) {
+                broken.push({ replicaId: null, file: '(cross-replica)',
+                    detail: `single-use nonce ${nonce.slice(0, 16)}… spent ${n} times across replicas — REQ-141 double-spend` });
+            }
+        }
         return { ok: broken.length === 0, broken };
     }
     /**

package/dist/holmes/guardrail/blind-spots.js

@@ -34,5 +34,16 @@ function blindSpotSummary() {
         // shell route to either state is denied by this gate; what remains is deletion from outside the
         // session, and saying so is the only honest option left.
         + ' `.ax` 전체가 세션 밖에서 삭제되면(에디터·Finder·세션 밖 git) 원장도 함께 사라져'
-        + ' 거버넌스를 켠 적 없는 프로젝트와 구별되지 않습니다 — `.ax/specs`만 사라진 경우는 탐지됩니다(REQ-175).';
+        + ' 거버넌스를 켠 적 없는 프로젝트와 구별되지 않습니다 — `.ax/specs`만 사라진 경우는 탐지됩니다(REQ-175).'
+        // @implements A-SPEC-421
+        // Measured against the INSTALLED build, which is the only place it shows: `tool_name: "Bash"`
+        // with `rm -rf /` is denied and `tool_name: "mcp__shell__run"` with the same command is allowed.
+        // The gate dispatches on the tool's NAME, so a name it does not know carries whatever it likes.
+        // Every MCP tool is such a name, and this repository itself runs several MCP servers — so this
+        // is the shape of the gap, not a hypothetical. Denying unknown names instead was considered and
+        // rejected: it would refuse every harness's Read, Grep and search tools and leave the guardrail
+        // unusable. What is fixable here is the map, and an undeclared gap reads as coverage.
+        + ' 게이트는 **도구 이름**으로 판정하므로 이름을 모르는 도구는 검사하지 않습니다 —'
+        + ' MCP 서버가 제공하는 도구(`mcp__<서버>__<도구>`)는 셸을 실행하더라도 이 게이트를 거치지'
+        + ' 않습니다. MCP 서버는 각자의 승인 경로로 통제하십시오.';
 }

package/dist/holmes/guardrail/impact-gate.d.ts

@@ -0,0 +1,77 @@
+import type { EvidenceArtifact } from '../mcp/maintenance-evidence';
+/**
+ * Pre-edit impact evidence — the decision core (Goal Phase 2, first slice).
+ *
+ * This module DECIDES; it does not enforce. Wiring it into the hook path is a separate slice, kept
+ * separate on purpose: a gate whose judgement and whose plumbing land together cannot be shown to
+ * have a correct judgement. Everything here is pure, so the same inputs always yield the same
+ * verdict and every branch is checkable against a fixture rather than against a live repository.
+ *
+ * The bias is fail-safe throughout. Where the evidence is silent the answer is `widen`, never
+ * `allow`: "we saw no impact" and "we could not look" are opposite claims, and only the first is a
+ * reason to proceed.
+ */
+export type EditDecision = 'allow' | 'widen' | 'refuse';
+export interface EditEvidenceReason {
+    code: 'no-analysis' | 'basis-drift' | 'target-out-of-scope' | 'contract-untested' | 'unproven-absence' | 'architecture-unchecked' | 'target-drift' | 'basis-unverifiable' | 'security-unchecked' | 'compatibility-unchecked';
+    detail: string;
+}
+export interface EditEvidenceInput {
+    /** Repo-relative path the session wants to edit. */
+    target: string;
+    /** The persisted analysis backing this edit, or null when none was produced. */
+    artifact: EvidenceArtifact | null;
+    /** HEAD as it is NOW — compared against the commit the analysis was computed on. */
+    currentHead: string;
+    /**
+     * @implements A-SPEC-277
+     * sha256 of the target AS IT IS NOW, or null when it cannot be read (deleted, or not yet created).
+     * Compared against the digest the analysis recorded, so an uncommitted edit to the analysed file
+     * is caught even while HEAD sits still.
+     */
+    currentTargetDigest?: string | null;
+}
+export interface EditEvidenceVerdict {
+    decision: EditDecision;
+    reasons: EditEvidenceReason[];
+    remediation: string;
+    /** True when the target qualified for the proportional low-risk path. */
+    lowRisk: boolean;
+}
+/**
+ * Documents are edited constantly and almost never break anything, so demanding a graph analysis for
+ * every prose change would train people to route around the gate — the proportional path exists to
+ * keep the gate credible where it matters. The exception is documents that GOVERN: an ADR or a
+ * C-SPEC is prose that decides architecture, and A-SPEC-233 already treats those as full-regression
+ * material. Same locations, read from the type table rather than spelled twice.
+ */
+export declare function isLowRiskTarget(target: string): boolean;
+export declare function evaluateEditEvidence(inputArgs: EditEvidenceInput): EditEvidenceVerdict;
+/**
+ * @implements A-SPEC-278
+ * The enforcement mode. `off` is the default and must be a TRUE no-op: a repository that never asked
+ * for this gate has to behave exactly as it did before, and a broken config falls back here too.
+ */
+export type PreEditEvidenceMode = 'off' | 'warn' | 'block';
+/**
+ * @implements A-SPEC-278
+ * Turn a verdict into a hook decision, or into silence.
+ *
+ * Silence — `null` — is deliberate for both `off` and a clean `allow`. Returning `allow` would still
+ * be an opinion: if this gate were ever consulted ahead of another, its `allow` could mask that
+ * gate's denial. A gate that has nothing to say should say nothing.
+ */
+export declare function preEditEvidenceDecision(verdict: EditEvidenceVerdict, mode: PreEditEvidenceMode): {
+    permissionDecision: 'allow' | 'deny';
+    permissionDecisionReason?: string;
+} | null;
+/**
+ * @implements A-SPEC-278
+ * The I/O adapter, kept apart from the pure core on purpose: everything above this line is decided
+ * by fixtures, and only this function touches a disk. It reads the artifact the session declared
+ * and measures the target's current content so the core can compare them.
+ *
+ * A digest that names no stored artifact yields `artifact: null` — the same shape as "no analysis",
+ * because from the gate's side an unfindable analysis and an absent one justify equally little.
+ */
+export declare function loadEditEvidence(projectRoot: string, target: string, digest: string | null, currentHead: string): EditEvidenceInput;