@holmes-lab/holmes-kit 0.3.10 → 0.4.0

package/dist/holmes/cpg/foundation/language-matrix.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATRIX_LANGUAGES = exports.LAYERS = void 0;
+exports.languageMatrix = languageMatrix;
+exports.renderLanguageSupport = renderLanguageSupport;
+// @implements A-SPEC-510.6
+/**
+ * The layer × language support matrix — what "officially supported" MEANS, made checkable.
+ *
+ * Every cell is DERIVED from the module that owns the capability, never restated here: a
+ * hand-written table is a second truth, and a second truth drifts (this repository has the
+ * scars — `wiring presence is not enforcement`, the codex parity gap, the moving baseline pin).
+ * So the matrix reads AST_LANGUAGES, CFG_LANGUAGES, LANGUAGE_CAPABILITY, hasDataFlowWalk and
+ * ecosystemOf, and `docs/language-support.md` is a RENDER of this function, pinned byte-identical
+ * by a test. Adding a language or a layer changes exactly one place: the owning module.
+ *
+ * The `relations` row keeps A-SPEC-286's doctrine intact — a capability claim is made in the
+ * GRAPH-RESOLVED column, because everything downstream queries the graph, not the scanner's
+ * intermediate output.
+ */
+const ast_store_1 = require("./ast-store");
+const cfg_1 = require("./cfg");
+const language_capability_1 = require("../language-capability");
+const language_parser_1 = require("../language-parser");
+const test_runner_1 = require("../../review/test-runner");
+exports.LAYERS = ['relations', 'ast', 'cfg', 'ddg', 'cdg', 'runner', 'taint'];
+/** The language families holmes-kit advertises, each with the probe inputs the derivation needs. */
+exports.MATRIX_LANGUAGES = [
+    { lang: 'typescript', label: 'TypeScript / JavaScript', ext: '.ts', astLang: 'typescript', sampleFile: 'x.test.ts' },
+    { lang: 'python', label: 'Python', ext: '.py', astLang: 'python', sampleFile: 'test_x.py' },
+    { lang: 'csharp', label: 'C#', ext: '.cs', astLang: 'csharp', sampleFile: 'XTest.cs' },
+    { lang: 'java', label: 'Java', ext: '.java', astLang: 'java', sampleFile: 'XTest.java' },
+    { lang: 'go', label: 'Go', ext: '.go', astLang: 'go', sampleFile: 'x_test.go' },
+    { lang: 'rust', label: 'Rust', ext: '.rs', astLang: 'rust', sampleFile: 'tests/x.rs' },
+    { lang: 'cpp', label: 'C++', ext: '.cpp', astLang: 'cpp', sampleFile: 'x_test.cpp' },
+];
+const AST_LANG_SET = new Set(ast_store_1.AST_LANGUAGES.map((l) => l.lang));
+function relationsCell(ext) {
+    const cap = language_capability_1.LANGUAGE_CAPABILITY[ext];
+    if (!cap)
+        return { support: 'none', basis: 'not in LANGUAGE_CAPABILITY' };
+    const resolved = cap.graphResolved;
+    if (resolved.length === 0)
+        return { support: 'none', basis: 'nothing reaches the graph' };
+    // A-SPEC-286: the claim is made in the graph-resolved column, never the scanner's raw output.
+    return resolved.length >= 3
+        ? { support: 'full', basis: `graph edges: ${resolved.join(', ')}` }
+        : { support: 'partial', basis: `graph edges: ${resolved.join(', ')} (no imports/inherits)` };
+}
+function astCell(astLang) {
+    // The TS grammar family covers tsx/js too — AST_LANGUAGES is the authority on which wasm applies.
+    const covered = AST_LANG_SET.has(astLang) || (astLang === 'typescript' && AST_LANG_SET.has('tsx'));
+    return covered
+        ? { support: 'full', basis: 'vendored tree-sitter grammar (L1 AST persisted)' }
+        : { support: 'none', basis: 'no vendored grammar for the L1 substrate' };
+}
+function cfgFamilyCell(astLang, layer) {
+    const covered = cfg_1.CFG_LANGUAGES.has(astLang) || (astLang === 'typescript' && cfg_1.CFG_LANGUAGES.has('tsx'));
+    const what = layer === 'cfg' ? 'control flow + dominators'
+        : layer === 'ddg' ? 'reaching definitions (REACHING_DEF)'
+            : 'control dependence (CDG)';
+    return covered
+        ? { support: 'full', basis: `${what}, statement granularity` }
+        : { support: 'none', basis: `${what} not lowered for this language yet` };
+}
+function runnerCell(sampleFile) {
+    const eco = (0, test_runner_1.ecosystemOf)(sampleFile);
+    return eco
+        ? { support: 'full', basis: `test runner adapter: ${eco}` }
+        : { support: 'none', basis: 'no test-runner adapter — execution evidence unavailable' };
+}
+function taintCell(astLang) {
+    const has = (0, language_parser_1.hasDataFlowWalk)(astLang);
+    return has
+        ? { support: 'full', basis: 'data-flow walk present (taint_scan analyses this language)' }
+        : { support: 'none', basis: 'no data-flow walk — taint_scan does not analyse this language' };
+}
+// @implements A-SPEC-510.6
+/** Derive the whole matrix. Pure, cheap, and impossible to drift from its sources. */
+function languageMatrix() {
+    const out = {};
+    for (const layer of exports.LAYERS)
+        out[layer] = {};
+    for (const { lang, ext, astLang, sampleFile } of exports.MATRIX_LANGUAGES) {
+        out.relations[lang] = relationsCell(ext);
+        out.ast[lang] = astCell(astLang);
+        out.cfg[lang] = cfgFamilyCell(astLang, 'cfg');
+        out.ddg[lang] = cfgFamilyCell(astLang, 'ddg');
+        out.cdg[lang] = cfgFamilyCell(astLang, 'cdg');
+        out.runner[lang] = runnerCell(sampleFile);
+        out.taint[lang] = taintCell(astLang);
+    }
+    return out;
+}
+const LAYER_DOC = {
+    relations: 'L0 — symbols and relations that actually become RTM graph edges',
+    ast: 'L1 — lossless-span AST, persisted (tree-sitter wasm substrate)',
+    cfg: 'L2 — control-flow graph with dominator / post-dominator trees',
+    ddg: 'L3 — data dependence (reaching definitions, REACHING_DEF edges)',
+    cdg: 'L3 — control dependence (CDG edges); PDG = DDG ∪ CDG',
+    runner: 'test_run — executes this language\'s suites for ART-4 execution evidence',
+    taint: 'taint_scan — data-flow walk for source→sink analysis',
+};
+const MARK = { full: '●', partial: '◐', none: '○' };
+// @implements A-SPEC-510.6
+/** Render docs/language-support.md — the table is a PRODUCT of the code, not a claim beside it. */
+function renderLanguageSupport() {
+    const m = languageMatrix();
+    const head = `| Layer | ${exports.MATRIX_LANGUAGES.map((l) => l.label).join(' | ')} |`;
+    const sep = `|---|${exports.MATRIX_LANGUAGES.map(() => '---').join('|')}|`;
+    const rows = exports.LAYERS.map((layer) => `| **${layer}** | ${exports.MATRIX_LANGUAGES.map((l) => MARK[m[layer][l.lang].support]).join(' | ')} |`);
+    const bases = exports.LAYERS.flatMap((layer) => exports.MATRIX_LANGUAGES.map((l) => `- \`${layer}\` / ${l.label}: **${m[layer][l.lang].support}** — ${m[layer][l.lang].basis}`));
+    return [
+        '<!-- GENERATED by renderLanguageSupport() (A-SPEC-510.6). Do not edit by hand:',
+        '     every cell is derived from the module that owns the capability, and a test pins this',
+        '     file byte-identical to the render. Regenerate: `node scripts/render-language-support.js`. -->',
+        '# Language support matrix',
+        '',
+        'Legend: ● full · ◐ partial · ○ none',
+        '',
+        head,
+        sep,
+        ...rows,
+        '',
+        '## What each layer means',
+        '',
+        ...exports.LAYERS.map((l) => `- **${l}** — ${LAYER_DOC[l]}`),
+        '',
+        '## Per-cell basis',
+        '',
+        ...bases,
+        '',
+    ].join('\n');
+}

