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

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

@@ -10,7 +10,7 @@ import { getDefinitionNodeFromCaptures, findEnclosingClassInfo, getLabelFromCapt
 import { detectFrameworkFromAST } from './framework-detection.js';
 import { buildTypeEnv } from './type-env.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from './utils/method-props.js';
-import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from './constants.js';
+import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from './constants.js';
 // ============================================================================
 // Worker-based parallel parsing
 // ============================================================================
@@ -247,7 +247,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
             continue;
         }
         // Skip files larger than the max tree-sitter buffer (32 MB)
-        if (file.content.length > TREE_SITTER_MAX_BUFFER)
+        if (getTreeSitterContentByteLength(file.content) > TREE_SITTER_MAX_BUFFER)
             continue;
         // Vue SFC preprocessing: extract <script> block content
         let parseContent = file.content;
@@ -270,7 +270,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
         let tree;
         try {
             tree = parser.parse(parseContent, undefined, {
-                bufferSize: getTreeSitterBufferSize(parseContent.length),
+                bufferSize: getTreeSitterBufferSize(parseContent),
             });
         }
         catch (parseError) {
@@ -412,10 +412,12 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                     }
                 }
             }
-            // Append #<paramCount> to Method/Constructor IDs to disambiguate overloads.
-            // Functions are not suffixed — they don't overload by name in the same scope.
+            // Append #<paramCount> to owned callable IDs to disambiguate overloads.
+            // Top-level Function IDs stay stable; functions inside an owner may overload.
             // When same-arity collisions exist, append ~type1,type2 for further disambiguation.
-            const needsAritySuffix = nodeLabel === 'Method' || nodeLabel === 'Constructor';
+            const needsAritySuffix = nodeLabel === 'Method' ||
+                nodeLabel === 'Constructor' ||
+                (nodeLabel === 'Function' && enclosingClassId !== null);
             let arityTag = needsAritySuffix && arityForId !== undefined ? `#${arityForId}` : '';
             if (arityTag && seqDefMethods && seqDefMethodInfo && seqClassNodeId !== undefined) {
                 // Use cached method map + collision groups (built once per class, not per method)
@@ -555,6 +557,13 @@ export const processParsing = async (graph, files, symbolTable, astCache,
  * Pass `undefined` if no consumer needs cross-phase access.
  */
 scopeTreeCache, onFileProgress, workerPool) => {
+    let lastProgress = 0;
+    const reportProgress = onFileProgress
+        ? (current, total, detail) => {
+            lastProgress = Math.max(lastProgress, current);
+            onFileProgress(lastProgress, total, detail);
+        }
+        : undefined;
     if (workerPool) {
         if (scopeTreeCache !== undefined && process.env.PROF_SCOPE_RESOLUTION === '1') {
             // Trees can't cross MessageChannels, so worker-parsed files land
@@ -564,13 +573,15 @@ scopeTreeCache, onFileProgress, workerPool) => {
             console.warn(`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`);
         }
         try {
-            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, onFileProgress);
+            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress);
         }
         catch (err) {
-            console.warn('Worker pool parsing failed, falling back to sequential:', err instanceof Error ? err.message : err);
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn('Worker pool parsing stopped; continuing with sequential parser:', message);
+            reportProgress?.(lastProgress, files.length, `Sequential fallback after worker issue: ${message}`);
         }
     }
     // Fallback: sequential parsing (no pre-extracted data)
-    await processParsingSequential(graph, files, symbolTable, astCache, scopeTreeCache, onFileProgress);
+    await processParsingSequential(graph, files, symbolTable, astCache, scopeTreeCache, reportProgress);
     return null;
 };

package/dist/core/ingestion/pipeline-phases/processes.js

@@ -84,12 +84,15 @@ export const processesPhase = {
                 }
                 list.push(url);
             }
