cgraphx 2.0.1 → 2.0.3

package/dist/core/code/shared/scope-resolution/registries/evidence.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * `composeEvidence` — translate accumulated raw signals per candidate
+ * into a `ResolutionEvidence[]` using the authoritative `EvidenceWeights`
+ * map (RFC §4.3 + Appendix A; Ring 2 SHARED #917).
+ *
+ * Each `RawSignals` record describes what was observed about a candidate
+ * during the 7-step walk: where it was found, at what depth, whether
+ * anything corroborates it. This module turns those raw facts into the
+ * typed evidence list attached to the outgoing `Resolution`.
+ *
+ * **Every weight comes from `EvidenceWeights`.** No inline magic numbers.
+ * Extends issue #429 (centralize hardcoded confidence values).
+ *
+ * **Confidence compose rule.** Signals add; the sum is capped at 1.0 at
+ * the call site (inside `lookupCore`). This module only emits the list;
+ * it does NOT compute the capped sum so callers can inspect per-signal
+ * contributions for debugging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeEvidence = composeEvidence;
+exports.confidenceFromEvidence = confidenceFromEvidence;
+const evidence_weights_js_1 = require("../evidence-weights.js");
+/**
+ * Compose the raw signals into a stable `ResolutionEvidence[]` list.
+ *
+ * Emission order mirrors the `EvidenceWeights` layout: where-found →
+ * type-binding → corroborators → arity → degraded. Stable order makes
+ * the per-signal contributions easy to reason about in tests.
+ */
+function composeEvidence(signals) {
+    const out = [];
+    // ── Where-found visibility ─────────────────────────────────────────────
+    if (signals.origin !== undefined) {
+        const baseWeight = getOriginWeight(signals.origin);
+        const capped = signals.viaUnlinkedImport
+            ? baseWeight * evidence_weights_js_1.EvidenceWeights.unlinkedImportMultiplier
+            : baseWeight;
+        const evidenceKind = whereFoundEvidenceKind(signals.origin);
+        out.push({
+            kind: evidenceKind,
+            weight: capped,
+            ...(signals.viaUnlinkedImport
+                ? { note: `via unresolved import (${evidence_weights_js_1.EvidenceWeights.unlinkedImportMultiplier}× cap)` }
+                : {}),
+        });
+    }
+    // ── Scope-chain depth deduction (per-hop, only meaningful for lexical
+    // hits where scopeChainDepth ≥ 1). Depth 0 = no deduction; depth N ≥ 1
+    // emits a single `scope-chain` evidence with the accumulated penalty.
+    if (signals.scopeChainDepth !== undefined && signals.scopeChainDepth > 0) {
+        out.push({
+            kind: 'scope-chain',
+            weight: evidence_weights_js_1.EvidenceWeights.scopeChainPerDepth * signals.scopeChainDepth,
+            note: `depth=${signals.scopeChainDepth}`,
+        });
+    }
+    // ── Type-binding / MRO path ────────────────────────────────────────────
+    if (signals.typeBindingMroDepth !== undefined) {
+        out.push({
+            kind: 'type-binding',
+            weight: (0, evidence_weights_js_1.typeBindingWeightAtDepth)(signals.typeBindingMroDepth),
+            note: `mroDepth=${signals.typeBindingMroDepth}`,
+        });
+    }
+    // ── Owner match (explanatory for debug) ────────────────────────────────
+    if (signals.ownerMatch === true) {
+        out.push({
+            kind: 'owner-match',
+            weight: evidence_weights_js_1.EvidenceWeights.ownerMatch,
+        });
+    }
+    // ── Kind match (always present; weight 0; retained for debuggability) ──
+    out.push({
+        kind: 'kind-match',
+        weight: evidence_weights_js_1.EvidenceWeights.kindMatch,
+    });
+    // ── Arity ──────────────────────────────────────────────────────────────
+    if (signals.arityVerdict !== undefined) {
+        const weight = signals.arityVerdict === 'compatible'
+            ? evidence_weights_js_1.EvidenceWeights.arityMatchCompatible
+            : signals.arityVerdict === 'incompatible'
+                ? evidence_weights_js_1.EvidenceWeights.arityMatchIncompatible
+                : evidence_weights_js_1.EvidenceWeights.arityMatchUnknown;
+        out.push({
+            kind: 'arity-match',
+            weight,
+            note: signals.arityVerdict,
+        });
+    }
+    // ── Dynamic-unresolved (degraded signal) ───────────────────────────────
+    if (signals.dynamicUnresolved === true) {
+        out.push({
+            kind: 'dynamic-import-unresolved',
+            weight: evidence_weights_js_1.EvidenceWeights.dynamicImportUnresolved,
+        });
+    }
+    return out;
+}
+/**
+ * Sum evidence weights and clamp to `[0, 1]`. Separate from `composeEvidence`
+ * so tests can inspect the raw evidence list.
+ */
+function confidenceFromEvidence(evidence) {
+    let sum = 0;
+    for (const e of evidence)
+        sum += e.weight;
+    if (sum < 0)
+        return 0;
+    if (sum > 1)
+        return 1;
+    return sum;
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+function getOriginWeight(origin) {
+    switch (origin) {
+        case 'local':
+            return evidence_weights_js_1.EvidenceWeights.local;
+        case 'import':
+            return evidence_weights_js_1.EvidenceWeights.import;
+        case 'reexport':
+            return evidence_weights_js_1.EvidenceWeights.reexport;
+        case 'namespace':
+            return evidence_weights_js_1.EvidenceWeights.namespace;
+        case 'wildcard':
+            return evidence_weights_js_1.EvidenceWeights.wildcard;
+        case 'global-qualified':
+            return evidence_weights_js_1.EvidenceWeights.globalQualified;
+        case 'global-name':
+            // Reserved for Ring 3 byName global index. `lookupCore` today only
+            // emits `'global-qualified'` (via `lookupQualified`, dotted-name
+            // fallback); no code path constructs `origin: 'global-name'` yet.
+            // Kept here so the Appendix A weight stays live and `composeEvidence`
+            // remains exhaustive over the origin union.
+            return evidence_weights_js_1.EvidenceWeights.globalName;
+    }
+}
+function whereFoundEvidenceKind(origin) {
+    switch (origin) {
+        case 'local':
+            return 'local';
+        case 'import':
+        case 'reexport':
+        case 'namespace':
+        case 'wildcard':
+            return 'import';
+        case 'global-qualified':
+            return 'global-qualified';
+        case 'global-name':
+            return 'global-name';
+    }
+}

package/dist/core/code/shared/scope-resolution/registries/field-registry.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * `FieldRegistry` — scope-aware lookup for field / property / variable
+ * access (RFC §4.4; Ring 2 SHARED #917).
+ *
+ * Thin wrapper over `lookupCore`, specialized for data-member kinds:
+ *
+ *   - `acceptedKinds` = Variable / Property / Const / Static.
+ *   - `useReceiverTypeBinding` is **true** — fields are resolved against
+ *     the receiver type's MRO first, then via the lexical chain for
+ *     free variables.
+ *   - `callsite` is not meaningful for field access (no arity), but the
+ *     `explicitReceiver` and `ownerScopedContributor` knobs are.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFieldRegistry = buildFieldRegistry;
+const lookup_core_js_1 = require("./lookup-core.js");
+const context_js_1 = require("./context.js");
+function buildFieldRegistry(ctx) {
+    return {
+        lookup(name, scope, options = {}) {
+            const params = {
+                acceptedKinds: context_js_1.FIELD_KINDS,
+                useReceiverTypeBinding: true,
+                ownerScopedContributor: options.ownerScopedContributor ?? null,
+                ...(options.explicitReceiver !== undefined
+                    ? { explicitReceiver: options.explicitReceiver }
+                    : {}),
+            };
+            return (0, lookup_core_js_1.lookupCore)(name, scope, params, ctx);
+        },
+    };
+}

package/dist/core/code/shared/scope-resolution/registries/lookup-core.js

@@ -0,0 +1,392 @@
+"use strict";
+/**
+ * `lookupCore` — the shared 7-step canonical resolution algorithm
+ * (RFC §4.2; Ring 2 SHARED #917).
+ *
+ * Pure function. Given a name, a starting scope, and per-kind parameters,
+ * walks lexical scopes + optional type-binding MRO + optional owner
+ * contributor + global qualified-name fallback, and returns a ranked
+ * `Resolution[]` with per-candidate evidence.
+ *
+ * All three public registries (`ClassRegistry` / `MethodRegistry` /
+ * `FieldRegistry`) dispatch into this function, differing only in the
+ * parameters they pass. The CHOICE of which steps fire is expressed
+ * through `LookupParams`, not through different algorithms per kind.
+ *
+ * ## Algorithm (RFC §4.2, verbatim names)
+ *
+ * **Step 1 — Lexical scope-chain walk.** From `startScope`, walk
+ *   parent-ward. At each scope, consult `scope.bindings.get(name)`:
+ *     - Filter candidates whose `def.type ∈ acceptedKinds`.
+ *     - For each surviving candidate, record a raw signal with the
+ *       binding's origin + the current scope-chain depth.
+ *     - **Hard shadow.** If `bindings.get(name)` is non-empty (including
+ *       non-kind-matching candidates), stop walking. The name is
+ *       lexically bound here; outer scopes are not consulted.
+ *
+ * **Step 2 — Type-binding resolution.** When `useReceiverTypeBinding`
+ *   is true, resolve the receiver's type at `startScope` (from
+ *   `scope.typeBindings`), then walk the MRO via
+ *   `MethodDispatchIndex.mroFor(ownerDefId)`. Membership per owner comes
+ *   through an optional `RegistryContext.ownedMembersByOwner` hook when
+ *   supplied (`undefined` → fall back to `defs.byId`; `[]` → indexed
+ *   miss), otherwise via the compatibility fallback scan over
+ *   `defs.byId`; each hit records a raw signal with the owner's
+ *   MRO depth.
+ *
+ * **Step 3 — Owner-scoped contributor.** When
+ *   `params.ownerScopedContributor` is present, merge its `byName(name)`
+ *   hits with `origin: 'local'` (they are declared directly on the
+ *   receiver). Distinct from Step 2 — Step 2 walks the MRO; Step 3 only
+ *   looks at the directly-declared owner members.
+ *
+ * **Step 4 — Kind filter (emit `kind-match` evidence).** Already
+ *   applied during Steps 1-3; this step just adds a `kind-match` signal
+ *   at weight 0 to every candidate for debuggability (so the evidence
+ *   array is self-describing).
+ *
+ * **Step 5 — Arity filter.** Call `providers.arityCompatibility(callsite,
+ *   def)` per surviving candidate. Verdicts: `compatible` / `unknown` /
+ *   `incompatible`. If at least one candidate is `compatible`, drop
+ *   `incompatible` ones. Otherwise keep all (the penalty weight alone
+ *   will rank them lower but they remain in the result).
+ *
+ * **Step 6 — Global fallback.** When Steps 1-3 produced **no**
+ *   candidates and the name contains a `.`, consult the
+ *   `QualifiedNameIndex` via `lookupQualified` — see §4.5. The `scope`
+ *   argument is NOT passed here because global lookup is scope-agnostic.
+ *
+ * **Step 7 — Rank + tie-break.** Compose evidence, compute confidence
+ *   (sum capped at 1.0), sort by the RFC Appendix B cascade.
+ *
+ * ## What this module does NOT do
+ *
+ *   - No AST reads (pure data in, pure data out).
+ *   - No `cgraph/` imports.
+ *   - No language switches. Language-specific behavior flows exclusively
+ *     through `providers.*` and the `params` object.
+ *   - No caching. Callers that want memoization can wrap this function.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupCore = lookupCore;
+const evidence_js_1 = require("./evidence.js");
+const tie_breaks_js_1 = require("./tie-breaks.js");
+const lookup_qualified_js_1 = require("./lookup-qualified.js");
+/**
+ * Run the 7-step lookup. Returns a non-empty `Resolution[]` when any
+ * candidate was found; an empty array otherwise. Callers consume `[0]`
+ * for the best answer and optionally inspect the rest for alternates.
+ */
+function lookupCore(name, startScope, params, ctx) {
+    const acceptedKinds = new Set(params.acceptedKinds);
+    const perCandidate = new Map();
+    // ── Step 1: lexical scope-chain walk ──────────────────────────────────
+    //
+    // SKIPPED for a NAMED explicit receiver. `recv.name` names a MEMBER of
+    // whatever `recv` denotes; it is not a lexical reference to `name`, so a
+    // binding of the bare tail name in an enclosing scope is never the right
+    // answer. Steps 2 and 3 (receiver type / owner members) are the routes.
+    //
+    // Without this, `options.baseUrl` bound to an unrelated function-local
+    // `const baseUrl` in the same file. This is the residual half of the defect
+    // JS/TS block scopes narrowed in #2699 — blocks moved nested-block locals
+    // off the chain, but a local declared directly in the function body stayed
+    // on it, and no amount of extra scopes reaches that case.
+    //
+    // `this` / `self` are deliberately EXEMPT. For a self-receiver the members
+    // and the lexical chain legitimately overlap — a class body is itself a
+    // scope that binds its members — so Step 1 is a real resolution route
+    // there, not a coincidence. Measured on a 762-file corpus: skipping Step 1
+    // for every explicit receiver dropped 711 edges, of which 43 were
+    // `this.member` reads reaching their own owner. Exempting the self names
+    // keeps those and still removes the 668 named-receiver false positives.
+    const skipLexical = params.explicitReceiver !== undefined &&
+        !IMPLICIT_RECEIVERS.includes(params.explicitReceiver.name);
+    const lexicalShadowed = skipLexical
+        ? false
+        : walkLexicalChain(name, startScope, acceptedKinds, ctx, perCandidate);
+    // ── Step 2: type-binding / MRO walk (methods/fields) ──────────────────
+    if (params.useReceiverTypeBinding && ctx.methodDispatch !== undefined) {
+        walkReceiverTypeBinding(name, startScope, acceptedKinds, params, ctx, perCandidate);
+    }
+    // ── Step 3: owner-scoped contributor ──────────────────────────────────
+    if (params.ownerScopedContributor !== null) {
+        seedFromOwnerScopedContributor(name, params.ownerScopedContributor, acceptedKinds, perCandidate);
+    }
+    // ── Step 4: kind-match evidence (emitted by composeEvidence directly) ──
+    // Handled inside `composeEvidence`.
+    // ── Step 5: arity filter ──────────────────────────────────────────────
+    if (params.callsite !== undefined) {
+        applyArityFilter(params.callsite, perCandidate, ctx);
+    }
+    // ── Step 6: global fallback (only when Steps 1-3 produced nothing) ──
+    if (perCandidate.size === 0 && !lexicalShadowed && name.includes('.')) {
+        const globals = (0, lookup_qualified_js_1.lookupQualified)(name, { acceptedKinds: params.acceptedKinds }, ctx);
+        if (globals.length > 0)
+            return globals;
+    }
+    if (perCandidate.size === 0)
+        return EMPTY;
+    // ── Step 7: compose evidence + rank ──────────────────────────────────
+    return rankCandidates(perCandidate);
+}
+function ensureCandidate(perCandidate, def) {
+    const existing = perCandidate.get(def.nodeId);
+    if (existing !== undefined)
+        return existing;
+    const fresh = {
+        def,
+        signals: { kindMatch: true },
+        tieBreakKey: { scopeDepth: 0, mroDepth: 0, origin: 'local' },
+    };
+    perCandidate.set(def.nodeId, fresh);
+    return fresh;
+}
+// ─── Step 1 implementation ─────────────────────────────────────────────────
+/**
+ * Walk the lexical scope chain from `startScope` upward. Returns `true`
+ * iff a scope with any `bindings.get(name)` entries was found — the
+ * caller uses this to decide whether to run the global fallback.
+ */
+function walkLexicalChain(name, startScope, acceptedKinds, ctx, perCandidate) {
+    let currentId = startScope;
+    let depth = 0;
+    const visited = new Set();
+    while (currentId !== null) {
+        if (visited.has(currentId))
+            return false;
+        visited.add(currentId);
+        const scope = ctx.scopes.getScope(currentId);
+        if (scope === undefined)
+            return false;
+        const bindings = scope.bindings.get(name);
+        if (bindings !== undefined && bindings.length > 0) {
+            for (const binding of bindings) {
+                if (!acceptedKinds.has(binding.def.type))
+                    continue;
+                recordLexicalHit(perCandidate, binding, depth);
+            }
+            return true; // hard shadow regardless of kind-filter survivorship
+        }
+        currentId = scope.parent;
+        depth++;
+    }
+    return false;
+}
+function recordLexicalHit(perCandidate, binding, scopeChainDepth) {
+    const state = ensureCandidate(perCandidate, binding.def);
+    state.signals.origin = binding.origin;
+    state.signals.scopeChainDepth = scopeChainDepth;
+    if (binding.via?.linkStatus === 'unresolved') {
+        state.signals.viaUnlinkedImport = true;
+    }
+    if (binding.via?.kind === 'dynamic-unresolved') {
+        state.signals.dynamicUnresolved = true;
+    }
+    state.tieBreakKey.scopeDepth = scopeChainDepth;
+    state.tieBreakKey.origin = binding.origin;
+}
+// ─── Step 2 implementation ─────────────────────────────────────────────────
+function walkReceiverTypeBinding(name, startScope, acceptedKinds, params, ctx, perCandidate) {
+    const ownerDefId = resolveReceiverOwner(startScope, params, ctx);
+    if (ownerDefId === undefined)
+        return;
+    if (ctx.methodDispatch === undefined)
+        return;
+    const ownerDef = ctx.defs.get(ownerDefId);
+    if (ownerDef === undefined)
+        return;
+    // Walk the owner itself at depth 0, then its MRO chain.
+    const walk = [ownerDefId, ...ctx.methodDispatch.mroFor(ownerDefId)];
+    let mroDepth = 0;
+    for (const currentOwnerId of walk) {
+        const members = collectOwnedMembers(currentOwnerId, name, ctx);
+        for (const def of members) {
+            if (!acceptedKinds.has(def.type))
+                continue;
+            recordTypeBindingHit(perCandidate, def, mroDepth, ownerDefId);
+        }
+        mroDepth++;
+    }
+}
+function resolveReceiverOwner(startScope, params, ctx) {
+    // Explicit receiver: consult the callsite scope's typeBindings for the
+    // named receiver; the attached TypeRef identifies the owner. Without a
+    // ready resolveTypeRef call (that module is separate), we do a direct
+    // lookup and trust the caller to have populated the binding.
+    if (params.explicitReceiver !== undefined) {
+        return lookupReceiverType(startScope, params.explicitReceiver.name, ctx);
+    }
+    // Implicit `self` / `this` — the scope's typeBindings should carry it.
+    for (const implicitName of IMPLICIT_RECEIVERS) {
+        const owner = lookupReceiverType(startScope, implicitName, ctx);
+        if (owner !== undefined)
+            return owner;
+    }
+    return undefined;
+}
+/**
+ * Names that denote the enclosing instance rather than an arbitrary object.
+ *
+ * Two consumers, and both want the same set: `resolveReceiverOwner` above
+ * tries them when no explicit receiver is present, and the Step-1 skip in
+ * `lookupCore` exempts them because for a SELF receiver the members and the
+ * lexical chain legitimately overlap — a class body is itself a scope that
+ * binds its members — whereas for a named receiver they never do.
+ *
+ * `$this` is matched because the receiver name arrives as the reference node's
+ * RAW SOURCE TEXT (`extractExplicitReceiver` returns `cap.text` verbatim), so
+ * PHP's `$this->x` presents as `"$this"`, sigil included. Listing the spelling
+ * keeps this a data table rather than a language switch — this module resolves
+ * language behaviour through `providers.*` and `params` only (see the header)
+ * — and it follows the ingestion-side twin, `THIS_RECEIVERS` in
+ * `cgraph/src/core/ingestion/type-env.ts`, which has always listed the
+ * sigil'd spelling rather than stripping it. Stripping would carry the same
+ * false-positive surface anyway (a JS variable literally named `$this`).
+ *
+ * That twin also lists `Me`, deliberately NOT mirrored here: no entry in
+ * `SupportedLanguages` uses it, so it can only ever exempt a variable that
+ * happens to be called `Me`. The two lists are otherwise the same set, and
+ * that equality — plus the `Me` exemption in both directions — is now ENFORCED
+ * by `cgraph/test/unit/receiver-twin-list-drift.test.ts`. Editing either list
+ * without the other fails there.
+ */
+const IMPLICIT_RECEIVERS = Object.freeze(['self', 'this', '$this']);
+function lookupReceiverType(startScope, receiverName, ctx) {
+    let currentId = startScope;
+    const visited = new Set();
+    while (currentId !== null) {
+        if (visited.has(currentId))
+            return undefined;
+        visited.add(currentId);
+        const scope = ctx.scopes.getScope(currentId);
+        if (scope === undefined)
+            return undefined;
+        const typeRef = scope.typeBindings.get(receiverName);
+        if (typeRef !== undefined) {
+            // rawName must resolve to a def via qualifiedNames; if it doesn't, we
+            // can't claim the receiver type. No fallback — that's what
+            // `resolveTypeRef` would do, but we keep this path lean and let
+            // callers pre-resolve if they want the richer semantics.
+            const candidateIds = ctx.qualifiedNames.get(typeRef.rawName);
+            if (candidateIds.length === 1)
+                return candidateIds[0];
+            // Ambiguous (≥ 2) or missing (0) — caller must pre-resolve via
+            // `resolveTypeRef` (#916) if they want the richer semantics. We
+            // intentionally do NOT re-implement a simple-name fallback here.
+            return undefined;
+        }
+        // The scope binds this receiver itself but carries no type for it — a
+        // JS/TS ordinary `function` whose `this` is bound at call time, not the
+        // enclosing instance (#2701). Stop rather than borrowing an enclosing
+        // scope's binding; see `Scope.ownsReceivers`. Mirrors the same gate in
+        // the ingestion-side twin of this walk, `findReceiverTypeBinding`.
+        if (scope.ownsReceivers?.has(receiverName) === true)
+            return undefined;
+        currentId = scope.parent;
+    }
+    return undefined;
+}
+function collectOwnedMembers(ownerDefId, memberName, ctx) {
+    return ctx.ownedMembersByOwner(ownerDefId, memberName);
+}
+function recordTypeBindingHit(perCandidate, def, mroDepth, receiverOwner) {
+    const state = ensureCandidate(perCandidate, def);
+    const existingMroDepth = state.signals.typeBindingMroDepth;
+    const firstHit = existingMroDepth === undefined;
+    // Only replace if this hit is shallower (smaller MRO depth). The local
+    // const lets TS narrow to `number` in the `else` branch so no `!`
+    // assertion is needed.
+    if (firstHit || mroDepth < existingMroDepth) {
+        state.signals.typeBindingMroDepth = mroDepth;
+        state.tieBreakKey.mroDepth = mroDepth;
+    }
+    if (def.ownerId === receiverOwner) {
+        state.signals.ownerMatch = true;
+    }
+    // Pure type-binding candidates (no lexical hit) would otherwise keep the
+    // `ensureCandidate` default `tieBreakKey.origin === 'local'`, making the
+    // Appendix B cascade lump them with local-origin candidates. Demote them
+    // to `'import'` — the strongest non-local origin — only when no earlier
+    // phase set an origin for this candidate. Lexical hits from Step 1 set
+    // `signals.origin` before Step 2 runs, so the guard skips them; Step 3
+    // (`seedFromOwnerScopedContributor`) runs AFTER Step 2 and unconditionally
+    // overrides `tieBreakKey.origin` back to `'local'` for direct-owner
+    // members, so any same-def overlap still ends up ranked correctly.
+    if (firstHit && state.signals.origin === undefined) {
+        state.tieBreakKey.origin = 'import';
+    }
+}
+// ─── Step 3 implementation ─────────────────────────────────────────────────
+function seedFromOwnerScopedContributor(name, contributor, acceptedKinds, perCandidate) {
+    for (const def of contributor.byName(name)) {
+        if (!acceptedKinds.has(def.type))
+            continue;
+        const state = ensureCandidate(perCandidate, def);
+        // Treat the contributor's direct membership as `origin: 'local'` —
+        // strongest visibility, no scope-chain penalty.
+        state.signals.origin = 'local';
+        state.signals.scopeChainDepth = 0;
+        state.signals.ownerMatch = def.ownerId === contributor.ownerDefId;
+        state.tieBreakKey.origin = 'local';
+    }
+}
+// ─── Step 5 implementation ─────────────────────────────────────────────────
+function applyArityFilter(callsite, perCandidate, ctx) {
+    const arityFn = ctx.providers.arityCompatibility;
+    if (arityFn === undefined) {
+        // No provider → record 'unknown' for every candidate; keeps signal
+        // shape uniform for composeEvidence.
+        for (const state of perCandidate.values()) {
+            state.signals.arityVerdict = 'unknown';
+        }
+        return;
+    }
+    let anyCompatible = false;
+    let anyUnknown = false;
+    for (const state of perCandidate.values()) {
+        const verdict = arityFn(callsite, state.def);
+        state.signals.arityVerdict = verdict;
+        if (verdict === 'compatible')
+            anyCompatible = true;
+        else if (verdict === 'unknown')
+            anyUnknown = true;
+    }
+    // When ALL candidates are 'incompatible' (none compatible, none unknown),
+    // the call is genuinely arity-broken — drop every candidate so the
+    // registry returns no resolution. This matches the PHP variadic case
+    // f(int $req, ...$rest) called with zero args: every candidate definitively
+    // rejects, and emitting an edge to a definitively-rejected callable is
+    // a false positive. When some candidates are 'unknown' (missing metadata),
+    // keep the set so downstream evidence can break the tie — that's the
+    // original safety-fallback behavior.
+    if (!anyCompatible) {
+        if (!anyUnknown) {
+            for (const defId of perCandidate.keys()) {
+                perCandidate.delete(defId);
+            }
+        }
+        return;
+    }
+    // Filter: when at least one compatible candidate exists, drop incompatibles.
+    for (const [defId, state] of perCandidate) {
+        if (state.signals.arityVerdict === 'incompatible') {
+            perCandidate.delete(defId);
+        }
+    }
+}
+// ─── Step 7 implementation ─────────────────────────────────────────────────
+function rankCandidates(perCandidate) {
+    const resolutions = [];
+    const tieKeys = new Map();
+    for (const state of perCandidate.values()) {
+        const evidence = (0, evidence_js_1.composeEvidence)(state.signals);
+        const confidence = (0, evidence_js_1.confidenceFromEvidence)(evidence);
+        resolutions.push({ def: state.def, confidence, evidence });
+        tieKeys.set(state.def.nodeId, { ...state.tieBreakKey });
+    }
+    resolutions.sort((a, b) => (0, tie_breaks_js_1.compareByConfidenceWithTiebreaks)(a, b, tieKeys));
+    return Object.freeze(resolutions);
+}
+// ─── Constants ──────────────────────────────────────────────────────────────
+const EMPTY = Object.freeze([]);

package/dist/core/code/shared/scope-resolution/registries/lookup-qualified.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * `lookupQualified` — qualified-name fast path (RFC §4.5; Ring 2 SHARED #917).
+ *
+ * Consults `QualifiedNameIndex` directly, filters by `acceptedKinds`, and
+ * returns `Resolution[]` with `origin: 'global-qualified'` evidence. Used by:
+ *
+ *   - `resolveTypeRef` dotted fallback (#916)
+ *   - `Registry.lookup` Step 6 when no lexical candidate survived
+ *   - Explicit dotted identifiers in Cypher / MCP tools where the caller
+ *     knows the target's canonical qualified name
+ *
+ * **Strict + deterministic.** No receiver-type resolution, no scope walk.
+ * Every surviving candidate gets the same base confidence (from
+ * `EvidenceWeights.globalQualified`), then the tie-break cascade
+ * disambiguates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupQualified = lookupQualified;
+const evidence_js_1 = require("./evidence.js");
+const tie_breaks_js_1 = require("./tie-breaks.js");
+/**
+ * Look up a canonical qualified name (e.g., `app.models.User`) across all
+ * defs, filtered by `acceptedKinds`. Returns an empty array when the name
+ * is not indexed or no candidate matches the kind filter.
+ *
+ * Callers consume `[0]` for the strict single-return answer; the remainder
+ * carries alternate candidates (partial classes, overloads, accidental
+ * cross-kind hits) ordered by the tie-break cascade.
+ */
+function lookupQualified(qualifiedName, params, ctx) {
+    const defIds = ctx.qualifiedNames.get(qualifiedName);
+    if (defIds.length === 0)
+        return EMPTY;
+    const acceptedKinds = new Set(params.acceptedKinds);
+    const resolutions = [];
+    const tieKeys = new Map();
+    for (const defId of defIds) {
+        const def = ctx.defs.get(defId);
+        if (def === undefined)
+            continue;
+        if (!acceptedKinds.has(def.type))
+            continue;
+        const evidence = (0, evidence_js_1.composeEvidence)({ origin: 'global-qualified', kindMatch: true });
+        const confidence = (0, evidence_js_1.confidenceFromEvidence)(evidence);
+        resolutions.push({ def, confidence, evidence });
+        tieKeys.set(def.nodeId, {
+            scopeDepth: 0,
+            mroDepth: 0,
+            origin: 'global-qualified',
+        });
+    }
+    if (resolutions.length === 0)
+        return EMPTY;
+    resolutions.sort((a, b) => (0, tie_breaks_js_1.compareByConfidenceWithTiebreaks)(a, b, tieKeys));
+    return Object.freeze(resolutions);
+}
+const EMPTY = Object.freeze([]);

package/dist/core/code/shared/scope-resolution/registries/macro-registry.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * `MacroRegistry` — scope-aware lookup for macro definitions
+ * (`macro_rules!` in Rust; `#define` in C/C++) referenced from a macro
+ * invocation site.
+ *
+ * Thin wrapper over `lookupCore`, specialized for the macro namespace:
+ *
+ *   - `acceptedKinds` = `MACRO_KINDS` (`['Macro']` only). Crucially this
+ *     does NOT include `Function`/`Method`, so a `log!(…)` invocation can
+ *     never resolve to a same-named free function `fn log` — macros and
+ *     functions are disjoint namespaces (the false-`CALLS`-edge class the
+ *     #1934 review flagged).
+ *   - `useReceiverTypeBinding` is **false** — a macro invocation has no
+ *     receiver; resolution is name-through-the-lexical-chain + the global
+ *     qualified fallback, exactly like `ClassRegistry`.
+ *   - Arity is not applied — macros are variadic by nature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMacroRegistry = buildMacroRegistry;
+const lookup_core_js_1 = require("./lookup-core.js");
+const context_js_1 = require("./context.js");
+function buildMacroRegistry(ctx) {
+    const params = {
+        acceptedKinds: context_js_1.MACRO_KINDS,
+        useReceiverTypeBinding: false,
+        ownerScopedContributor: null,
+    };
+    return {
+        lookup(name, scope) {
+            return (0, lookup_core_js_1.lookupCore)(name, scope, params, ctx);
+        },
+    };
+}