package/dist/holmes/cpg/foundation/substrate-census.d.ts

@@ -0,0 +1,36 @@
+/** The construct corpus — file name ↔ construct, the single truth the boundary test pins. */
+export declare const CONSTRUCT_FIXTURES: ReadonlyArray<{
+    file: string;
+    construct: string;
+}>;
+export declare const FIXTURES_DIR: string;
+export interface CensusRow {
+    file: string;
+    construct: string;
+    /** Symbols the current substrate extracted from this fixture (0 = the construct is invisible). */
+    symbols: number;
+    /** Call/import/inherit relations recovered. */
+    edges: number;
+    /** Every extracted symbol carries line-level start/end. Column-level spans do not exist yet. */
+    lineSpans: boolean;
+    /** AST node count under the new substrate (visibility even where `symbols` froze at 0). */
+    astNodes?: number;
+    /** ERROR/missing nodes under the new substrate — 0 across the corpus is the L1 bar. */
+    astErrors?: number;
+}
+/**
+ * Scan EXACTLY the fixture corpus with the current substrate. Pure with respect to everything
+ * outside `dir` — files not named by CONSTRUCT_FIXTURES never enter the table, so a decoy planted
+ * beside the corpus cannot inflate or pollute the envelope.
+ */
+export declare function substrateCensus(dir?: string): CensusRow[];
+/**
+ * The census with the new-substrate columns filled in — the decision table's two arms side by
+ * side. Loads the wasm substrate lazily (never at import), so consumers that only need the old
+ * columns keep paying nothing.
+ */
+export declare function fullCensus(dir?: string): Promise<CensusRow[]>;
+/** The failures, by name — the honest half of the envelope (what the substrate cannot see). */
+export declare function invisibleConstructs(rows?: CensusRow[]): string[];
+/** Ensure fs is a declared dependency of this module's contract (fixture existence check). */
+export declare function fixturesPresent(dir?: string): boolean;

