@holmes-lab/holmes-kit 0.2.1 → 0.3.0

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

@@ -0,0 +1,65 @@
+/**
+ * What the extractor actually recovers, per language.
+ *
+ * Goal Phase 4 requires that per-language coverage and its limits always travel with the result.
+ * They did not, and the capability is genuinely uneven — measured with fixtures 2026-08-28, symbols
+ * come out of every advertised language, `imports` only out of Python and TypeScript-family files,
+ * and `inherits` out of NONE of them, not even where the declaration is completely unambiguous
+ * (`class Child(Base)`, `extends Base`).
+ *
+ * The problem was never the unevenness; it was the silence. Coverage reported only extensions
+ * OUTSIDE the scannable set, so an impact answer over a Java file looked exactly as trustworthy as
+ * one over Python while resting on strictly less evidence, and every downstream answer inherited
+ * that asymmetry without anyone being told.
+ *
+ * This table is pinned against the real scanner by fixtures in the sibling test. If it drifts from
+ * reality in either direction that test fails — a capability table that cannot fail guarantees
+ * nothing.
+ */
+export declare const EXTRACTABLE_RELATIONS: readonly ["calls", "imports", "inherits"];
+export type ExtractableRelation = typeof EXTRACTABLE_RELATIONS[number];
+export interface LanguageCapability {
+    symbols: boolean;
+    /** What the SCANNER recovers from the source text. */
+    relations: ExtractableRelation[];
+    /**
+     * @implements A-SPEC-286
+     * What actually becomes a GRAPH edge — always a subset of `relations`.
+     *
+     * These are different claims and conflating them misleads. Measured 2026-08-28: the scanner emits
+     * 1,892 `imports` edges of which zero reach the graph, because their target is a module path
+     * rather than a symbol and the builder resolves symbol-to-symbol relations only. Everything
+     * downstream — impact, localization, the pre-edit gate — queries the graph, so the graph column is
+     * the one a coverage claim has to be made in.
+     */
+    graphResolved: ExtractableRelation[];
+}
+export declare const LANGUAGE_CAPABILITY: Record<string, LanguageCapability>;
+export declare function capabilityFor(ext: string): LanguageCapability | undefined;
+export interface LanguageGap {
+    ext: string;
+    /** Relation kinds this language's extractor does NOT recover at all. */
+    missing: ExtractableRelation[];
+    /**
+     * @implements A-SPEC-286
+     * Recovered by the scanner but never resolved into a graph edge. A distinct fact from `missing`:
+     * the information exists and is still unusable to anything that queries the graph.
+     */
+    extractedButUnresolved: ExtractableRelation[];
+}
+/**
+ * The capability gaps for the languages ACTUALLY present in a scan.
+ *
+ * Only languages that appear are listed: enumerating every language the tool could theoretically
+ * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
+ * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
+ */
+export declare function capabilityGapsFor(sourcePaths: readonly string[]): LanguageGap[];
+/** Every advertised extension must have an entry; a blank would be a silent overclaim. */
+export declare const ADVERTISED_EXTENSIONS: readonly string[];
+/**
+ * An unknown extension gets a family of its own rather than joining a shared bucket: an unfamiliar
+ * language must not be able to take another language's definitions. Narrowing is the safe direction
+ * — it costs recall, which is disclosed, instead of asserting something false.
+ */
+export declare function languageFamilyOf(ext: string): string;

package/dist/holmes/cpg/language-capability.js

