arceus-s 1.6.4

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

@@ -0,0 +1,218 @@
+/**
+ * `runScopeResolution` — generic registry-primary resolution
+ * orchestrator.
+ *
+ *     ParsedFile[]  (one per file via `extractParsedFile`)
+ *        │  finalizeScopeModel(  + provider hooks adapted to FinalizeHooks)
+ *        ▼
+ *     ScopeResolutionIndexes
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReceiverBoundCalls (FIRST — see Contract Invariant I1)
+ *        │  emitFreeCallFallback   (THEN)
+ *        │  emitReferencesViaLookup (LAST — uses handledSites)
+ *        │  emitImportEdges
+ *        ▼
+ *     KnowledgeGraph
+ *
+ * Per-language entry points (e.g. `runPythonScopeResolution` in
+ * `languages/python/scope-resolver.ts`) construct an `ScopeResolver` and
+ * delegate here.
+ *
+ * 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';
+import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js';
+import { propagateImportedReturnTypes } from '../passes/imported-return-types.js';
+import { emitReceiverBoundCalls } from '../passes/receiver-bound-calls.js';
+import { emitFreeCallFallback } from '../passes/free-call-fallback.js';
+import { emitReferencesViaLookup } from '../graph-bridge/references-to-edges.js';
+import { emitImportEdges } from '../graph-bridge/imports-to-edges.js';
+import { buildWorkspaceResolutionIndex } from '../workspace-index.js';
+import { logger } from '../../../logger.js';
+export function runScopeResolution(input, provider) {
+    const { graph, files } = input;
+    const onWarn = input.onWarn ?? (() => { });
+    const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+    const tStart = PROF ? process.hrtime.bigint() : 0n;
+    let fileContents;
+    const getFileContents = () => {
+        if (fileContents === undefined) {
+            fileContents = new Map();
+            for (const f of files)
+                fileContents.set(f.path, f.content);
+        }
+        return fileContents;
+    };
+    // ── Phase 1: extract each file → ParsedFile ────────────────────────────
+    const parsedFiles = [];
+    let filesSkipped = 0;
+    const treeCache = input.treeCache;
+    const preExtracted = input.preExtractedParsedFiles;
+    let preExtractedHits = 0;
+    for (const file of files) {
+        let parsed;
+        // Fast path: a worker (during the parse phase) already produced a
+        // ParsedFile for this file via `extractParsedFile`. Reuse it
+        // directly — skips a tree-sitter re-parse on the main thread.
+        if (preExtracted !== undefined) {
+            parsed = preExtracted.get(file.path);
+            if (parsed !== undefined)
+                preExtractedHits++;
+        }
+        if (parsed === undefined) {
+            const cachedTree = treeCache?.get(file.path);
+            parsed = extractParsedFile(provider.languageProvider, file.content, file.path, onWarn, cachedTree);
+            if (parsed === undefined) {
+                filesSkipped++;
+                continue;
+            }
+        }
+        provider.populateOwners(parsed);
+        parsedFiles.push(parsed);
+    }
+    if (PROF && preExtracted !== undefined) {
+        logger.warn(`[scope-resolution prof] pre-extracted hits: ${preExtractedHits}/${files.length}`);
+    }
+    provider.populateWorkspaceOwners?.(parsedFiles, { fileContents: getFileContents() });
+    // Reconcile scope-resolution's ownership view into the SemanticModel.
+    // See `reconcile-ownership.ts` for the full rationale (Contract
+    // Invariant I9). Debug-mode validator runs immediately after to
+    // catch drift between `parsed.localDefs` and the registries.
+    //
+    // PHASE BOUNDARY: `input.model` is `MutableSemanticModel` up to this
+    // point (write phase: reconciliation). After this line no further
+    // writes are expected — downstream passes consume `readonlyModel`
+    // (narrowed to `SemanticModel`) so accidental writes would surface
+    // as type errors.
+    reconcileOwnership(parsedFiles, input.model);
+    validateOwnershipParity(parsedFiles, input.model, onWarn);
+    const readonlyModel = input.model;
+    if (parsedFiles.length === 0) {
+        return {
+            filesProcessed: 0,
+            filesSkipped,
+            importsEmitted: 0,
+            resolve: { sitesProcessed: 0, referencesEmitted: 0, unresolved: 0 },
+            referenceEdgesEmitted: 0,
+            referenceSkipped: 0,
+        };
+    }
+    const tExtract = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 2: finalize → ScopeResolutionIndexes ─────────────────────────
+    const allFilePaths = new Set(parsedFiles.map((f) => f.filePath));
+    const nodeLookup = buildGraphNodeLookup(graph);
+    const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup);
+    const extendsOnlyMroByClassDefId = provider.buildExtendsOnlyMro?.(graph, parsedFiles, nodeLookup);
+    const resolutionConfig = input.resolutionConfig;
+    const finalized = finalizeScopeModel(parsedFiles, {
+        hooks: {
+            resolveImportTarget: (targetRaw, fromFile) => provider.resolveImportTarget(targetRaw, fromFile, allFilePaths, resolutionConfig),
+            expandsWildcardTo: (targetModuleScope) => provider.expandsWildcardTo?.(targetModuleScope, parsedFiles) ?? [],
+            mergeBindings: (existing, incoming, scopeId) => provider.mergeBindings(existing, incoming, scopeId),
+        },
+    });
+    // Replace the empty MethodDispatchIndex that finalizeScopeModel
+    // builds by design with the populated one derived from the
+    // language's MRO. Spread produces a fresh `ScopeResolutionIndexes`
+    // instead of mutating the finalized result through an `as` cast —
+    // downstream passes get an object whose readonly guarantees match
+    // the type system.
+    const indexes = {
+        ...finalized,
+        methodDispatch: buildPopulatedMethodDispatch(mroByClassDefId, extendsOnlyMroByClassDefId),
+    };
+    // Build the workspace resolution index ONCE — scope-valued lookups
+    // (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel`
+    // cannot carry. Must run AFTER `populateOwners` (so owned defs are
+    // attributed correctly) and AFTER finalize (so module-scope
+    // bindings are available).
+    const workspaceIndex = buildWorkspaceResolutionIndex(parsedFiles);
+    // 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) {
+        provider.populateNamespaceSiblings(parsedFiles, indexes, {
+            fileContents: getFileContents(),
+            treeCache,
+        });
+    }
+    const tFinalize = PROF ? process.hrtime.bigint() : 0n;
+    // Cross-package namespace typeBinding mirroring. Runs before
+    // propagateImportedReturnTypes so the SCC-ordered pass sees the
+    // mirrored bindings.
+    if (provider.mirrorNamespaceTypeBindings !== undefined) {
+        provider.mirrorNamespaceTypeBindings(parsedFiles, indexes, workspaceIndex);
+    }
+    // Cross-file return-type propagation (Contract Invariant I3 timing:
+    // 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);
+    }
+    if (provider.populateRangeBindings !== undefined) {
+        provider.populateRangeBindings(parsedFiles, indexes, {
+            fileContents: getFileContents(),
+            treeCache,
+        });
+    }
+    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,
+    };
+    const { referenceIndex, stats: resolveStats } = resolveReferenceSites({
+        scopes: indexes,
+        providers: registryProviders,
+    });
+    const tResolve = PROF ? process.hrtime.bigint() : 0n;
+    // ── Phase 4: emit graph edges (LOAD-BEARING ORDER — see I1) ────────────
+    const handledSites = new Set();
+    const receiverExtras = emitReceiverBoundCalls(graph, indexes, parsedFiles, nodeLookup, handledSites, provider, workspaceIndex, readonlyModel);
+    const unresolvedReceiverExtras = provider.emitUnresolvedReceiverEdges !== undefined
+        ? provider.emitUnresolvedReceiverEdges(graph, indexes, parsedFiles, nodeLookup, handledSites, readonlyModel)
+        : 0;
+    const freeCallExtras = emitFreeCallFallback(graph, indexes, parsedFiles, nodeLookup, referenceIndex, handledSites, readonlyModel, workspaceIndex, {
+        allowGlobalFallback: provider.allowGlobalFreeCallFallback === true,
+        isFileLocalDef: provider.isFileLocalDef,
+        isCallableVisibleFromCaller: provider.isCallableVisibleFromCaller,
+    });
+    const { emitted, skipped } = emitReferencesViaLookup(graph, indexes, referenceIndex, nodeLookup, handledSites);
+    const importsEmitted = emitImportEdges(graph, indexes.imports, indexes.scopeTree, provider.importEdgeReason);
+    if (PROF) {
+        const tEnd = process.hrtime.bigint();
+        const ns = (a, b) => Number(b - a) / 1_000_000;
+        logger.warn(`[scope-resolution prof] extract=${ns(tStart, tExtract).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)`);
+    }
+    return {
+        filesProcessed: parsedFiles.length,
+        filesSkipped,
+        importsEmitted,
+        resolve: resolveStats,
+        referenceEdgesEmitted: emitted + receiverExtras + unresolvedReceiverExtras + freeCallExtras,
+        referenceSkipped: skipped,
+    };
+}

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/namespace-targets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build a per-file `localName → targetFilePath` map over the file's
+ * module-scope namespace-kind import edges.
+ *
+ * Namespace imports (`import X`, `import X as Y`) bind a name that can
+ * appear as a receiver in member calls (`X.foo()`, `Y.foo()`). Named
+ * imports (`from X import foo`) bind `foo` directly and are a different
+ * resolution path.
+ *
+ * Why not consult `scope.bindings` directly? For namespace imports
+ * where the target module has no self-named def,
+ * `finalize-algorithm.ts:540` skips binding creation entirely, so
+ * `scope.bindings.get('X')` returns undefined. We iterate
+ * `indexes.imports` to recover those targets.
+ *
+ * Next-consumer contract: any language with namespace-style imports
+ * (TypeScript `import * as X`, Java static import, Ruby `require`)
+ * uses this directly. `ParsedImport.kind === 'namespace'` is the
+ * cross-language hook.
+ *
+ * Scope-chain concern (verified 2026-04-21): `pythonImportOwningScope`
+ * documents that function-local and class-body imports bind to the
+ * inner scope, which would make a module-only read incomplete. In
+ * practice `finalize-algorithm` places ALL of a file's ImportEdges
+ * onto `indexes.imports[moduleScope]` regardless of where the
+ * `import` statement appears — the integration fixtures
+ * `python-function-local-namespace-import` and
+ * `python-class-body-namespace-import` both emit correct CALLS edges
+ * with reason "namespace-receiver", demonstrating that the module-
+ * scope read is sufficient today. If finalize routing ever changes to
+ * honor the hook's per-scope contract, this function must walk the
+ * reference-site scope chain (mirror `findExportedDefByName`).
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+export declare function collectNamespaceTargets(parsed: ParsedFile, scopes: ScopeResolutionIndexes): Map<string, string[]>;

package/dist/core/ingestion/scope-resolution/scope/namespace-targets.js

@@ -0,0 +1,58 @@
+/**
+ * Build a per-file `localName → targetFilePath` map over the file's
+ * module-scope namespace-kind import edges.
+ *
+ * Namespace imports (`import X`, `import X as Y`) bind a name that can
+ * appear as a receiver in member calls (`X.foo()`, `Y.foo()`). Named
+ * imports (`from X import foo`) bind `foo` directly and are a different
+ * resolution path.
+ *
+ * Why not consult `scope.bindings` directly? For namespace imports
+ * where the target module has no self-named def,
+ * `finalize-algorithm.ts:540` skips binding creation entirely, so
+ * `scope.bindings.get('X')` returns undefined. We iterate
+ * `indexes.imports` to recover those targets.
+ *
+ * Next-consumer contract: any language with namespace-style imports
+ * (TypeScript `import * as X`, Java static import, Ruby `require`)
+ * uses this directly. `ParsedImport.kind === 'namespace'` is the
+ * cross-language hook.
+ *
+ * Scope-chain concern (verified 2026-04-21): `pythonImportOwningScope`
+ * documents that function-local and class-body imports bind to the
+ * inner scope, which would make a module-only read incomplete. In
+ * practice `finalize-algorithm` places ALL of a file's ImportEdges
+ * onto `indexes.imports[moduleScope]` regardless of where the
+ * `import` statement appears — the integration fixtures
+ * `python-function-local-namespace-import` and
+ * `python-class-body-namespace-import` both emit correct CALLS edges
+ * with reason "namespace-receiver", demonstrating that the module-
+ * scope read is sufficient today. If finalize routing ever changes to
+ * honor the hook's per-scope contract, this function must walk the
+ * reference-site scope chain (mirror `findExportedDefByName`).
+ */
+export function collectNamespaceTargets(parsed, scopes) {
+    const out = new Map();
+    const moduleEdges = scopes.imports.get(parsed.moduleScope);
+    if (moduleEdges === undefined)
+        return out;
+    const namespaceLocals = new Set();
+    for (const imp of parsed.parsedImports) {
+        if (imp.kind === 'namespace')
+            namespaceLocals.add(imp.localName);
+    }
+    for (const edge of moduleEdges) {
+        if (edge.targetFile === null)
+            continue;
+        if (!namespaceLocals.has(edge.localName))
+            continue;
+        let targets = out.get(edge.localName);
+        if (targets === undefined) {
+            targets = [];
+            out.set(edge.localName, targets);
+        }
+        if (!targets.includes(edge.targetFile))
+            targets.push(edge.targetFile);
+    }
+    return out;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Scope-chain lookup primitives shared across language providers.
+ *
+ * Five functions:
+ *   - `findReceiverTypeBinding` — walk scope.typeBindings up the chain
+ *     for a receiver name.
+ *   - `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
+ *     class / function) by simpleName.
+ *
+ * Next-consumer contract: every OO or module-capable language hits the
+ * same pre-finalize / post-finalize binding split and the same
+ * "resolve member on owner with MRO" pattern. All four are reusable
+ * as-is for TypeScript, Java, Kotlin, Ruby, etc.
+ */
+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.
+ *
+ * Semantics widened historically from `'Class' | 'Interface'` to cover
+ * C#-shape languages (struct, record, enum, trait). Languages that emit
+ * only `'Class'` are unaffected — the extra kinds never appear in their
+ * parsed output.
+ */
+export declare function isClassLike(t: string): boolean;
+/**
+ * Walk the scope chain from `startScope` looking for a typeBinding
+ * named `receiverName`. Returns the TypeRef or undefined if no binding
+ * exists in the chain.
+ */
+export declare function findReceiverTypeBinding(startScope: ScopeId, receiverName: string, scopes: ScopeResolutionIndexes): TypeRef | undefined;
+/**
+ * Look up a class-like binding by name in the given scope's chain.
+ *
+ * "Class-like" covers `Class | Interface | Struct | Record | Enum |
+ * Trait` via the shared `isClassLike` predicate — every kind that
+ * collapses to `@scope.class` in the scope-extractor query contract.
+ *
+ * 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. 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.
+ */
+export declare function findClassBindingInScope(startScope: ScopeId, receiverName: string, scopes: ScopeResolutionIndexes): SymbolDefinition | undefined;
+/**
+ * Look up a callable (Function/Method/Constructor) by name in the
+ * given scope's chain. Uses the dual-source pattern (scope.bindings +
+ * `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.
+ */
+export declare function findCallableBindingInScope(startScope: ScopeId, callableName: string, scopes: ScopeResolutionIndexes): SymbolDefinition | undefined;
+/**
+ * Populate `ownerId` on every def structurally owned by a Class
+ * scope — methods (defs in Function scopes whose parent is Class)
+ * and class-body fields (defs directly in Class scopes).
+ *
+ * Generic OO ownership rule. Languages that want richer ownership
+ * (e.g. inner-class qualification) can compose with this as a base
+ * step.
+ *
+ * Mutates `parsed.localDefs` in place via type cast — `SymbolDefinition`
+ * is `readonly` for consumers but the extractor returns plain objects.
+ * Defs are shared by reference between `localDefs` and `Scope.ownedDefs`,
+ * so this single mutation is visible from both sides.
+ */
+export declare function populateClassOwnedMembers(parsed: ParsedFile): void;
+/**
+ * Walk a scope chain upward looking for the innermost enclosing
+ * Class scope and return that class's def. Used by per-language
+ * `super` receiver branches to discover the dispatch base.
+ */
+export declare function findEnclosingClassDef(startScope: ScopeId, scopes: ScopeResolutionIndexes): SymbolDefinition | undefined;
+/**
+ * Find a free-function def by simple name across all parsed files,
+ * preferring scope-chain-visible bindings (import + finalized scope
+ * bindings) before falling back to a workspace-wide simple-name scan.
+ *
+ * The fallback scan is intentionally loose so per-language compound
+ * resolvers can find a callable target even when the binding chain
+ * doesn't surface it (e.g. cross-package re-exports the finalize
+ * pass missed). Strictly-typed languages may want to disable the
+ * fallback by simply not calling this helper from their compound
+ * resolver.
+ */
+export declare function findExportedDefByName(name: string, inScope: ScopeId, scopes: ScopeResolutionIndexes, index: WorkspaceResolutionIndex): SymbolDefinition | undefined;
+/**
+ * Find a member of a class by simple name — delegates to
+ * `SemanticModel.methods` (methods / functions / constructors) with a
+ * fallback to `SemanticModel.fields` (properties / fields /
+ * variables). After `runScopeResolution`'s reconciliation pass
+ * populates both registries from `parsed.localDefs[i].ownerId`
+ * (post-`populateOwners`), this is the single authoritative view of
+ * class membership — no parallel scope-resolution index needed.
+ *
+ * Returns the first-seen overload for methods without arity or
+ * return-type narrowing. Callers that need arity-aware dispatch use
+ * `lookupMethodByOwner(owner, name, argCount)` directly.
+ */
+export declare function findOwnedMember(ownerDefId: string, memberName: string, model: SemanticModel): SymbolDefinition | undefined;
+/**
+ * Find a file-level def (top-of-module class / function / variable)
+ * by simple name — consults the target file's Module scope's
+ * finalized bindings. Only defs bound at module-scope with
+ * `origin === 'local'` qualify, matching the historical
+ * "module-export-visible" semantics. Class methods and class-body
+ * fields bind at their containing class scope and are naturally
+ * excluded.
+ *
+ * Reads from `WorkspaceResolutionIndex.moduleScopeByFile` (scope-tied
+ * 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;