package/dist/holmes/cpg/foundation/substrate-census.js

@@ -0,0 +1,135 @@
+"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.FIXTURES_DIR = exports.CONSTRUCT_FIXTURES = void 0;
+exports.substrateCensus = substrateCensus;
+exports.fullCensus = fullCensus;
+exports.invisibleConstructs = invisibleConstructs;
+exports.fixturesPresent = fixturesPresent;
+// @implements A-SPEC-510.1
+/**
+ * The substrate census — the ONE table both the decision report and the regression tests consume.
+ *
+ * S-510.1 freezes the CURRENT hand-rolled parser's extraction outcome over a construct corpus
+ * (one tricky language construct per fixture file). The table is an honest envelope, not a
+ * scoreboard: a construct the parser cannot see is recorded as a failure, because an all-green
+ * census would be the envelope lying, not coverage. Every later substrate change (.2+) must move
+ * this table VISIBLY — updating it is how progress gets recorded.
+ *
+ * Line-level spans only: the current CodeSymbol carries startLine/endLine and no columns, so
+ * `spans` here asserts line presence — lossless round-trip is exactly what the current substrate
+ * cannot do, and that fact belongs in the decision report.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const cpg_scanner_1 = require("../cpg-scanner");
+/** The construct corpus — file name ↔ construct, the single truth the boundary test pins. */
+exports.CONSTRUCT_FIXTURES = [
+    { file: 'class-features.ts', construct: 'class: private field, getter/setter, static block' },
+    { file: 'generics.ts', construct: 'generics: constrained type params, generic class/alias' },
+    { file: 'async-await.ts', construct: 'async/await function + async arrow' },
+    { file: 'generators.ts', construct: 'generator + async generator' },
+    { file: 'optional-chaining.ts', construct: 'optional chaining / nullish coalescing / optional call' },
+    { file: 'switch-fallthrough.ts', construct: 'switch with fallthrough cases' },
+    { file: 'try-catch-finally.ts', construct: 'try/catch/finally with rethrow' },
+    { file: 'labeled-break.ts', construct: 'labeled break/continue' },
+    { file: 'nested-arrows.ts', construct: 'curried nested arrow functions' },
+    { file: 'destructuring.ts', construct: 'nested destructuring with defaults and rest' },
+    { file: 'enum-namespace.ts', construct: 'enum + namespace' },
+    { file: 'jsx-component.tsx', construct: 'JSX element in a .tsx component' },
+    { file: 'dynamic-import.ts', construct: 'dynamic import()' },
+    { file: 'async_def.py', construct: 'python: async def / await' },
+    { file: 'generators_yield_from.py', construct: 'python: generator + yield from' },
+    { file: 'comprehensions.py', construct: 'python: nested list/dict/set comprehensions' },
+    { file: 'decorators_args.py', construct: 'python: parameterized decorator + wraps' },
+    { file: 'match_case.py', construct: 'python: match/case with or- and mapping-patterns' },
+    { file: 'with_multi.py', construct: 'python: multi-item with statement' },
+    { file: 'walrus.py', construct: 'python: walrus operator in condition' },
+    { file: 'try_except_else_finally.py', construct: 'python: try/except/else/finally' },
+    { file: 'lambdas.py', construct: 'python: lambda returning lambda' },
+    { file: 'global_nonlocal.py', construct: 'python: global + nonlocal in closure' },
+];
+// Fixtures are DATA, not code: excluded from tsc (a .tsx parse target must not need the build's
+// JSX config), so `dist` carries no copy — a dist-resolved consumer falls back to the src corpus.
+const srcFallback = path.join(__dirname, 'fixtures').replace(`${path.sep}dist${path.sep}`, `${path.sep}src${path.sep}`);
+exports.FIXTURES_DIR = fs.existsSync(path.join(__dirname, 'fixtures'))
+    ? path.join(__dirname, 'fixtures')
+    : srcFallback;
+/**
+ * Scan EXACTLY the fixture corpus with the current substrate. Pure with respect to everything
+ * outside `dir` — files not named by CONSTRUCT_FIXTURES never enter the table, so a decoy planted
+ * beside the corpus cannot inflate or pollute the envelope.
+ */
+function substrateCensus(dir = exports.FIXTURES_DIR) {
+    const scanned = new cpg_scanner_1.CpgScanner().scan(dir, dir);
+    const byBase = new Map(scanned.map((f) => [path.basename(f.path), f]));
+    return exports.CONSTRUCT_FIXTURES.map(({ file, construct }) => {
+        const f = byBase.get(file);
+        const symbols = f?.symbols ?? [];
+        return {
+            file,
+            construct,
+            symbols: symbols.length,
+            edges: f?.edges?.length ?? 0,
+            lineSpans: symbols.length > 0 && symbols.every((s) => s.startLine > 0 && s.endLine >= s.startLine),
+        };
+    });
+}
+// @implements A-SPEC-510.2
+/**
+ * The census with the new-substrate columns filled in — the decision table's two arms side by
+ * side. Loads the wasm substrate lazily (never at import), so consumers that only need the old
+ * columns keep paying nothing.
+ */
+async function fullCensus(dir = exports.FIXTURES_DIR) {
+    const { parseAst } = await Promise.resolve().then(() => __importStar(require('./ast-store')));
+    const rows = substrateCensus(dir);
+    for (const row of rows) {
+        const ast = await parseAst(fs.readFileSync(path.join(dir, row.file), 'utf8'), row.file);
+        if (ast) {
+            row.astNodes = ast.nodes.length;
+            row.astErrors = ast.errorCount;
+        }
+    }
+    return rows;
+}
+/** The failures, by name — the honest half of the envelope (what the substrate cannot see). */
+function invisibleConstructs(rows = substrateCensus()) {
+    return rows.filter((r) => r.symbols === 0).map((r) => r.file);
+}
+/** Ensure fs is a declared dependency of this module's contract (fixture existence check). */
+function fixturesPresent(dir = exports.FIXTURES_DIR) {
+    return exports.CONSTRUCT_FIXTURES.every(({ file }) => fs.existsSync(path.join(dir, file)));
+}

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

