gitnexus 1.6.4-rc.2 → 1.6.4-rc.21

package/dist/core/ingestion/scope-resolution/pipeline/registry.js

@@ -11,6 +11,7 @@
 import { SupportedLanguages } from '../../../../_shared/index.js';
 import { pythonScopeResolver } from '../../languages/python/scope-resolver.js';
 import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js';
+import { typescriptScopeResolver } from '../../languages/typescript/scope-resolver.js';
 /** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates
  *  this map intersected with `MIGRATED_LANGUAGES` (the per-language
  *  flag set) so adding a resolver here without flipping the flag is
@@ -18,4 +19,5 @@ import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js';
 export const SCOPE_RESOLVERS = new Map([
     [SupportedLanguages.Python, pythonScopeResolver],
     [SupportedLanguages.CSharp, csharpScopeResolver],
+    [SupportedLanguages.TypeScript, typescriptScopeResolver],
 ]);

package/dist/core/ingestion/scope-resolution/pipeline/run.d.ts

@@ -53,6 +53,14 @@ interface RunScopeResolutionInput {
     readonly treeCache?: {
         get(filePath: string): unknown;
     };
+    /**
+     * Opaque per-language import-resolution config (e.g. tsconfig path
+     * aliases for TypeScript). Loaded once by the caller via
+     * `provider.loadResolutionConfig(repoPath)` and threaded into every
+     * `provider.resolveImportTarget` call. `undefined` when the
+     * provider doesn't supply a config loader.
+     */
+    readonly resolutionConfig?: unknown;
 }
 interface RunScopeResolutionStats {
     readonly filesProcessed: number;

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -23,6 +23,7 @@
  * Plan: `docs/plans/2026-04-20-001-refactor-emit-pipeline-generalization-plan.md`.
  */
 import { reconcileOwnership, validateOwnershipParity } from './reconcile-ownership.js';
+import { validateBindingsImmutability } from './validate-bindings-immutability.js';
 import { extractParsedFile } from '../../scope-extractor-bridge.js';
 import { finalizeScopeModel } from '../../finalize-orchestrator.js';
 import { resolveReferenceSites } from '../../resolve-references.js';
@@ -81,9 +82,10 @@ export function runScopeResolution(input, provider) {
     const allFilePaths = new Set(parsedFiles.map((f) => f.filePath));
     const nodeLookup = buildGraphNodeLookup(graph);
     const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup);
+    const resolutionConfig = input.resolutionConfig;
     const finalized = finalizeScopeModel(parsedFiles, {
         hooks: {
-            resolveImportTarget: (targetRaw, fromFile) => provider.resolveImportTarget(targetRaw, fromFile, allFilePaths),
+            resolveImportTarget: (targetRaw, fromFile) => provider.resolveImportTarget(targetRaw, fromFile, allFilePaths, resolutionConfig),
             mergeBindings: (existing, incoming, scopeId) => provider.mergeBindings(existing, incoming, scopeId),
         },
     });
@@ -106,6 +108,8 @@ export function runScopeResolution(input, provider) {
     // Cross-file implicit-namespace visibility (C#). Must run before
     // propagateImportedReturnTypes so the latter pass sees siblings'
     // class bindings when chasing return-type chains across files.
+    // The hook writes to `bindingAugmentations` only; finalized
+    // `indexes.bindings` remains immutable post-finalize (I8).
     if (provider.populateNamespaceSiblings !== undefined) {
         const fileContents = new Map();
         for (const f of files)
@@ -115,12 +119,23 @@ export function runScopeResolution(input, provider) {
             treeCache,
         });
     }
+    const tFinalize = PROF ? process.hrtime.bigint() : 0n;
     // Cross-file return-type propagation (Contract Invariant I3 timing:
-    // after finalize, before resolve).
+    // after finalize, before resolve). Split-timed separately so the
+    // SCC-ordered pass's cost is observable (PR #1050 made this O(files)
+    // with chain-follow per importer; quadratic regressions show up
+    // here, not in finalize).
     if (provider.propagatesReturnTypesAcrossImports !== false) {
         propagateImportedReturnTypes(parsedFiles, indexes, workspaceIndex);
     }
-    const tFinalize = PROF ? process.hrtime.bigint() : 0n;
+    const tPropagate = PROF ? process.hrtime.bigint() : 0n;
+    // Opt-in I8 invariant guard. Runs once after all post-finalize hooks
+    // (`populateNamespaceSiblings`, `propagateImportedReturnTypes`) have
+    // had a chance to drift, so a single sweep covers the full
+    // post-finalize surface visible to `resolveReferenceSites`. No-op in
+    // default CLI runs; enabled by NODE_ENV=development or
+    // VALIDATE_SEMANTIC_MODEL=1.
+    validateBindingsImmutability(indexes, onWarn);
     // ── Phase 3: resolve references via Registry.lookup ────────────────────
     const registryProviders = {
         arityCompatibility: provider.arityCompatibility,
@@ -140,8 +155,9 @@ export function runScopeResolution(input, provider) {
         const tEnd = process.hrtime.bigint();
         const ns = (a, b) => Number(b - a) / 1_000_000;
         console.warn(`[scope-resolution prof] extract=${ns(tStart, tExtract).toFixed(0)}ms` +
-            ` finalize+propagate=${ns(tExtract, tFinalize).toFixed(0)}ms` +
-            ` resolve=${ns(tFinalize, tResolve).toFixed(0)}ms` +
+            ` finalize=${ns(tExtract, tFinalize).toFixed(0)}ms` +
+            ` propagate=${ns(tFinalize, tPropagate).toFixed(0)}ms` +
+            ` resolve=${ns(tPropagate, tResolve).toFixed(0)}ms` +
             ` emit=${ns(tResolve, tEnd).toFixed(0)}ms` +
             ` total=${ns(tStart, tEnd).toFixed(0)}ms` +
             ` (${parsedFiles.length} files)`);

package/dist/core/ingestion/scope-resolution/pipeline/validate-bindings-immutability.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Dev-mode runtime validator for the two-channel binding lifecycle
+ * (Contract Invariant I8 in `contract/scope-resolver.ts`).
+ *
+ * The two channels:
+ *   - `indexes.bindings` — finalize-output channel. After
+ *     `finalizeScopeModel` returns, every inner `BindingRef[]` array
+ *     here is deep-frozen by `materializeBindings`. NO post-finalize
+ *     hook should ever mutate this map's inner arrays — drift here
+ *     manifests at runtime as the `Cannot add property N, object is
+ *     not extensible` crash (issue #1066) or, more insidiously, as
+ *     a hook silently mutating one of the frozen arrays (a no-op in
+ *     production where freezes can be elided, a `TypeError` in dev).
+ *
+ *   - `indexes.bindingAugmentations` — post-finalize append-only
+ *     channel. Inner arrays here are NEVER frozen; hooks like
+ *     `populateNamespaceSiblings` `push()` directly. Walkers consult
+ *     both channels via `lookupBindingsAt`.
+ *
+ * This validator runs after every post-finalize hook has executed
+ * (so the dev-mode envelope captures the FULL surface area visible
+ * to `resolveReferenceSites`) and asserts:
+ *
+ *   1. Every inner `BindingRef[]` array in `indexes.bindings` is
+ *      `Object.isFrozen` — i.e. finalize produced a frozen bucket
+ *      AND no hook accidentally `set()`-back a mutable replacement.
+ *
+ *   2. Every inner `BindingRef[]` array in
+ *      `indexes.bindingAugmentations` is NOT frozen — i.e. the
+ *      hook used the augmentation channel as designed (mutable
+ *      `push()`) and didn't accidentally freeze its own scratch
+ *      arrays. Self-documenting; mostly a sanity net.
+ *
+ * Mirrors `validateOwnershipParity` (#909): warns via `onWarn`,
+ * never throws, and is opt-in outside development. Gated by
+ * `isSemanticModelValidatorEnabled()` (`utils/env.ts`).
+ */
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+export declare function validateBindingsImmutability(indexes: ScopeResolutionIndexes, onWarn: (message: string) => void): number;

package/dist/core/ingestion/scope-resolution/pipeline/validate-bindings-immutability.js

@@ -0,0 +1,65 @@
+/**
+ * Dev-mode runtime validator for the two-channel binding lifecycle
+ * (Contract Invariant I8 in `contract/scope-resolver.ts`).
+ *
+ * The two channels:
+ *   - `indexes.bindings` — finalize-output channel. After
+ *     `finalizeScopeModel` returns, every inner `BindingRef[]` array
+ *     here is deep-frozen by `materializeBindings`. NO post-finalize
+ *     hook should ever mutate this map's inner arrays — drift here
+ *     manifests at runtime as the `Cannot add property N, object is
+ *     not extensible` crash (issue #1066) or, more insidiously, as
+ *     a hook silently mutating one of the frozen arrays (a no-op in
+ *     production where freezes can be elided, a `TypeError` in dev).
+ *
+ *   - `indexes.bindingAugmentations` — post-finalize append-only
+ *     channel. Inner arrays here are NEVER frozen; hooks like
+ *     `populateNamespaceSiblings` `push()` directly. Walkers consult
+ *     both channels via `lookupBindingsAt`.
+ *
+ * This validator runs after every post-finalize hook has executed
+ * (so the dev-mode envelope captures the FULL surface area visible
+ * to `resolveReferenceSites`) and asserts:
+ *
+ *   1. Every inner `BindingRef[]` array in `indexes.bindings` is
+ *      `Object.isFrozen` — i.e. finalize produced a frozen bucket
+ *      AND no hook accidentally `set()`-back a mutable replacement.
+ *
+ *   2. Every inner `BindingRef[]` array in
+ *      `indexes.bindingAugmentations` is NOT frozen — i.e. the
+ *      hook used the augmentation channel as designed (mutable
+ *      `push()`) and didn't accidentally freeze its own scratch
+ *      arrays. Self-documenting; mostly a sanity net.
+ *
+ * Mirrors `validateOwnershipParity` (#909): warns via `onWarn`,
+ * never throws, and is opt-in outside development. Gated by
+ * `isSemanticModelValidatorEnabled()` (`utils/env.ts`).
+ */
+import { isSemanticModelValidatorEnabled } from '../../utils/env.js';
+export function validateBindingsImmutability(indexes, onWarn) {
+    if (!isSemanticModelValidatorEnabled())
+        return 0;
+    let violations = 0;
+    for (const [scopeId, bucketMap] of indexes.bindings) {
+        for (const [name, bucket] of bucketMap) {
+            if (!Object.isFrozen(bucket)) {
+                onWarn(`binding-immutability: indexes.bindings[${scopeId}][${name}] is NOT frozen — ` +
+                    `finalize produced a mutable bucket OR a post-finalize hook replaced a frozen ` +
+                    `bucket with a mutable one. Hooks must write to indexes.bindingAugmentations ` +
+                    `instead. See ScopeResolver Invariant I8.`);
+                violations++;
+            }
+        }
+    }
+    for (const [scopeId, bucketMap] of indexes.bindingAugmentations) {
+        for (const [name, bucket] of bucketMap) {
+            if (Object.isFrozen(bucket)) {
+                onWarn(`binding-immutability: indexes.bindingAugmentations[${scopeId}][${name}] is FROZEN — ` +
+                    `the augmentation channel is mutable by contract; freezing it defeats the ` +
+                    `append-only purpose. See ScopeResolver Invariant I8.`);
+                violations++;
+            }
+        }
+    }
+    return violations;
+}

package/dist/core/ingestion/scope-resolution/scope/walkers.d.ts

@@ -1,13 +1,14 @@
 /**
  * Scope-chain lookup primitives shared across language providers.
  *
- * Four functions:
+ * Five functions:
  *   - `findReceiverTypeBinding` — walk scope.typeBindings up the chain
  *     for a receiver name.
- *   - `findClassBindingInScope` — walk scope.bindings + indexes.bindings
- *     (pre-finalize + post-finalize) for a class-kind binding. Dual-
- *     source is required because the cross-file finalize pass produces
- *     a separate bindings map that is not merged back into scope.bindings.
+ *   - `lookupBindingsAt` — read finalized + augmented binding refs at
+ *     one scope, deduped by `def.nodeId`. The dual-source-aware
+ *     primitive every other binding lookup composes with.
+ *   - `findClassBindingInScope` — walk scope.bindings + the indexes via
+ *     `lookupBindingsAt` for a class-kind binding.
  *   - `findOwnedMember` — find a method/field owned by a class def
  *     across all parsed files by (ownerId, simpleName).
  *   - `findExportedDef` — find a file-level exported def (top-of-module
@@ -18,10 +19,44 @@
  * "resolve member on owner with MRO" pattern. All four are reusable
  * as-is for TypeScript, Java, Kotlin, Ruby, etc.
  */
-import type { ParsedFile, ScopeId, SymbolDefinition, TypeRef } from '../../../../_shared/index.js';
+import type { BindingRef, ParsedFile, ScopeId, SymbolDefinition, TypeRef } from '../../../../_shared/index.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
 import type { WorkspaceResolutionIndex } from '../workspace-index.js';
+/**
+ * Look up binding refs at `scopeId` for `name`, consulting both the
+ * finalize-owned `bindings` channel and the post-finalize
+ * `bindingAugmentations` channel (see invariant I8 in
+ * `contract/scope-resolver.ts`). Finalized refs come first; augmented
+ * refs append, deduped by `def.nodeId` so a sibling that's also
+ * explicitly imported doesn't double-emit.
+ *
+ * Returns a shared frozen empty array when neither channel has the
+ * name — callers can compare against `=== EMPTY_BINDINGS` if they
+ * want a fast-path miss check. The bucket arrays are returned by
+ * reference when only one channel populates them; the merged path
+ * allocates a fresh array.
+ *
+ * Walker primitives (`findClassBindingInScope`,
+ * `findCallableBindingInScope`, `findExportedDefByName`) and
+ * post-finalize passes that read finalized bindings (e.g.
+ * `propagateImportedReturnTypes`, `namespace-targets`) MUST go
+ * through this helper instead of `scopes.bindings.get(...)` directly,
+ * so the augmentation channel is always visible.
+ */
+export declare function lookupBindingsAt(scopeId: ScopeId, name: string, scopes: ScopeResolutionIndexes): readonly BindingRef[];
+/**
+ * Return the union of bound names at `scopeId` across both the
+ * finalized and augmented channels. Companion to `lookupBindingsAt`
+ * for callers that need to iterate every name at a scope (e.g.
+ * `propagateImportedReturnTypes`). Order is not guaranteed; callers
+ * that need stable iteration should sort externally.
+ *
+ * Fast paths (zero allocation) when at most one channel is populated:
+ * returns the underlying `Map.keys()` iterator directly. Only when both
+ * channels carry names do we materialize a `Set` for deduplication.
+ */
+export declare function namesAtScope(scopeId: ScopeId, scopes: ScopeResolutionIndexes): Iterable<string>;
 /**
  * True when a def's `type` names a class-like declaration — every kind
  * that collapses to `@scope.class` in the scope-extractor query contract.
@@ -48,8 +83,10 @@ export declare function findReceiverTypeBinding(startScope: ScopeId, receiverNam
  * Walks the scope chain upward and consults TWO sources at each step:
  *   1. `scope.bindings` — populated during scope-extraction Pass 2 with
  *      local declarations (`origin: 'local'`).
- *   2. `indexes.bindings` — populated by the cross-file finalize pass
- *      with import/namespace/wildcard/reexport origins.
+ *   2. The cross-file finalized + augmented bindings, via
+ *      `lookupBindingsAt` (per I8: finalized = canonical immutable
+ *      output; augmented = post-finalize hooks like
+ *      `populateNamespaceSiblings`).
  *
  * Without (2) we'd miss every cross-file class-receiver call.
  */
@@ -57,8 +94,9 @@ export declare function findClassBindingInScope(startScope: ScopeId, receiverNam
 /**
  * Look up a callable (Function/Method/Constructor) by name in the
  * given scope's chain. Uses the dual-source pattern (scope.bindings +
- * indexes.bindings) so cross-file imports are visible — without it
- * free calls to imported functions never resolve via the post-pass.
+ * `lookupBindingsAt` for finalized + augmented) so cross-file
+ * imports are visible — without it free calls to imported functions
+ * never resolve via the post-pass.
  *
  * Mirrors `findClassBindingInScope` exactly; only the accepted
  * def-type predicate differs.
@@ -122,6 +160,11 @@ export declare function findOwnedMember(ownerDefId: string, memberName: string,
  * excluded.
  *
  * Reads from `WorkspaceResolutionIndex.moduleScopeByFile` (scope-tied
- * lookup that doesn't live on `SemanticModel`).
+ * lookup that doesn't live on `SemanticModel`). This intentionally
+ * does NOT call `lookupBindingsAt`: `findExportedDef` answers "what
+ * did the target file declare locally at module scope?", while
+ * `bindingAugmentations` models importer-side visibility created by
+ * post-finalize hooks. Callers that need importer-visible exports use
+ * `findExportedDefByName`, which is dual-channel aware.
  */
 export declare function findExportedDef(targetFile: string, memberName: string, index: WorkspaceResolutionIndex): SymbolDefinition | undefined;

package/dist/core/ingestion/scope-resolution/scope/walkers.js

@@ -1,13 +1,14 @@
 /**
  * Scope-chain lookup primitives shared across language providers.
  *
- * Four functions:
+ * Five functions:
  *   - `findReceiverTypeBinding` — walk scope.typeBindings up the chain
  *     for a receiver name.
- *   - `findClassBindingInScope` — walk scope.bindings + indexes.bindings
- *     (pre-finalize + post-finalize) for a class-kind binding. Dual-
- *     source is required because the cross-file finalize pass produces
- *     a separate bindings map that is not merged back into scope.bindings.
+ *   - `lookupBindingsAt` — read finalized + augmented binding refs at
+ *     one scope, deduped by `def.nodeId`. The dual-source-aware
+ *     primitive every other binding lookup composes with.
+ *   - `findClassBindingInScope` — walk scope.bindings + the indexes via
+ *     `lookupBindingsAt` for a class-kind binding.
  *   - `findOwnedMember` — find a method/field owned by a class def
  *     across all parsed files by (ownerId, simpleName).
  *   - `findExportedDef` — find a file-level exported def (top-of-module
@@ -18,6 +19,80 @@
  * "resolve member on owner with MRO" pattern. All four are reusable
  * as-is for TypeScript, Java, Kotlin, Ruby, etc.
  */
+const EMPTY_BINDINGS = Object.freeze([]);
+/**
+ * Look up binding refs at `scopeId` for `name`, consulting both the
+ * finalize-owned `bindings` channel and the post-finalize
+ * `bindingAugmentations` channel (see invariant I8 in
+ * `contract/scope-resolver.ts`). Finalized refs come first; augmented
+ * refs append, deduped by `def.nodeId` so a sibling that's also
+ * explicitly imported doesn't double-emit.
+ *
+ * Returns a shared frozen empty array when neither channel has the
+ * name — callers can compare against `=== EMPTY_BINDINGS` if they
+ * want a fast-path miss check. The bucket arrays are returned by
+ * reference when only one channel populates them; the merged path
+ * allocates a fresh array.
+ *
+ * Walker primitives (`findClassBindingInScope`,
+ * `findCallableBindingInScope`, `findExportedDefByName`) and
+ * post-finalize passes that read finalized bindings (e.g.
+ * `propagateImportedReturnTypes`, `namespace-targets`) MUST go
+ * through this helper instead of `scopes.bindings.get(...)` directly,
+ * so the augmentation channel is always visible.
+ */
+export function lookupBindingsAt(scopeId, name, scopes) {
+    const finalized = scopes.bindings.get(scopeId)?.get(name);
+    const augmented = scopes.bindingAugmentations.get(scopeId)?.get(name);
+    const fLen = finalized?.length ?? 0;
+    const aLen = augmented?.length ?? 0;
+    if (fLen === 0 && aLen === 0)
+        return EMPTY_BINDINGS;
+    if (aLen === 0)
+        return finalized;
+    if (fLen === 0)
+        return augmented;
+    const seen = new Set();
+    const out = [];
+    for (const r of finalized) {
+        seen.add(r.def.nodeId);
+        out.push(r);
+    }
+    for (const r of augmented) {
+        if (seen.has(r.def.nodeId))
+            continue;
+        out.push(r);
+    }
+    return out;
+}
+const EMPTY_NAMES = Object.freeze([]);
+/**
+ * Return the union of bound names at `scopeId` across both the
+ * finalized and augmented channels. Companion to `lookupBindingsAt`
+ * for callers that need to iterate every name at a scope (e.g.
+ * `propagateImportedReturnTypes`). Order is not guaranteed; callers
+ * that need stable iteration should sort externally.
+ *
+ * Fast paths (zero allocation) when at most one channel is populated:
+ * returns the underlying `Map.keys()` iterator directly. Only when both
+ * channels carry names do we materialize a `Set` for deduplication.
+ */
+export function namesAtScope(scopeId, scopes) {
+    const finalized = scopes.bindings.get(scopeId);
+    const augmented = scopes.bindingAugmentations.get(scopeId);
+    const fSize = finalized?.size ?? 0;
+    const aSize = augmented?.size ?? 0;
+    if (fSize === 0 && aSize === 0)
+        return EMPTY_NAMES;
+    if (aSize === 0)
+        return finalized.keys();
+    if (fSize === 0)
+        return augmented.keys();
+    const out = new Set(finalized.keys());
+    for (const name of augmented.keys())
+        out.add(name);
+    return out;
+}
 /**
  * True when a def's `type` names a class-like declaration — every kind
  * that collapses to `@scope.class` in the scope-extractor query contract.
@@ -67,8 +142,10 @@ export function findReceiverTypeBinding(startScope, receiverName, scopes) {
  * Walks the scope chain upward and consults TWO sources at each step:
  *   1. `scope.bindings` — populated during scope-extraction Pass 2 with
  *      local declarations (`origin: 'local'`).
- *   2. `indexes.bindings` — populated by the cross-file finalize pass
- *      with import/namespace/wildcard/reexport origins.
+ *   2. The cross-file finalized + augmented bindings, via
+ *      `lookupBindingsAt` (per I8: finalized = canonical immutable
+ *      output; augmented = post-finalize hooks like
+ *      `populateNamespaceSiblings`).
  *
  * Without (2) we'd miss every cross-file class-receiver call.
  */
@@ -89,13 +166,10 @@ export function findClassBindingInScope(startScope, receiverName, scopes) {
                     return b.def;
             }
         }
-        const finalizedScopeBindings = scopes.bindings.get(currentId);
-        const importedBindings = finalizedScopeBindings?.get(receiverName);
-        if (importedBindings !== undefined) {
-            for (const b of importedBindings) {
-                if (isClassLike(b.def.type))
-                    return b.def;
-            }
+        const importedBindings = lookupBindingsAt(currentId, receiverName, scopes);
+        for (const b of importedBindings) {
+            if (isClassLike(b.def.type))
+                return b.def;
         }
         currentId = scope.parent;
     }
@@ -104,8 +178,9 @@ export function findClassBindingInScope(startScope, receiverName, scopes) {
 /**
  * Look up a callable (Function/Method/Constructor) by name in the
  * given scope's chain. Uses the dual-source pattern (scope.bindings +
- * indexes.bindings) so cross-file imports are visible — without it
- * free calls to imported functions never resolve via the post-pass.
+ * `lookupBindingsAt` for finalized + augmented) so cross-file
+ * imports are visible — without it free calls to imported functions
+ * never resolve via the post-pass.
  *
  * Mirrors `findClassBindingInScope` exactly; only the accepted
  * def-type predicate differs.
@@ -128,13 +203,10 @@ export function findCallableBindingInScope(startScope, callableName, scopes) {
                 }
             }
         }
-        const finalizedScopeBindings = scopes.bindings.get(currentId);
-        const importedBindings = finalizedScopeBindings?.get(callableName);
-        if (importedBindings !== undefined) {
-            for (const b of importedBindings) {
-                if (b.def.type === 'Function' || b.def.type === 'Method' || b.def.type === 'Constructor') {
-                    return b.def;
-                }
+        const importedBindings = lookupBindingsAt(currentId, callableName, scopes);
+        for (const b of importedBindings) {
+            if (b.def.type === 'Function' || b.def.type === 'Method' || b.def.type === 'Constructor') {
+                return b.def;
             }
         }
         currentId = scope.parent;
@@ -272,12 +344,10 @@ export function findExportedDefByName(name, inScope, scopes, index) {
                     return b.def;
             }
         }
-        const finalized = scopes.bindings.get(currentId)?.get(name);
-        if (finalized !== undefined) {
-            for (const b of finalized) {
-                if (b.def.type === 'Function' || b.def.type === 'Method')
-                    return b.def;
-            }
+        const finalized = lookupBindingsAt(currentId, name, scopes);
+        for (const b of finalized) {
+            if (b.def.type === 'Function' || b.def.type === 'Method')
+                return b.def;
         }
         currentId = scope.parent;
     }
@@ -332,7 +402,12 @@ export function findOwnedMember(ownerDefId, memberName, model) {
  * excluded.
  *
  * Reads from `WorkspaceResolutionIndex.moduleScopeByFile` (scope-tied
- * lookup that doesn't live on `SemanticModel`).
+ * lookup that doesn't live on `SemanticModel`). This intentionally
+ * does NOT call `lookupBindingsAt`: `findExportedDef` answers "what
+ * did the target file declare locally at module scope?", while
+ * `bindingAugmentations` models importer-side visibility created by
+ * post-finalize hooks. Callers that need importer-visible exports use
+ * `findExportedDefByName`, which is dual-channel aware.
  */
 export function findExportedDef(targetFile, memberName, index) {
     const moduleScope = index.moduleScopeByFile.get(targetFile);

package/dist/core/ingestion/type-extractors/swift.js

@@ -21,6 +21,9 @@ function unwrapSwiftExpression(node) {
     }
     return node;
 }
+function swiftNavigationSuffixName(node) {
+    return node?.type === 'navigation_suffix' ? node.lastNamedChild?.text : node?.text;
+}
 /** Swift: let x: Foo = ... */
 const extractDeclaration = (node, env) => {
     // Swift property_declaration has pattern and type_annotation
@@ -99,8 +102,8 @@ const extractInitializer = (node, env, classNames) => {
     // Explicit init: User.init(name: "alice") — navigation_expression with .init suffix
     if (callee.type === 'navigation_expression') {
         const receiver = callee.firstNamedChild;
-        const suffix = callee.lastNamedChild;
-        if (receiver?.type === 'simple_identifier' && suffix?.text === 'init') {
+        if (receiver?.type === 'simple_identifier' &&
+            swiftNavigationSuffixName(callee.lastNamedChild) === 'init') {
             const calleeName = receiver.text;
             if (calleeName && classNames.has(calleeName)) {
                 env.set(varName, calleeName);
@@ -114,7 +117,7 @@ const scanConstructorBinding = (node) => {
         return undefined;
     if (hasTypeAnnotation(node))
         return undefined;
-    const pattern = node.childForFieldName('pattern');
+    const pattern = node.childForFieldName('pattern') ?? findChild(node, 'pattern');
     if (!pattern)
         return undefined;
     const varName = pattern.text;
@@ -147,7 +150,7 @@ const scanConstructorBinding = (node) => {
     if (callee.type === 'navigation_expression') {
         const receiver = callee.firstNamedChild;
         const suffix = callee.lastNamedChild;
-        if (receiver?.type === 'simple_identifier' && suffix?.text === 'init') {
+        if (receiver?.type === 'simple_identifier' && swiftNavigationSuffixName(suffix) === 'init') {
             return { varName, calleeName: receiver.text };
         }
         // General qualified call: service.getUser() → extract method name.

package/dist/core/ingestion/utils/ast-helpers.d.ts

@@ -31,6 +31,8 @@ export declare const FUNCTION_NODE_TYPES: Set<string>;
  */
 export declare const CLASS_CONTAINER_TYPES: Set<string>;
 export declare const CONTAINER_TYPE_TO_LABEL: Record<string, string>;
+/** Return the first matching ancestor unless a boundary ancestor is reached first. */
+export declare function findAncestorBeforeBoundary(node: SyntaxNode, targetTypes: ReadonlySet<string>, boundaryTypes: ReadonlySet<string>): SyntaxNode | null;
 /**
  * Determine the graph node label from a tree-sitter capture map.
  * Handles language-specific reclassification via the provider's labelOverride hook

package/dist/core/ingestion/utils/ast-helpers.js

@@ -153,6 +153,18 @@ export const CONTAINER_TYPE_TO_LABEL = {
     object_declaration: 'Class',
     companion_object: 'Class',
 };
+/** Return the first matching ancestor unless a boundary ancestor is reached first. */
+export function findAncestorBeforeBoundary(node, targetTypes, boundaryTypes) {
+    let current = node.parent;
+    while (current !== null) {
+        if (boundaryTypes.has(current.type))
+            return null;
+        if (targetTypes.has(current.type))
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
 /**
  * Determine the graph node label from a tree-sitter capture map.
  * Handles language-specific reclassification via the provider's labelOverride hook

package/dist/core/ingestion/utils/env.d.ts

@@ -8,3 +8,13 @@
  */
 /** Whether we're running in development mode (enables verbose console logging). */
 export declare const isDev: boolean;
+/**
+ * Whether scope-resolution dev validators (e.g. `validateBindingsImmutability`)
+ * should run AND emit warnings. Off by default in CLI runs to avoid silent
+ * O(n) scans on large repos; on in `NODE_ENV=development` or when explicitly
+ * opted-in via `VALIDATE_SEMANTIC_MODEL=1`. `VALIDATE_SEMANTIC_MODEL=0` is the
+ * explicit off switch and wins over both.
+ *
+ * Read every call (not memoized) so test setups using `vi.stubEnv` work.
+ */
+export declare const isSemanticModelValidatorEnabled: () => boolean;

package/dist/core/ingestion/utils/env.js

@@ -8,3 +8,17 @@
  */
 /** Whether we're running in development mode (enables verbose console logging). */
 export const isDev = process.env.NODE_ENV === 'development';
+/**
+ * Whether scope-resolution dev validators (e.g. `validateBindingsImmutability`)
+ * should run AND emit warnings. Off by default in CLI runs to avoid silent
+ * O(n) scans on large repos; on in `NODE_ENV=development` or when explicitly
+ * opted-in via `VALIDATE_SEMANTIC_MODEL=1`. `VALIDATE_SEMANTIC_MODEL=0` is the
+ * explicit off switch and wins over both.
+ *
+ * Read every call (not memoized) so test setups using `vi.stubEnv` work.
+ */
+export const isSemanticModelValidatorEnabled = () => {
+    if (process.env.VALIDATE_SEMANTIC_MODEL === '0')
+        return false;
+    return process.env.NODE_ENV === 'development' || process.env.VALIDATE_SEMANTIC_MODEL === '1';
+};

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -117,6 +117,7 @@ export interface ExtractedToolDef {
     toolName: string;
     description: string;
     lineNumber: number;
+    handlerNodeId?: string;
 }
 export interface ExtractedORMQuery {
     filePath: string;