@@ -0,0 +1,145 @@
+"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.ADVERTISED_EXTENSIONS = exports.LANGUAGE_CAPABILITY = exports.EXTRACTABLE_RELATIONS = void 0;
+exports.capabilityFor = capabilityFor;
+exports.capabilityGapsFor = capabilityGapsFor;
+exports.languageFamilyOf = languageFamilyOf;
+// @implements A-SPEC-289
+// @implements A-SPEC-288
+// @implements A-SPEC-287
+// @implements A-SPEC-286
+// @implements A-SPEC-285
+const path = __importStar(require("node:path"));
+const cpg_scanner_1 = require("./cpg-scanner");
+/**
+ * What the extractor actually recovers, per language.
+ *
+ * Goal Phase 4 requires that per-language coverage and its limits always travel with the result.
+ * They did not, and the capability is genuinely uneven — measured with fixtures 2026-08-28, symbols
+ * come out of every advertised language, `imports` only out of Python and TypeScript-family files,
+ * and `inherits` out of NONE of them, not even where the declaration is completely unambiguous
+ * (`class Child(Base)`, `extends Base`).
+ *
+ * The problem was never the unevenness; it was the silence. Coverage reported only extensions
+ * OUTSIDE the scannable set, so an impact answer over a Java file looked exactly as trustworthy as
+ * one over Python while resting on strictly less evidence, and every downstream answer inherited
+ * that asymmetry without anyone being told.
+ *
+ * This table is pinned against the real scanner by fixtures in the sibling test. If it drifts from
+ * reality in either direction that test fails — a capability table that cannot fail guarantees
+ * nothing.
+ */
+exports.EXTRACTABLE_RELATIONS = ['calls', 'imports', 'inherits'];
+// @implements A-SPEC-288 — `extends` joins Python's inheritance; `implements` stays a stated gap.
+// @implements A-SPEC-289 — imports now resolve to FILE nodes when the specifier is relative and
+// names a scanned file; bare specifiers stay external and unresolved by design.
+const TS_FAMILY = { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] };
+/** Symbols and calls only — no import edges, no inheritance. */
+const CALLS_ONLY = { symbols: true, relations: ['calls'], graphResolved: ['calls'] };
+exports.LANGUAGE_CAPABILITY = {
+    '.ts': TS_FAMILY, '.mts': TS_FAMILY, '.cts': TS_FAMILY, '.tsx': TS_FAMILY,
+    '.js': TS_FAMILY, '.mjs': TS_FAMILY, '.jsx': TS_FAMILY,
+    // CommonJS `require()` is not recovered as an import, unlike ESM `import` — measured.
+    '.cjs': CALLS_ONLY,
+    // @implements A-SPEC-286 — the first language whose inheritance is both extracted AND resolved.
+    '.py': { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] },
+    '.java': CALLS_ONLY, '.cs': CALLS_ONLY, '.go': CALLS_ONLY, '.rs': CALLS_ONLY,
+    // @implements A-SPEC-287 — C++ used to extract calls that never became graph edges, because its
+    // edge scope omitted the class node the symbol walk uses. Fixed; it now resolves like the others.
+    '.cpp': CALLS_ONLY, '.cc': CALLS_ONLY, '.cxx': CALLS_ONLY,
+    '.hpp': CALLS_ONLY, '.hh': CALLS_ONLY, '.h': CALLS_ONLY,
+};
+function capabilityFor(ext) {
+    return exports.LANGUAGE_CAPABILITY[ext.toLowerCase()];
+}
+/**
+ * The capability gaps for the languages ACTUALLY present in a scan.
+ *
+ * Only languages that appear are listed: enumerating every language the tool could theoretically
+ * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
+ * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
+ */
+function capabilityGapsFor(sourcePaths) {
+    const present = new Set();
+    for (const p of sourcePaths) {
+        const ext = path.extname(p).toLowerCase();
+        if (capabilityFor(ext))
+            present.add(ext);
+    }
+    return [...present].sort()
+        .map((ext) => {
+        const cap = capabilityFor(ext);
+        return {
+            ext,
+            missing: exports.EXTRACTABLE_RELATIONS.filter((r) => !cap.relations.includes(r)),
+            extractedButUnresolved: cap.relations.filter((r) => !cap.graphResolved.includes(r)),
+        };
+    })
+        .filter((gap) => gap.missing.length > 0 || gap.extractedButUnresolved.length > 0);
+}
+/** Every advertised extension must have an entry; a blank would be a silent overclaim. */
+exports.ADVERTISED_EXTENSIONS = cpg_scanner_1.SCANNABLE_EXTENSIONS;
+// @implements A-SPEC-300
+/**
+ * Extensions that can actually call each other, grouped.
+ *
+ * Name resolution links a call to a definition when the name is defined in exactly one file. That
+ * rule had no notion of language, and measured on a five-language fixture (2026-08-28) it asserted
+ *   CODE:Child.run@Child.java --calls--> CODE:helper@lib.rs
+ * A Java method calling a Rust function. Worse, the correct target sat in the SAME file: it was
+ * missed on qualification, leaving the Rust definition as the only candidate, so the precision rule
+ * actively confirmed a wrong answer. A missing edge widens scope; a wrong edge narrows it onto the
+ * wrong place.
+ *
+ * The groups follow real interop, not file-name similarity: TypeScript and JavaScript genuinely call
+ * each other, and a C++ implementation genuinely calls its header's declarations.
+ */
+const LANGUAGE_FAMILIES = {
+    '.ts': 'ts-js', '.mts': 'ts-js', '.cts': 'ts-js', '.tsx': 'ts-js',
+    '.js': 'ts-js', '.mjs': 'ts-js', '.jsx': 'ts-js', '.cjs': 'ts-js',
+    '.py': 'python',
+    '.java': 'java', '.cs': 'csharp', '.go': 'go', '.rs': 'rust',
+    '.cpp': 'cpp', '.cc': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp', '.h': 'cpp',
+};
+/**
+ * An unknown extension gets a family of its own rather than joining a shared bucket: an unfamiliar
+ * language must not be able to take another language's definitions. Narrowing is the safe direction
+ * — it costs recall, which is disclosed, instead of asserting something false.
+ */
+function languageFamilyOf(ext) {
+    const lower = ext.toLowerCase();
+    return LANGUAGE_FAMILIES[lower] ?? `ext:${lower}`;
+}

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 서버는 각자의 승인 경로로 통제하십시오.';
 }