@@ -69,6 +69,21 @@ exports.EXTRACTABLE_RELATIONS = ['calls', 'imports', 'inherits'];
 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'] };
+// @implements A-SPEC-511.1
+/**
+ * Calls AND inheritance. The five non-TS/Python languages moved here once their inheritance was
+ * actually recovered AND measured arriving in the graph (S-510.6's corpus proved the gap; this is
+ * the repair). Imports stay out on purpose: their targets are package specifiers, which the
+ * resolver cannot turn into a scanned FILE node, so extracting them would widen `relations`
+ * without widening `graphResolved` — the exact conflation A-SPEC-286 forbids.
+ *
+ * Go's cell carries a stated limit: only STRUCT EMBEDDING is recovered. Interface satisfaction in
+ * Go is implicit and structural, so naming it would need a type checker; holmes-kit declares the
+ * gap instead of guessing it.
+ */
+const CALLS_AND_INHERITS = {
+    symbols: true, relations: ['calls', 'inherits'], graphResolved: ['calls', 'inherits'],
+};
 exports.LANGUAGE_CAPABILITY = {
     '.ts': TS_FAMILY, '.mts': TS_FAMILY, '.cts': TS_FAMILY, '.tsx': TS_FAMILY,
     '.js': TS_FAMILY, '.mjs': TS_FAMILY, '.jsx': TS_FAMILY,
@@ -76,11 +91,14 @@ exports.LANGUAGE_CAPABILITY = {
     '.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-511.1 — inheritance recovered: Java extends/implements, C# base_list,
+    // Go struct embedding (interface satisfaction is a declared permanent gap), Rust `impl T for S`.
+    '.java': CALLS_AND_INHERITS, '.cs': CALLS_AND_INHERITS, '.go': CALLS_AND_INHERITS, '.rs': CALLS_AND_INHERITS,
     // @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,
+    // @implements A-SPEC-511.1 — base_class_clause recovered (access specifiers skipped).
+    '.cpp': CALLS_AND_INHERITS, '.cc': CALLS_AND_INHERITS, '.cxx': CALLS_AND_INHERITS,
+    '.hpp': CALLS_AND_INHERITS, '.hh': CALLS_AND_INHERITS, '.h': CALLS_AND_INHERITS,
 };
 function capabilityFor(ext) {
     return exports.LANGUAGE_CAPABILITY[ext.toLowerCase()];

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

@@ -534,22 +534,41 @@ const EDGE_CONFIG = {
     // 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'] },
+    // @implements A-SPEC-511.1 — `inherits` for Go is STRUCT EMBEDDING only: an embedded field is a
+    // syntactic fact. Interface satisfaction is implicit and structural (no `implements` keyword), so
+    // recovering it needs a type checker — a DECLARED PERMANENT LIMIT, never a guess.
+    go: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_declaration', 'method_declaration'],
+        inherits: { declTypes: ['type_spec'], mode: 'go-embedding' } },
     // @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'] },
+    // @implements A-SPEC-511.1 — `impl Trait for Type` ⇒ Type inherits Trait (implementer → abstract).
+    // An inherent `impl Type { … }` carries no trait field and is NOT inheritance: no edge.
+    rust: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_item', 'impl_item', 'trait_item'],
+        inherits: { declTypes: ['impl_item'], mode: 'rust-impl' } },
+    // @implements A-SPEC-511.1 — Java separates the two syntactically, and BOTH are inheritance edges:
+    // `superclass` (extends) and `super_interfaces` (implements), plus an interface's own extends.
+    java: { callTypes: ['method_invocation'], calleeField: 'name', scopeTypes: ['class_declaration', 'method_declaration'],
+        inherits: { declTypes: ['class_declaration', 'interface_declaration', 'record_declaration', 'enum_declaration'],
+            fields: ['superclass', 'super_interfaces', 'interfaces', 'extends_interfaces'] } },
+    // @implements A-SPEC-511.1 — C# puts the base class AND the interfaces in ONE `base_list`, with no
+    // syntactic marker telling them apart. Splitting them would be a guess, so BOTH become `inherits`
+    // (a deliberate asymmetry with the TS walk, which emits extends only — H-SPEC-511 decision 1).
+    csharp: { callTypes: ['invocation_expression'], calleeField: 'function', scopeTypes: ['class_declaration', 'method_declaration'],
+        inherits: { declTypes: ['class_declaration', 'interface_declaration', 'struct_declaration', 'record_declaration'],
+            childTypes: ['base_list'] } },
     // @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'] },
+    // @implements A-SPEC-511.1 — C++ bases live in `base_class_clause`; access specifiers
+    // (public/private/protected/virtual) are skipped and only the type name is taken.
+    cpp: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['class_specifier', 'struct_specifier', 'function_definition'],
+        inherits: { declTypes: ['class_specifier', 'struct_specifier'], childTypes: ['base_class_clause'] } },
 };
 // 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.
