gitnexus 1.6.3-rc.31 → 1.6.3-rc.33

package/dist/core/graph/graph.js

@@ -1,28 +1,113 @@
+/** Fresh empty iterator per call — `[].values()` returns a new
+ *  exhausted iterator each invocation, so empty-type lookups don't
+ *  share a single already-exhausted iterator across callers. */
+function emptyRelIter() {
+    return [].values();
+}
 export const createKnowledgeGraph = () => {
     const nodeMap = new Map();
     const relationshipMap = new Map();
+    // Per-type index maintained alongside `relationshipMap`. Bucket
+    // values are `Map<id, Relationship>` so per-type iteration is cheap
+    // and per-edge removal is O(1). See plan
+    // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 1).
+    const relationshipsByType = new Map();
+    // Reverse-adjacency index: nodeId → Set<relId> of every edge where
+    // this node appears as source OR target. Maintained on writeRel /
+    // deleteRel so `removeNode` can delete a node's edges in
+    // O(edges-touching-node) instead of O(total-edges).
+    const edgeIdsByNode = new Map();
+    // File index: filePath → Set<nodeId>. Maintained on addNode /
+    // removeNode so `removeNodesByFile` reaches its file's nodes
+    // directly instead of scanning the whole node map.
+    const nodeIdsByFile = new Map();
+    // Private helpers that encode the dual-index invariants in one
+    // place. All mutation paths go through these — adding a new
+    // mutation method only needs to call the helper, not remember to
+    // touch every index.
+    const addToBucket = (map, key, value) => {
+        let bucket = map.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            map.set(key, bucket);
+        }
+        bucket.add(value);
+    };
+    const removeFromBucket = (map, key, value) => {
+        const bucket = map.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(value);
+        if (bucket.size === 0)
+            map.delete(key);
+    };
+    const writeRel = (rel) => {
+        relationshipMap.set(rel.id, rel);
+        let typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket === undefined) {
+            typeBucket = new Map();
+            relationshipsByType.set(rel.type, typeBucket);
+        }
+        typeBucket.set(rel.id, rel);
+        addToBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        // Guard against a self-edge writing the same rel.id into the
+        // same Set twice — Set dedup handles it, but we skip explicitly
+        // for clarity.
+        if (rel.targetId !== rel.sourceId) {
+            addToBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
+    const deleteRel = (rel) => {
+        relationshipMap.delete(rel.id);
+        const typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket !== undefined) {
+            typeBucket.delete(rel.id);
+            if (typeBucket.size === 0)
+                relationshipsByType.delete(rel.type);
+        }
+        removeFromBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        if (rel.targetId !== rel.sourceId) {
+            removeFromBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
     const addNode = (node) => {
-        if (!nodeMap.has(node.id)) {
-            nodeMap.set(node.id, node);
+        if (nodeMap.has(node.id))
+            return;
+        nodeMap.set(node.id, node);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            addToBucket(nodeIdsByFile, filePath, node.id);
         }
     };
     const addRelationship = (relationship) => {
-        if (!relationshipMap.has(relationship.id)) {
-            relationshipMap.set(relationship.id, relationship);
-        }
+        if (relationshipMap.has(relationship.id))
+            return;
+        writeRel(relationship);
     };
     /**
-     * Remove a single node and all relationships involving it
+     * Remove a single node and all relationships involving it.
+     * O(edges-touching-node) via the reverse-adjacency index — no full
+     * relationshipMap scan.
      */
     const removeNode = (nodeId) => {
-        if (!nodeMap.has(nodeId))
+        const node = nodeMap.get(nodeId);
+        if (node === undefined)
             return false;
         nodeMap.delete(nodeId);
-        // Remove all relationships involving this node
-        for (const [relId, rel] of relationshipMap) {
-            if (rel.sourceId === nodeId || rel.targetId === nodeId) {
-                relationshipMap.delete(relId);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            removeFromBucket(nodeIdsByFile, filePath, nodeId);
+        }
+        const touchingEdgeIds = edgeIdsByNode.get(nodeId);
+        if (touchingEdgeIds !== undefined) {
+            // Snapshot the ids before iterating — deleteRel mutates the same
+            // Set via removeFromBucket, which would break mid-loop iteration.
+            for (const relId of [...touchingEdgeIds]) {
+                const rel = relationshipMap.get(relId);
+                if (rel !== undefined)
+                    deleteRel(rel);
             }
+            edgeIdsByNode.delete(nodeId);
         }
         return true;
     };
@@ -31,20 +116,26 @@ export const createKnowledgeGraph = () => {
      * Returns true if the relationship existed and was removed, false otherwise.
      */
     const removeRelationship = (relationshipId) => {
-        return relationshipMap.delete(relationshipId);
+        const rel = relationshipMap.get(relationshipId);
+        if (rel === undefined)
+            return false;
+        deleteRel(rel);
+        return true;
     };
     /**
      * Remove all nodes (and their relationships) belonging to a file.
+     * O(file-nodes × avg-edges-per-node) via the file index — no full
+     * node-map scan.
      */
     const removeNodesByFile = (filePath) => {
-        let removed = 0;
-        for (const [nodeId, node] of nodeMap) {
-            if (node.properties?.filePath === filePath) {
-                removeNode(nodeId);
-                removed++;
-            }
-        }
-        return removed;
+        const nodeIds = nodeIdsByFile.get(filePath);
+        if (nodeIds === undefined)
+            return 0;
+        // Snapshot before iterating — removeNode mutates nodeIdsByFile.
+        const snapshot = [...nodeIds];
+        for (const nodeId of snapshot)
+            removeNode(nodeId);
+        return snapshot.length;
     };
     return {
         get nodes() {
@@ -55,6 +146,10 @@ export const createKnowledgeGraph = () => {
         },
         iterNodes: () => nodeMap.values(),
         iterRelationships: () => relationshipMap.values(),
+        iterRelationshipsByType: (type) => {
+            const bucket = relationshipsByType.get(type);
+            return bucket === undefined ? emptyRelIter() : bucket.values();
+        },
         forEachNode(fn) {
             nodeMap.forEach(fn);
         },

package/dist/core/graph/types.d.ts

@@ -6,12 +6,23 @@
  *
  * This file only defines the CLI's KnowledgeGraph with mutation methods.
  */
-import type { GraphNode, GraphRelationship } from '../../_shared/index.js';
+import type { GraphNode, GraphRelationship, RelationshipType } from '../../_shared/index.js';
 export interface KnowledgeGraph {
     nodes: GraphNode[];
     relationships: GraphRelationship[];
     iterNodes: () => IterableIterator<GraphNode>;
     iterRelationships: () => IterableIterator<GraphRelationship>;
+    /**
+     * Iterate ONLY relationships of the given type, backed by a per-type
+     * index maintained in `addRelationship` / `removeRelationship` /
+     * `removeNode` / `removeNodesByFile`. Returns an empty iterator when
+     * the graph contains no relationships of that type.
+     *
+     * Prefer this over `iterRelationships()` + per-edge type filtering
+     * for hot paths (MRO setup, heritage walks). Backwards-compatible:
+     * existing `iterRelationships()` callers keep working.
+     */
+    iterRelationshipsByType: (type: RelationshipType) => IterableIterator<GraphRelationship>;
     forEachNode: (fn: (node: GraphNode) => void) => void;
     forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
     getNode: (id: string) => GraphNode | undefined;

package/dist/core/group/config-parser.d.ts

@@ -1,3 +1,7 @@
 import type { GroupConfig } from './types.js';
 export declare function parseGroupConfig(yamlContent: string): GroupConfig;
+export declare class GroupNotFoundError extends Error {
+    readonly groupName: string;
+    constructor(groupName: string);
+}
 export declare function loadGroupConfig(groupDir: string): Promise<GroupConfig>;

package/dist/core/group/config-parser.js

@@ -74,10 +74,27 @@ export function parseGroupConfig(yamlContent) {
         matching,
     };
 }
+export class GroupNotFoundError extends Error {
+    groupName;
+    constructor(groupName) {
+        super(`Group "${groupName}" not found`);
+        this.groupName = groupName;
+        this.name = 'GroupNotFoundError';
+    }
+}
 export async function loadGroupConfig(groupDir) {
     const fsp = await import('node:fs/promises');
     const path = await import('node:path');
     const yamlPath = path.join(groupDir, 'group.yaml');
-    const content = await fsp.readFile(yamlPath, 'utf-8');
+    let content;
+    try {
+        content = await fsp.readFile(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new GroupNotFoundError(path.basename(groupDir));
+        }
+        throw err;
+    }
     return parseGroupConfig(content);
 }

package/dist/core/group/cross-impact.js

@@ -4,7 +4,7 @@
  */
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { loadGroupConfig } from './config-parser.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getGroupDir } from './storage.js';
 import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
@@ -242,6 +242,8 @@ export async function runGroupImpact(deps, params) {
         config = await loadGroupConfig(groupDir);
     }
     catch (e) {
+        if (e instanceof GroupNotFoundError)
+            return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
         return { error: e instanceof Error ? e.message : String(e) };
     }
     const resolved = await resolveGroupRepo(deps.port, config, repoPath);
@@ -255,13 +257,10 @@ export async function runGroupImpact(deps, params) {
         includeTests,
         minConfidence,
     };
-    // Single shared deadline for Phase 1 (local walk) + Phase 2 (bridge fan-out).
-    // Phase 1 still gets the full budget; Phase 2 only uses whatever wall-clock
-    // time is left, so total work cannot exceed `timeoutMs`.
     const deadline = Date.now() + Math.max(0, timeoutMs);
     const { value: local, timedOut: localTimedOut } = await safeLocalImpact(deps.port, resolved, impactParams, timeoutMs);
     if (localTimedOut) {
-        const base = local;
+        const _base = local;
         return {
             local,
             group: name,
@@ -361,7 +360,6 @@ export async function runGroupImpact(deps, params) {
                 continue;
             }
             if (!repoInSubgroup(n.neighborRepo, subgroup)) {
-                // CrossLink convention: consumer -> provider
                 outOfScope.push({
                     from: direction === 'upstream' ? n.neighborRepo : repoPath,
                     to: direction === 'upstream' ? repoPath : n.neighborRepo,

package/dist/core/group/service.js

@@ -5,7 +5,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
-import { loadGroupConfig } from './config-parser.js';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
 import { syncGroup } from './sync.js';
@@ -134,7 +134,15 @@ export class GroupService {
             return { groups };
         }
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         return {
             name: config.name,
             description: config.description,
@@ -147,7 +155,15 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const result = await syncGroup(config, {
             groupDir,
             exactOnly: Boolean(params.exactOnly),
@@ -222,6 +238,14 @@ export class GroupService {
             config = await loadGroupConfig(groupDir);
         }
         catch (e) {
+            if (e instanceof GroupNotFoundError)
+                return {
+                    group: name,
+                    target: target || uid,
+                    service: servicePrefix,
+                    error: `Group "${name}" not found. Run group_list to see configured groups.`,
+                    results: [],
+                };
             return {
                 group: name,
                 target: target || uid,
@@ -231,9 +255,6 @@ export class GroupService {
             };
         }
         const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
-        // Per-repo work is independent (each repo opens its own DB handle and the
-        // group-level result preserves repo iteration order via the indexed map).
-        // Errors are caught per repo so one slow/failed member does not block the rest.
         const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
@@ -282,10 +303,16 @@ export class GroupService {
         const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
         const subgroupExact = params.subgroupExact === true;
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
-        // Per-repo query is independent; run them concurrently and isolate
-        // failures so one slow/failed member does not block the rest.
         const perRepo = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
@@ -324,7 +351,15 @@ export class GroupService {
         if (!name)
             return { error: 'name is required' };
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
-        const config = await loadGroupConfig(groupDir);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
         const registry = await readContractRegistry(groupDir);
         const repoStatuses = {};
         for (const [repoPath, registryName] of Object.entries(config.repos)) {

package/dist/core/ingestion/ast-cache.d.ts

@@ -1,5 +1,20 @@
 import Parser from 'tree-sitter';
-export interface ASTCache {
+/**
+ * Minimal structural shape consumers need when reading Trees back
+ * through a phase-dependency boundary. Declared here so phases that
+ * receive ASTCache via `getPhaseOutput<...>` don't hand-roll their
+ * own inline structural types that silently drift when ASTCache's
+ * contract changes.
+ *
+ * Typed as `unknown` at the Tree boundary because consumers on the
+ * other side of the phase-output map don't share tree-sitter's type
+ * graph (e.g. COBOL's standalone processor).
+ */
+export interface ASTCacheReader {
+    get(filePath: string): unknown;
+    clear(): void;
+}
+export interface ASTCache extends ASTCacheReader {
     get: (filePath: string) => Parser.Tree | undefined;
     set: (filePath: string, tree: Parser.Tree) => void;
     clear: () => void;

package/dist/core/ingestion/ast-cache.js

@@ -7,8 +7,20 @@ export const createASTCache = (maxSize = 50) => {
         max: effectiveMax,
         dispose: (tree) => {
             try {
-                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter trees are GC-managed.
-                // Keep this try/catch so we don't crash on either runtime.
+                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter
+                // trees are GC-managed and .delete is absent (no-op here).
+                //
+                // Single-owner invariant (load-bearing under WASM): a given
+                // Parser.Tree reference must live in AT MOST ONE ASTCache
+                // that disposes. The parse-phase chunk-local cache clears
+                // between chunks; the cross-phase `scopeTreeCache` (also an
+                // ASTCache today) holds the same Tree by reference. Under
+                // native tree-sitter this is benign (dispose is a no-op).
+                // If/when GitNexus adopts web-tree-sitter for sequential
+                // parsing, the cross-phase cache must either (a) skip
+                // writing Trees that are already owned by a disposing cache,
+                // or (b) use tree.copy() per entry. Failing to pick one
+                // will hand freed memory to scope-resolution.
                 tree.delete?.();
             }
             catch (e) {

package/dist/core/ingestion/call-processor.js

@@ -26,6 +26,7 @@ import { isLanguageAvailable, loadParser, loadLanguage } from '../tree-sitter/pa
 import { getProvider } from './languages/index.js';
 import { generateId } from '../../lib/utils.js';
 import { getLanguageFromFilename, SupportedLanguages } from '../../_shared/index.js';
+import { isRegistryPrimary } from './registry-primary-flag.js';
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { FUNCTION_NODE_TYPES, findEnclosingClassId, findEnclosingClassInfo, genericFuncName, inferFunctionLabel, } from './utils/ast-helpers.js';
@@ -594,6 +595,9 @@ importedRawReturnTypesMap, heritageMap, bindingAccumulator) => {
         const language = getLanguageFromFilename(file.path);
         if (!language)
             continue;
+        // Registry-primary gate: scope-based phase owns CALLS for this lang.
+        if (isRegistryPrimary(language))
+            continue;
         if (!isLanguageAvailable(language)) {
             if (skippedByLang) {
                 skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
@@ -2162,6 +2166,11 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
             onProgress?.(filesProcessed, totalFiles);
             await yieldToEventLoop();
         }
+        // Registry-primary gate: skip Python (etc.) entirely when the
+        // scope-based phase owns CALLS for this language.
+        const fileLanguage = getLanguageFromFilename(filePath);
+        if (fileLanguage && isRegistryPrimary(fileLanguage))
+            continue;
         ctx.enableCache(filePath);
         const widenCache = new Map();
         const receiverMap = fileReceiverTypes.get(filePath);

package/dist/core/ingestion/import-processor.js

@@ -9,6 +9,7 @@ import { getTreeSitterBufferSize } from './constants.js';
 import { loadImportConfigs } from './language-config.js';
 import { buildSuffixIndex } from './import-resolvers/utils.js';
 import { isDev } from './utils/env.js';
+import { isRegistryPrimary } from './registry-primary-flag.js';
 /** Group files by provider (only those with implicit import wiring), then call each wirer
  *  with its own language's files. O(n) over files, O(1) per provider lookup. */
 function wireImplicitImports(files, importMap, addImportEdge, projectConfig) {
@@ -64,6 +65,9 @@ export function preprocessImportPath(sourceText, importNode, provider) {
 function createImportEdgeHelpers(graph, importMap) {
     let totalImportsResolved = 0;
     const addImportGraphEdge = (filePath, resolvedPath) => {
+        const language = getLanguageFromFilename(filePath);
+        if (language !== null && isRegistryPrimary(language))
+            return;
         const sourceId = generateId('File', filePath);
         const targetId = generateId('File', resolvedPath);
         const relId = generateId('IMPORTS', `${filePath}->${resolvedPath}`);

package/dist/core/ingestion/import-resolvers/python.js

@@ -45,12 +45,15 @@ export function resolvePythonImportInternal(currentFile, importPath, allFiles) {
         return null;
     // Normalize for Windows backslashes
     const importerDir = currentFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
-    if (!importerDir)
-        return null;
-    if (allFiles.has(`${importerDir}/${pathLike}/__init__.py`))
-        return `${importerDir}/${pathLike}/__init__.py`;
-    if (allFiles.has(`${importerDir}/${pathLike}.py`))
-        return `${importerDir}/${pathLike}.py`;
+    // Proximity check — only applies when the importer lives in a subdirectory.
+    // Root-level importers (importerDir === '') skip straight to the ancestor
+    // walk below, which handles the root case correctly (prefix becomes '').
+    if (importerDir) {
+        if (allFiles.has(`${importerDir}/${pathLike}/__init__.py`))
+            return `${importerDir}/${pathLike}/__init__.py`;
+        if (allFiles.has(`${importerDir}/${pathLike}.py`))
+            return `${importerDir}/${pathLike}.py`;
+    }
     // Ancestor directory walk — Python resolves bare imports against sys.path entries,
     // which typically includes the project root and package directories. Walk up from the
     // importer's directory to find the module in an ancestor, preferring the closest match.

package/dist/core/ingestion/language-provider.d.ts

@@ -250,7 +250,18 @@ interface LanguageProviderConfig {
      *
      * Default: undefined (language continues to use legacy DAG).
      */
-    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => readonly CaptureMatch[];
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string, 
+    /**
+     * Optional pre-parsed tree-sitter Tree the caller has already
+     * produced (e.g. from the parse phase's AST cache). When supplied,
+     * the provider SHOULD skip its own `parser.parse(sourceText)` and
+     * run its capture query against the supplied tree directly. Typed
+     * as `unknown` here to avoid leaking the tree-sitter dependency
+     * into the provider contract — the provider casts at use site.
+     * Cache miss (parameter omitted or undefined) is always safe and
+     * MUST trigger a fresh parse.
+     */
+    cachedTree?: unknown) => readonly CaptureMatch[];
     /**
      * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
      * The central finalize algorithm resolves `ParsedImport.targetRaw` to a
@@ -288,18 +299,6 @@ interface LanguageProviderConfig {
      * suffix — `@scope.function` → `'Function'`, etc.).
      */
     readonly resolveScopeKind?: (captures: CaptureMatch) => ScopeKind | null;
-    /**
-     * Should this scope capture materialize as a real `Scope` node? Return
-     * `false` to skip scope creation while still emitting declarations that
-     * would have gone inside (they attach to the enclosing real scope).
-     *
-     * Example: Python `if`/`for`/`while` bodies capture as `@scope.block` but
-     * Python has no block scope — hook returns `false` and child declarations
-     * lift to the enclosing function/module.
-     *
-     * Default: undefined (treated as `true` — always create).
-     */
-    readonly shouldCreateScope?: (captures: CaptureMatch) => boolean;
     /**
      * Override where a declaration's name becomes visible. By default the name
      * is bound in the innermost enclosing scope; return a different `ScopeId`
@@ -382,18 +381,6 @@ interface LanguageProviderConfig {
      * else treats as `'free'`).
      */
     readonly classifyCallForm?: (captures: CaptureMatch, enclosingScope: Scope) => 'free' | 'member' | 'constructor' | 'index';
-    /**
-     * Does a binding at this scope shadow bindings of the same name in outer
-     * scopes? Default: any binding shadows (standard lexical scoping). Return
-     * `false` for transparent-scope edge cases (Python `from x import *`
-     * contexts, JS `var` hoisting quirks, COBOL PARAGRAPH transparency).
-     *
-     * Consulted by `Registry.lookup` Step 1 and by `resolveTypeRef` for
-     * shadowing decisions during the lexical chain walk.
-     *
-     * Default: undefined (treated as `true` — any binding shadows).
-     */
-    readonly shouldShadow?: (scope: Scope, bindings: readonly BindingRef[]) => boolean;
     /**
      * Is this callable definition compatible with the given call-site arity?
      * Language-specific rules: Python `*args`/`**kwargs`/defaults, JS default

package/dist/core/ingestion/languages/python/arity-metadata.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface PythonArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computePythonArityMetadata(fnNode: SyntaxNode): PythonArityMetadata;
+export {};

package/dist/core/ingestion/languages/python/arity-metadata.js

@@ -0,0 +1,45 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import { pythonMethodConfig } from '../../method-extractors/configs/python.js';
+export function computePythonArityMetadata(fnNode) {
+    const params = pythonMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVariadic = false;
+    let optionalCount = 0;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic)
+            hasVariadic = true;
+        else if (p.isOptional)
+            optionalCount++;
+        if (p.type !== null)
+            types.push(p.type);
+    }
+    const total = params.length;
+    const parameterCount = hasVariadic ? undefined : total;
+    // Unlike legacy `buildMethodProps`, we populate `requiredParameterCount`
+    // whenever the function isn't variadic — even when it equals
+    // `parameterCount`. The scope-resolution registry needs a concrete min
+    // to rule out under-application (e.g. picking `write_audit(x, y)` for
+    // a 1-arg call). Legacy could get away with leaving it undefined
+    // because its call-graph builder had a separate arity pre-filter.
+    const requiredParameterCount = hasVariadic ? undefined : total - optionalCount;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

package/dist/core/ingestion/languages/python/arity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Python arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Python method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def metadata is absent / incomplete.
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized but
+ * still considered when no compatible candidate exists), per RFC §4.
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function pythonArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';