-            const toolsByFile = new Map();
+            const toolsByHandlerId = new Map();
+            const toolsWithoutHandlerByFile = new Map();
             for (const td of toolDefs) {
-                let list = toolsByFile.get(td.filePath);
+                const key = td.handlerNodeId ?? td.filePath;
+                const targetMap = td.handlerNodeId ? toolsByHandlerId : toolsWithoutHandlerByFile;
+                let list = targetMap.get(key);
                 if (!list) {
                     list = [];
-                    toolsByFile.set(td.filePath, list);
+                    targetMap.set(key, list);
                 }
                 list.push(td.name);
             }
@@ -118,7 +121,9 @@ export const processesPhase = {
                         linked++;
                     }
                 }
-                const toolNames = toolsByFile.get(entryFile);
+                const exactToolNames = toolsByHandlerId.get(proc.entryPointId);
+                const fallbackToolNames = toolsWithoutHandlerByFile.get(entryFile);
+                const toolNames = exactToolNames ?? fallbackToolNames;
                 if (toolNames) {
                     for (const toolName of toolNames) {
                         const toolNodeId = generateId('Tool', toolName);

package/dist/core/ingestion/pipeline-phases/tools.d.ts

@@ -13,6 +13,7 @@ export interface ToolDef {
     name: string;
     filePath: string;
     description: string;
+    handlerNodeId?: string;
 }
 export interface ToolsOutput {
     toolDefs: ToolDef[];

package/dist/core/ingestion/pipeline-phases/tools.js

@@ -23,7 +23,13 @@ export const toolsPhase = {
             if (seenToolNames.has(td.toolName))
                 continue;
             seenToolNames.add(td.toolName);
-            toolDefs.push({ name: td.toolName, filePath: td.filePath, description: td.description });
+            const handlerNodeId = td.handlerNodeId && ctx.graph.getNode(td.handlerNodeId) ? td.handlerNodeId : undefined;
+            toolDefs.push({
+                name: td.toolName,
+                filePath: td.filePath,
+                description: td.description,
+                ...(handlerNodeId !== undefined ? { handlerNodeId } : {}),
+            });
         }
         // TS tool definition arrays — require inputSchema nearby
         const toolCandidatePaths = allPaths.filter((p) => (p.endsWith('.ts') || p.endsWith('.js')) &&
@@ -60,10 +66,10 @@ export const toolsPhase = {
                     label: 'Tool',
                     properties: { name: td.name, filePath: td.filePath, description: td.description },
                 });
-                const handlerFileId = generateId('File', td.filePath);
+                const handlerId = td.handlerNodeId ?? generateId('File', td.filePath);
                 ctx.graph.addRelationship({
-                    id: generateId('HANDLES_TOOL', `${handlerFileId}->${toolNodeId}`),
-                    sourceId: handlerFileId,
+                    id: generateId('HANDLES_TOOL', `${handlerId}->${toolNodeId}`),
+                    sourceId: handlerId,
                     targetId: toolNodeId,
                     type: 'HANDLES_TOOL',
                     confidence: 1.0,

package/dist/core/ingestion/registry-primary-flag.d.ts

@@ -56,7 +56,9 @@ import { SupportedLanguages } from '../../_shared/index.js';
  *      so this set also controls what gets silenced in the legacy DAG.
  *
  * Add a language here ONLY after shadow parity ≥ 99% fixtures / ≥ 98%
- * corpus per RFC §6.4. The parity CI gate will block the PR otherwise.
+ * corpus per RFC §6.4. TypeScript is temporarily accepted under the
+ * Ring 3 CI parity gate while corpus-level shadow-mode wiring is tracked
+ * in #927 for this migration.
  *
  * The set is intentionally a static TypeScript literal (not a JSON import,
  * not an env lookup) so CI can discover it via `tsx` without a build step

package/dist/core/ingestion/registry-primary-flag.js

@@ -56,7 +56,9 @@ import { SupportedLanguages } from '../../_shared/index.js';
  *      so this set also controls what gets silenced in the legacy DAG.
  *
  * Add a language here ONLY after shadow parity ≥ 99% fixtures / ≥ 98%
- * corpus per RFC §6.4. The parity CI gate will block the PR otherwise.
+ * corpus per RFC §6.4. TypeScript is temporarily accepted under the
+ * Ring 3 CI parity gate while corpus-level shadow-mode wiring is tracked
+ * in #927 for this migration.
  *
  * The set is intentionally a static TypeScript literal (not a JSON import,
  * not an env lookup) so CI can discover it via `tsx` without a build step
@@ -65,6 +67,7 @@ import { SupportedLanguages } from '../../_shared/index.js';
 export const MIGRATED_LANGUAGES = new Set([
     SupportedLanguages.Python,
     SupportedLanguages.CSharp,
+    SupportedLanguages.TypeScript,
 ]);
 /**
  * Return the env-var name that controls a given language's registry-

package/dist/core/ingestion/scope-extractor-bridge.d.ts

@@ -13,8 +13,11 @@
  *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
  *      the state of every language today — `ParsedFile` production stays
  *      dormant until a language migrates.
- *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
- *   3. **Swallows exceptions from either side.** A failure here returns
+ *   2. Short-circuits empty / whitespace-only files. There is no scope
+ *      content to extract, and some tree-sitter queries do not match an
+ *      otherwise valid empty root node.
+ *   3. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   4. **Swallows exceptions from either side.** A failure here returns
  *      `undefined` and emits a warning via `onWarn`; legacy parsing on
  *      the same file continues unaffected by the scope-extraction miss.
  *      Scope-based resolution is the new path under construction — it

package/dist/core/ingestion/scope-extractor-bridge.js

@@ -13,8 +13,11 @@
  *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
  *      the state of every language today — `ParsedFile` production stays
  *      dormant until a language migrates.
- *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
- *   3. **Swallows exceptions from either side.** A failure here returns
+ *   2. Short-circuits empty / whitespace-only files. There is no scope
+ *      content to extract, and some tree-sitter queries do not match an
+ *      otherwise valid empty root node.
+ *   3. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   4. **Swallows exceptions from either side.** A failure here returns
  *      `undefined` and emits a warning via `onWarn`; legacy parsing on
  *      the same file continues unaffected by the scope-extraction miss.
  *      Scope-based resolution is the new path under construction — it
@@ -29,6 +32,8 @@ import { extract as extractScope } from './scope-extractor.js';
 export function extractParsedFile(provider, sourceText, filePath, onWarn, cachedTree) {
     if (provider.emitScopeCaptures === undefined)
         return undefined;
+    if (sourceText.trim().length === 0)
+        return undefined;
     try {
         const captures = provider.emitScopeCaptures(sourceText, filePath, cachedTree);
         return extractScope(captures, filePath, provider);

package/dist/core/ingestion/scope-extractor.js

@@ -58,7 +58,7 @@
  *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
  *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
  */
-import { buildPositionIndex, buildScopeTree, makeScopeId } from '../../_shared/index.js';
+import { buildPositionIndex, buildScopeTree, canParentScope, makeScopeId } from '../../_shared/index.js';
 // ─── Public entry point ─────────────────────────────────────────────────────
 /**
  * Drive the five extraction passes and return a `ParsedFile`.
@@ -210,7 +210,11 @@ function pass1BuildScopes(matches, filePath, provider) {
         candidates.push({ match, range: anchor.range, kind, id });
     }
     // Sort by (startLine, startCol) ASC, (endLine, endCol) DESC so outer
-    // scopes appear before their children for parent-resolution.
+    // scopes appear before their children for parent-resolution. When two
+    // candidates have exactly equal ranges (e.g. a `compilation_unit` and
+    // the only top-level scope in the file — see `canParentScope`), Module
+    // sorts first so it lands on the stack ahead of the candidate that will
+    // claim it as parent.
     candidates.sort((a, b) => {
         if (a.range.startLine !== b.range.startLine)
             return a.range.startLine - b.range.startLine;
@@ -218,13 +222,23 @@ function pass1BuildScopes(matches, filePath, provider) {
             return a.range.startCol - b.range.startCol;
         if (a.range.endLine !== b.range.endLine)
             return b.range.endLine - a.range.endLine;
-        return b.range.endCol - a.range.endCol;
+        if (a.range.endCol !== b.range.endCol)
+            return b.range.endCol - a.range.endCol;
+        if (a.kind === b.kind)
+            return 0;
+        if (a.kind === 'Module')
+            return -1;
+        if (b.kind === 'Module')
+            return 1;
+        return 0;
     });
     const drafts = [];
     const stack = []; // enclosing real scopes, outermost at [0]
     for (const cand of candidates) {
-        // Pop the stack until the top strictly contains this candidate.
-        while (stack.length > 0 && !rangeStrictlyContains(stack[stack.length - 1].range, cand.range)) {
+        // Pop the stack until the top can parent this candidate (strict
+        // containment, plus the equal-range Module carve-out).
+        while (stack.length > 0 &&
+            !canParentScope(stack[stack.length - 1].range, cand.range, stack[stack.length - 1].kind, cand.kind)) {
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1].id : null;
@@ -692,19 +706,6 @@ function rangesEqual(a, b) {
         a.endLine === b.endLine &&
         a.endCol === b.endCol);
 }
-function rangeStrictlyContains(outer, inner) {
-    if (outer.startLine === inner.startLine &&
-        outer.startCol === inner.startCol &&
-        outer.endLine === inner.endLine &&
-        outer.endCol === inner.endCol) {
-        return false;
-    }
-    const startsBefore = outer.startLine < inner.startLine ||
-        (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
-    const endsAfter = outer.endLine > inner.endLine ||
-        (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
-    return startsBefore && endsAfter;
-}
 /**
  * Capture names that are never anchors — they are sub-tags nested inside a
  * larger anchor (e.g., the receiver expression inside a `@reference.call`

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -88,14 +88,21 @@
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
  *
- *   - **I3 — `propagateImportedReturnTypes` mutation timing.** The
- *     pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
+ *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
  *     `draftToScope`, NOT frozen). It MUST run AFTER `finalizeScopeModel`
  *     (so `indexes.bindings` is populated) and BEFORE
  *     `resolveReferenceSites` (so resolution sees the propagated types).
  *     The pass also re-runs `followChainPostFinalize` on every scope's
  *     typeBindings because scope-extractor's pass-4 already ran and
  *     missed any chain whose terminal lives in a foreign file.
+ *     Within the pass, files are walked in `indexes.sccs` reverse-
+ *     topological order (leaves first) so multi-hop alias chains
+ *     (e.g. `models.User → service.user → app.user`) collapse to the
+ *     terminal class in a single pass — every importer sees its
+ *     source's already-chain-followed typeBindings. Cyclic SCCs reach
+ *     a partial fixpoint within a single pass without iterating to
+ *     convergence; `ts-circular` only asserts pipeline-no-throw.
  *
  *   - **I4 — `emitReceiverBoundCalls` case order.** Cases are evaluated
  *     in this order; the FIRST that emits an edge wins:
@@ -129,14 +136,45 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Post-finalize hooks may mutate `Scope.typeBindings` and
- *     `indexes.bindings`.** `propagateImportedReturnTypes` and
- *     `populateNamespaceSiblings` both write to these structures via
- *     `as Map<...>` casts through `ReadonlyMap` facades. Downstream
- *     consumers MUST NOT freeze or snapshot these maps before all
- *     post-finalize hooks have run. The `ReadonlyMap<...>` type on
- *     `ScopeResolutionIndexes` is a read-guidance surface for
- *     consumers, NOT an immutability promise during the resolve phase.
+ *   - **I8 — Two-channel binding lifecycle.**
+ *     `indexes.bindings` is the **finalize-output channel**. After
+ *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
+ *     are deep-frozen by `materializeBindings` and MUST NOT be
+ *     mutated by any post-finalize hook. Treat `indexes.bindings` as
+ *     immutable from the moment `finalizeScopeModel` returns.
+ *
+ *     `indexes.bindingAugmentations` is the **post-finalize
+ *     append-only channel**. Hooks like `populateNamespaceSiblings`
+ *     append cross-file bindings synthesized after finalize (C#
+ *     same-namespace visibility, `using static` member exposure)
+ *     into this channel, NOT into `indexes.bindings`. Inner arrays
+ *     here are NEVER frozen — hooks `push()` directly. Any consumer
+ *     that reads post-finalize workspace bindings MUST query both
+ *     index channels via `lookupBindingsAt`
+ *     (`scope-resolution/scope/walkers.ts`); the helper returns
+ *     finalized refs first, appends unique augmentation refs after,
+ *     and dedupes by `def.nodeId` so finalized metadata wins on
+ *     duplicate defs. Per-`Scope.bindings` local declarations are the
+ *     lexical extraction channel and remain a separate first-tier
+ *     lookup for local shadowing.
+ *
+ *     `Scope.typeBindings` remains mutable post-finalize per I6 (it
+ *     is intentionally not frozen at any point).
+ *
+ *     The `ReadonlyMap<...>` types on `ScopeResolutionIndexes` are
+ *     compile-time read-guidance for consumers; structural mutation
+ *     of `bindingAugmentations` is performed via a deliberate
+ *     `as Map<...>` cast inside the hook implementations and is the
+ *     ONLY sanctioned channel for post-finalize binding fanout.
+ *
+ *     The dev-mode runtime validator
+ *     (`validateBindingsImmutability` in
+ *     `scope-resolution/validate-bindings-immutability.ts`) surfaces
+ *     any drift — i.e. a hook writing to `indexes.bindings` instead
+ *     of `bindingAugmentations`, or producing a non-frozen finalized
+ *     bucket — via `onWarn` when explicitly enabled by
+ *     `NODE_ENV === 'development' || VALIDATE_SEMANTIC_MODEL === '1'`
+ *     (`VALIDATE_SEMANTIC_MODEL=0` is an explicit off switch).
  *
  *   - **I9 — `SemanticModel` is the single authoritative symbol store.**
  *     Every symbol-indexed lookup (key = `nodeId | simpleName |
@@ -244,8 +282,32 @@ export interface ScopeResolver {
      * resolvers that must distinguish "this module exists in the repo"
      * from "this module is external" (Python's fallback resolver, for
      * example).
+     *
+     * `resolutionConfig` is the opaque value returned by
+     * `loadResolutionConfig` (loaded once per workspace pass by the
+     * orchestrator). TypeScript uses this to thread `tsconfig.json` path
+     * aliases through to the standard resolver. Languages that don't
+     * need any extra config ignore the parameter.
+     */
+    resolveImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>, resolutionConfig?: unknown): string | null;
+    /**
+     * Optional one-shot loader for cross-file import-resolution config
+     * (e.g. tsconfig path aliases for TypeScript, go.mod paths for Go,
+     * composer.json autoload for PHP). The orchestrator calls this once
+     * per workspace pass with the repo root and threads the result into
+     * every subsequent `resolveImportTarget` call as the
+     * `resolutionConfig` parameter.
+     *
+     * Languages that don't need any per-workspace config leave this
+     * undefined; the orchestrator threads `undefined` to
+     * `resolveImportTarget` in that case. Returning `null` is also
+     * supported and equivalent to "no config available".
+     *
+     * May be sync or async — the orchestrator awaits the result. The
+     * shape is opaque to the orchestrator (`unknown`); the per-language
+     * `resolveImportTarget` casts it to the language's expected shape.
      */
-    resolveImportTarget(targetRaw: string, fromFile: string, allFilePaths: ReadonlySet<string>): string | null;
+    loadResolutionConfig?(repoPath: string): Promise<unknown> | unknown;
     /**
      * Per-scope binding-merge precedence. The shared finalize pass
      * collects bindings from multiple sources (local declarations,

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.js

@@ -88,14 +88,21 @@
  *     per-(caller, target) collapse semantics require multiple call
  *     sites in the same caller body not produce multiple edges.
  *
- *   - **I3 — `propagateImportedReturnTypes` mutation timing.** The
- *     pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
+ *   - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.**
+ *     The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from
  *     `draftToScope`, NOT frozen). It MUST run AFTER `finalizeScopeModel`
  *     (so `indexes.bindings` is populated) and BEFORE
  *     `resolveReferenceSites` (so resolution sees the propagated types).
  *     The pass also re-runs `followChainPostFinalize` on every scope's
  *     typeBindings because scope-extractor's pass-4 already ran and
  *     missed any chain whose terminal lives in a foreign file.
+ *     Within the pass, files are walked in `indexes.sccs` reverse-
+ *     topological order (leaves first) so multi-hop alias chains
+ *     (e.g. `models.User → service.user → app.user`) collapse to the
+ *     terminal class in a single pass — every importer sees its
+ *     source's already-chain-followed typeBindings. Cyclic SCCs reach
+ *     a partial fixpoint within a single pass without iterating to
+ *     convergence; `ts-circular` only asserts pipeline-no-throw.
  *
  *   - **I4 — `emitReceiverBoundCalls` case order.** Cases are evaluated
  *     in this order; the FIRST that emits an edge wins:
@@ -129,14 +136,45 @@
  *     once per workspace at resolve time), and merging would create a
  *     god-interface that complicates future migrations.
  *
- *   - **I8 — Post-finalize hooks may mutate `Scope.typeBindings` and
- *     `indexes.bindings`.** `propagateImportedReturnTypes` and
- *     `populateNamespaceSiblings` both write to these structures via
- *     `as Map<...>` casts through `ReadonlyMap` facades. Downstream
- *     consumers MUST NOT freeze or snapshot these maps before all
- *     post-finalize hooks have run. The `ReadonlyMap<...>` type on
- *     `ScopeResolutionIndexes` is a read-guidance surface for
- *     consumers, NOT an immutability promise during the resolve phase.
+ *   - **I8 — Two-channel binding lifecycle.**
+ *     `indexes.bindings` is the **finalize-output channel**. After
+ *     `finalizeScopeModel` returns, its inner `BindingRef[]` arrays
+ *     are deep-frozen by `materializeBindings` and MUST NOT be
+ *     mutated by any post-finalize hook. Treat `indexes.bindings` as
+ *     immutable from the moment `finalizeScopeModel` returns.
+ *
+ *     `indexes.bindingAugmentations` is the **post-finalize
+ *     append-only channel**. Hooks like `populateNamespaceSiblings`
+ *     append cross-file bindings synthesized after finalize (C#
+ *     same-namespace visibility, `using static` member exposure)
+ *     into this channel, NOT into `indexes.bindings`. Inner arrays
+ *     here are NEVER frozen — hooks `push()` directly. Any consumer
+ *     that reads post-finalize workspace bindings MUST query both
+ *     index channels via `lookupBindingsAt`
+ *     (`scope-resolution/scope/walkers.ts`); the helper returns
+ *     finalized refs first, appends unique augmentation refs after,
+ *     and dedupes by `def.nodeId` so finalized metadata wins on
+ *     duplicate defs. Per-`Scope.bindings` local declarations are the
+ *     lexical extraction channel and remain a separate first-tier
+ *     lookup for local shadowing.
+ *
+ *     `Scope.typeBindings` remains mutable post-finalize per I6 (it
+ *     is intentionally not frozen at any point).
+ *
+ *     The `ReadonlyMap<...>` types on `ScopeResolutionIndexes` are
+ *     compile-time read-guidance for consumers; structural mutation
+ *     of `bindingAugmentations` is performed via a deliberate
+ *     `as Map<...>` cast inside the hook implementations and is the
+ *     ONLY sanctioned channel for post-finalize binding fanout.
+ *
+ *     The dev-mode runtime validator
+ *     (`validateBindingsImmutability` in
+ *     `scope-resolution/validate-bindings-immutability.ts`) surfaces
+ *     any drift — i.e. a hook writing to `indexes.bindings` instead
+ *     of `bindingAugmentations`, or producing a non-frozen finalized
+ *     bucket — via `onWarn` when explicitly enabled by
+ *     `NODE_ENV === 'development' || VALIDATE_SEMANTIC_MODEL === '1'`
+ *     (`VALIDATE_SEMANTIC_MODEL=0` is an explicit off switch).
  *
  *   - **I9 — `SemanticModel` is the single authoritative symbol store.**
  *     Every symbol-indexed lookup (key = `nodeId | simpleName |