@@ -589,6 +608,33 @@ function goReceiverTypeName(methodDeclNode) {
     }
     return null;
 }
+// @implements A-SPEC-511.1
+// A base type's NAME, normalized the way every other consumer expects: generic/template arguments
+// dropped (`Base<T>` → `Base`), path qualifiers reduced to the last segment (`ns::Base`,
+// `pkg.Base` → `Base`) — the same convention the Python attribute/subscript walk already uses.
+// A computed or dependent base yields null: an unreadable base stays a gap, never a guess.
+function baseTypeNameOf(node) {
+    if (!node)
+        return null;
+    const t = node.type;
+    if (t === 'identifier' || t === 'type_identifier' || t === 'field_identifier')
+        return node.text;
+    if (t === 'generic_type' || t === 'scoped_type_identifier' || t === 'qualified_identifier'
+        || t === 'scoped_identifier' || t === 'template_type' || t === 'qualified_type'
+        || t === 'type_arguments' || t === 'generic_name' || t === 'qualified_name') {
+        // Take the LAST identifier-ish child that is not inside the argument list.
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const c = node.namedChild(i);
+            if (c.type === 'type_arguments' || c.type === 'template_argument_list')
+                continue;
+            const n = baseTypeNameOf(c);
+            if (n)
+                return n;
+        }
+        return null;
+    }
+    return null;
+}
 function walkEdges(tree, cfg) {
     const out = [];
     const scope = new Set(cfg.scopeTypes);
@@ -639,12 +685,93 @@ function walkEdges(tree, cfg) {
         }
         return parts.length ? parts.join('.') : '<module>';
     };
+    // @implements A-SPEC-511.1
+    // Inheritance, table-driven per language. `from` is the declaring type's qualified name (the same
+    // id the symbol walk emits, so the builder can resolve it); `to` is the normalized base name.
+    const inh = cfg.inherits;
+    const declTypes = new Set(inh ? inh.declTypes : []);
+    const emitInherits = (node) => {
+        const selfName = scopeName(node);
+        // A clause reachable BOTH as a field and as a named child (Java's interfaces/super_interfaces)
+        // would otherwise emit each base twice; dedupe per declaration, not globally, so two classes
+        // inheriting the same base still produce two edges.
+        const seenHere = new Set();
+        const push = (target) => {
+            const to = baseTypeNameOf(target);
+            if (!to || !selfName || to === selfName || seenHere.has(to))
+                return;
+            seenHere.add(to);
+            out.push({ from: selfName, to, rel: 'inherits' });
+        };
+        if (inh.mode === 'rust-impl') {
+            // `impl Trait for Type`: the trait field only exists on a trait impl; inherent impls have none.
+            const trait = node.childForFieldName('trait');
+            if (trait)
+                push(trait);
+            return;
+        }
+        if (inh.mode === 'go-embedding') {
+            // `type A struct { B }` — an embedded field is a field_declaration with a type and NO name.
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const st = node.namedChild(i);
+                if (st.type !== 'struct_type')
+                    continue;
+                for (let j = 0; j < st.namedChildCount; j++) {
+                    const fl = st.namedChild(j);
+                    if (fl.type !== 'field_declaration_list')
+                        continue;
+                    for (let k = 0; k < fl.namedChildCount; k++) {
+                        const fd = fl.namedChild(k);
+                        if (fd.type !== 'field_declaration' || fd.childForFieldName('name'))
+                            continue;
+                        push(fd.childForFieldName('type'));
+                    }
+                }
+            }
+            return;
+        }
+        // A clause wraps its targets one or two levels deep depending on the grammar: Java's
+        // `interfaces` field yields a `super_interfaces` node holding a `type_list` (measured), while
+        // `superclass` holds the type directly. Descend until a name is readable — but only through
+        // wrapper nodes, never into type arguments (baseTypeNameOf owns that rule).
+        const pushDeep = (n, depth = 0) => {
+            if (!n)
+                return;
+            if (baseTypeNameOf(n)) {
+                push(n);
+                return;
+            }
+            if (depth >= 3)
+                return;
+            for (let i = 0; i < n.namedChildCount; i++)
+                pushDeep(n.namedChild(i), depth + 1);
+        };
+        for (const field of inh.fields ?? [])
+            pushDeep(node.childForFieldName(field));
+        for (const childType of inh.childTypes ?? []) {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const c = node.namedChild(i);
+                if (c.type === childType)
+                    pushDeep(c);
+            }
+        }
+        // Some grammars expose the clause only as a NAMED CHILD (Java's `super_interfaces`,
+        // `extends_interfaces`) rather than through a field — cover both spellings.
+        for (const field of inh.fields ?? []) {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                if (node.namedChild(i).type === field)
+                    pushDeep(node.namedChild(i));
+            }
+        }
+    };
     const visit = (node) => {
         if (callTypes.has(node.type)) {
             const callee = calleeNameOf(node.childForFieldName(cfg.calleeField));
             if (callee)
                 out.push({ from: enclosing(node), to: callee, rel: 'calls' });
         }
+        if (inh && declTypes.has(node.type))
+            emitInherits(node);
         for (let i = 0; i < node.childCount; i++)
             visit(node.child(i));
     };

package/dist/holmes/governance/push-gate.d.ts

@@ -32,6 +32,9 @@ export declare function judgePush(input: PushJudgeInput): PushVerdict;
 /**
  * The pre-push stdin format: `<local ref> <local sha> <remote ref> <remote sha>` per line.
  * A deletion push (all-zero local sha) deletes a remote ref — there is nothing to vouch for.
+ * Only BRANCH refs (refs/heads/) are judged: the gate guards the moment a code line becomes
+ * someone's baseline, and a tag merely NAMES an existing commit — dogfooded 2026-09-01, pushing
+ * v0.3.9 (an ancestor of the evidenced tip) was refused by the exact-head rule until this line.
  */
 export declare function parsePushLines(stdinText: string): Array<{
     localSha: string;

package/dist/holmes/governance/push-gate.js

@@ -50,6 +50,9 @@ function flatSubject(s) {
 /**
  * The pre-push stdin format: `<local ref> <local sha> <remote ref> <remote sha>` per line.
  * A deletion push (all-zero local sha) deletes a remote ref — there is nothing to vouch for.
+ * Only BRANCH refs (refs/heads/) are judged: the gate guards the moment a code line becomes
+ * someone's baseline, and a tag merely NAMES an existing commit — dogfooded 2026-09-01, pushing
+ * v0.3.9 (an ancestor of the evidenced tip) was refused by the exact-head rule until this line.
  */
 function parsePushLines(stdinText) {
     const out = [];
@@ -57,7 +60,9 @@ function parsePushLines(stdinText) {
         const parts = line.trim().split(/\s+/);
         if (parts.length !== 4)
             continue;
-        const [, localSha, , remoteSha] = parts;
+        const [localRef, localSha, , remoteSha] = parts;
+        if (!localRef.startsWith('refs/heads/'))
+            continue; // tags/notes: names, not baselines
         if (!/^[0-9a-f]{40}$/.test(localSha))
             continue;
         if (/^0{40}$/.test(localSha))

package/grammars/manifest.json

@@ -0,0 +1,23 @@
+{
+  "webTreeSitter": "0.27.0",
+  "grammars": [
+    {
+      "file": "tree-sitter-typescript.wasm",
+      "package": "tree-sitter-typescript",
+      "packageVersion": "0.23.2",
+      "sha256": "778025db5a8be0e70f8ccc3671e486dfeddd048c25d9e8a70c26de2e1bf6f97d"
+    },
+    {
+      "file": "tree-sitter-tsx.wasm",
+      "package": "tree-sitter-typescript",
+      "packageVersion": "0.23.2",
+      "sha256": "79e5da75ea62855a0cd67177685f0164eac87d5f630b3cbe1e0a099751ad30f8"
+    },
+    {
+      "file": "tree-sitter-python.wasm",
+      "package": "tree-sitter-python",
+      "packageVersion": "0.25.0",
+      "sha256": "16108b50df4ee9a30168794252ab55e7c93bfc5765d7fa0aa3e335752c515f47"
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -12,6 +12,7 @@
   "files": [
     "bin/",
     "dist/",
+    "grammars/",
     "playbooks/",
     "scripts/install.ps1",
     "docs/install-guide.md",
@@ -68,7 +69,8 @@
     "tree-sitter-python": "^0.21.0",
     "tree-sitter-rust": "^0.21.0",
     "tree-sitter-typescript": "^0.21.2",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "web-tree-sitter": "0.27.0"
   },
   "repository": {
     "type": "git",