@codragraph/cli 1.6.2

package/dist/_shared/scope-resolution/registries/lookup-qualified.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `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.
+ */
+import type { NodeLabel } from '../../graph/types.js';
+import type { Resolution } from '../types.js';
+import type { RegistryContext } from './context.js';
+export interface LookupQualifiedParams {
+    readonly acceptedKinds: readonly NodeLabel[];
+}
+/**
+ * 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.
+ */
+export declare function lookupQualified(qualifiedName: string, params: LookupQualifiedParams, ctx: RegistryContext): readonly Resolution[];
+//# sourceMappingURL=lookup-qualified.d.ts.map

package/dist/_shared/scope-resolution/registries/lookup-qualified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-qualified.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/registries/lookup-qualified.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,eAAe,GACnB,SAAS,UAAU,EAAE,CA4BvB"}

package/dist/_shared/scope-resolution/registries/lookup-qualified.js

@@ -0,0 +1,56 @@
+/**
+ * `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.
+ */
+import { composeEvidence, confidenceFromEvidence } from './evidence.js';
+import { compareByConfidenceWithTiebreaks } from './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.
+ */
+export 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 = composeEvidence({ origin: 'global-qualified', kindMatch: true });
+        const confidence = 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) => compareByConfidenceWithTiebreaks(a, b, tieKeys));
+    return Object.freeze(resolutions);
+}
+const EMPTY = Object.freeze([]);
+//# sourceMappingURL=lookup-qualified.js.map

package/dist/_shared/scope-resolution/registries/lookup-qualified.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-qualified.js","sourceRoot":"","sources":["../../../src/scope-resolution/registries/lookup-qualified.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,gCAAgC,EAAoB,MAAM,iBAAiB,CAAC;AAOrF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,aAAqB,EACrB,MAA6B,EAC7B,GAAoB;IAEpB,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEtC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAY,MAAM,CAAC,aAAa,CAAC,CAAC;IAE/D,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAE3C,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,MAAM,UAAU,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QACpD,WAAW,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE;YACtB,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,kBAAkB;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3C,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,KAAK,GAA0B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/dist/_shared/scope-resolution/registries/method-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `MethodRegistry` — scope-aware lookup for method / function / constructor
+ * dispatch (RFC §4.4; Ring 2 SHARED #917).
+ *
+ * Thin wrapper over `lookupCore`, specialized for callable kinds:
+ *
+ *   - `acceptedKinds` = Method / Function / Constructor.
+ *   - `useReceiverTypeBinding` is **true** — the type-binding + MRO walk
+ *     (Step 2) is the primary evidence path for receiver-dispatched calls.
+ *   - `callsite.arity` flows through to `provider.arityCompatibility`
+ *     when provided. When the provider is absent, arity evidence is
+ *     `unknown` (neutral signal).
+ */
+import type { Callsite, Resolution, ScopeId } from '../types.js';
+import type { OwnerScopedContributor, RegistryContext } from './context.js';
+/**
+ * Extra per-call parameters that vary across call sites but NOT across
+ * registries. Kept as a separate shape so `MethodRegistry.lookup` stays
+ * concise while still exposing the explicit-receiver + owner-contributor +
+ * arity knobs the RFC algorithm needs.
+ */
+export interface MethodLookupOptions {
+    /** Call-site arity for `provider.arityCompatibility`. */
+    readonly callsite?: Callsite;
+    /** Explicit receiver (e.g., `user` in `user.save()`). See §4.1. */
+    readonly explicitReceiver?: {
+        readonly name: string;
+    };
+    /** Optional per-owner contributor (Step 3). */
+    readonly ownerScopedContributor?: OwnerScopedContributor;
+}
+export interface MethodRegistry {
+    lookup(name: string, scope: ScopeId, options?: MethodLookupOptions): readonly Resolution[];
+}
+export declare function buildMethodRegistry(ctx: RegistryContext): MethodRegistry;
+//# sourceMappingURL=method-registry.d.ts.map

package/dist/_shared/scope-resolution/registries/method-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-registry.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/registries/method-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG5E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CAC1D;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,UAAU,EAAE,CAAC;CAC5F;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,cAAc,CAexE"}

package/dist/_shared/scope-resolution/registries/method-registry.js

@@ -0,0 +1,32 @@
+/**
+ * `MethodRegistry` — scope-aware lookup for method / function / constructor
+ * dispatch (RFC §4.4; Ring 2 SHARED #917).
+ *
+ * Thin wrapper over `lookupCore`, specialized for callable kinds:
+ *
+ *   - `acceptedKinds` = Method / Function / Constructor.
+ *   - `useReceiverTypeBinding` is **true** — the type-binding + MRO walk
+ *     (Step 2) is the primary evidence path for receiver-dispatched calls.
+ *   - `callsite.arity` flows through to `provider.arityCompatibility`
+ *     when provided. When the provider is absent, arity evidence is
+ *     `unknown` (neutral signal).
+ */
+import { lookupCore } from './lookup-core.js';
+import { METHOD_KINDS } from './context.js';
+export function buildMethodRegistry(ctx) {
+    return {
+        lookup(name, scope, options = {}) {
+            const params = {
+                acceptedKinds: METHOD_KINDS,
+                useReceiverTypeBinding: true,
+                ownerScopedContributor: options.ownerScopedContributor ?? null,
+                ...(options.callsite !== undefined ? { callsite: options.callsite } : {}),
+                ...(options.explicitReceiver !== undefined
+                    ? { explicitReceiver: options.explicitReceiver }
+                    : {}),
+            };
+            return lookupCore(name, scope, params, ctx);
+        },
+    };
+}
+//# sourceMappingURL=method-registry.js.map

package/dist/_shared/scope-resolution/registries/method-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../../src/scope-resolution/registries/method-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAqB5C,MAAM,UAAU,mBAAmB,CAAC,GAAoB;IACtD,OAAO;QACL,MAAM,CAAC,IAAY,EAAE,KAAc,EAAE,UAA+B,EAAE;YACpE,MAAM,MAAM,GAAqB;gBAC/B,aAAa,EAAE,YAAY;gBAC3B,sBAAsB,EAAE,IAAI;gBAC5B,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,IAAI,IAAI;gBAC9D,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzE,GAAG,CAAC,OAAO,CAAC,gBAAgB,KAAK,SAAS;oBACxC,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE;oBAChD,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;YACF,OAAO,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/_shared/scope-resolution/registries/tie-breaks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `compareByConfidenceWithTiebreaks` — the RFC §4.2 Step 7 total order
+ * over `Resolution` candidates (Ring 2 SHARED #917).
+ *
+ * Primary key is confidence (DESC). Remaining ties within `CONFIDENCE_EPSILON`
+ * fall through a deterministic cascade so the same inputs always produce
+ * the same winner, independent of insertion order.
+ *
+ * Tie-break cascade (per RFC Appendix B):
+ *
+ *   1. confidence DESC                       (primary)
+ *   2. scope depth ASC                       (nearer lexical scope wins)
+ *   3. MRO depth ASC                         (nearer class in hierarchy wins)
+ *   4. `ORIGIN_PRIORITY` ASC                 (local > import > … > global-name)
+ *   5. DefId.localeCompare                   (final deterministic tiebreaker)
+ *
+ * The per-candidate inputs needed beyond `Resolution.confidence` —
+ * `scopeDepth`, `mroDepth`, `origin` — are supplied via a sidecar
+ * `TieBreakKey` so the comparator stays pure and `Resolution` itself
+ * doesn't need to carry book-keeping fields.
+ */
+import { type OriginForTieBreak } from '../origin-priority.js';
+import type { Resolution } from '../types.js';
+export declare const CONFIDENCE_EPSILON = 0.001;
+/** Side-information per candidate used for secondary tie-breaks. */
+export interface TieBreakKey {
+    readonly scopeDepth: number;
+    readonly mroDepth: number;
+    readonly origin: OriginForTieBreak;
+}
+/**
+ * Pure comparator suitable for `Array.prototype.sort`. Return value follows
+ * the JavaScript convention: negative → `a` wins, positive → `b` wins.
+ *
+ * **Important:** `keys` is keyed by `Resolution.def.nodeId`, not by array
+ * index — stable across reorderings. Missing keys fall back to neutral
+ * values (`scopeDepth: 0`, `mroDepth: 0`, `origin: 'local'`), which means
+ * the tie-break degrades gracefully to defId-lexicographic ordering when
+ * side-info is unavailable. That keeps the total order deterministic
+ * even on malformed inputs.
+ */
+export declare function compareByConfidenceWithTiebreaks(a: Resolution, b: Resolution, keys: ReadonlyMap<string, TieBreakKey>): number;
+//# sourceMappingURL=tie-breaks.d.ts.map

package/dist/_shared/scope-resolution/registries/tie-breaks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tie-breaks.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/registries/tie-breaks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GACrC,MAAM,CAoBR"}

package/dist/_shared/scope-resolution/registries/tie-breaks.js

@@ -0,0 +1,60 @@
+/**
+ * `compareByConfidenceWithTiebreaks` — the RFC §4.2 Step 7 total order
+ * over `Resolution` candidates (Ring 2 SHARED #917).
+ *
+ * Primary key is confidence (DESC). Remaining ties within `CONFIDENCE_EPSILON`
+ * fall through a deterministic cascade so the same inputs always produce
+ * the same winner, independent of insertion order.
+ *
+ * Tie-break cascade (per RFC Appendix B):
+ *
+ *   1. confidence DESC                       (primary)
+ *   2. scope depth ASC                       (nearer lexical scope wins)
+ *   3. MRO depth ASC                         (nearer class in hierarchy wins)
+ *   4. `ORIGIN_PRIORITY` ASC                 (local > import > … > global-name)
+ *   5. DefId.localeCompare                   (final deterministic tiebreaker)
+ *
+ * The per-candidate inputs needed beyond `Resolution.confidence` —
+ * `scopeDepth`, `mroDepth`, `origin` — are supplied via a sidecar
+ * `TieBreakKey` so the comparator stays pure and `Resolution` itself
+ * doesn't need to carry book-keeping fields.
+ */
+import { ORIGIN_PRIORITY } from '../origin-priority.js';
+export const CONFIDENCE_EPSILON = 0.001;
+/**
+ * Pure comparator suitable for `Array.prototype.sort`. Return value follows
+ * the JavaScript convention: negative → `a` wins, positive → `b` wins.
+ *
+ * **Important:** `keys` is keyed by `Resolution.def.nodeId`, not by array
+ * index — stable across reorderings. Missing keys fall back to neutral
+ * values (`scopeDepth: 0`, `mroDepth: 0`, `origin: 'local'`), which means
+ * the tie-break degrades gracefully to defId-lexicographic ordering when
+ * side-info is unavailable. That keeps the total order deterministic
+ * even on malformed inputs.
+ */
+export function compareByConfidenceWithTiebreaks(a, b, keys) {
+    // Primary: confidence DESC, treating values within epsilon as equal.
+    const delta = b.confidence - a.confidence;
+    if (Math.abs(delta) >= CONFIDENCE_EPSILON)
+        return delta < 0 ? -1 : 1;
+    const ka = keys.get(a.def.nodeId) ?? DEFAULT_KEY;
+    const kb = keys.get(b.def.nodeId) ?? DEFAULT_KEY;
+    // Secondary: scope depth ASC.
+    if (ka.scopeDepth !== kb.scopeDepth)
+        return ka.scopeDepth - kb.scopeDepth;
+    // Tertiary: MRO depth ASC.
+    if (ka.mroDepth !== kb.mroDepth)
+        return ka.mroDepth - kb.mroDepth;
+    // Quaternary: ORIGIN_PRIORITY ASC.
+    const po = ORIGIN_PRIORITY[ka.origin] - ORIGIN_PRIORITY[kb.origin];
+    if (po !== 0)
+        return po;
+    // Final: DefId lexicographic, locale-aware for deterministic cross-platform output.
+    return a.def.nodeId.localeCompare(b.def.nodeId);
+}
+const DEFAULT_KEY = Object.freeze({
+    scopeDepth: 0,
+    mroDepth: 0,
+    origin: 'local',
+});
+//# sourceMappingURL=tie-breaks.js.map

package/dist/_shared/scope-resolution/registries/tie-breaks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tie-breaks.js","sourceRoot":"","sources":["../../../src/scope-resolution/registries/tie-breaks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,eAAe,EAA0B,MAAM,uBAAuB,CAAC;AAGhF,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AASxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAC9C,CAAa,EACb,CAAa,EACb,IAAsC;IAEtC,qEAAqE;IACrE,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB;QAAE,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC;IACjD,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC;IAEjD,8BAA8B;IAC9B,IAAI,EAAE,CAAC,UAAU,KAAK,EAAE,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC;IAE1E,2BAA2B;IAC3B,IAAI,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;IAElE,mCAAmC;IACnC,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IACnE,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExB,oFAAoF;IACpF,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,WAAW,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC7C,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,OAAO;CAChB,CAAC,CAAC"}

package/dist/_shared/scope-resolution/resolve-type-ref.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `resolveTypeRef` — strict single-return resolver for `TypeRef`s
+ * (RFC §4.6; Ring 2 SHARED #916).
+ *
+ * Narrower contract than `Registry.lookup`: no name-only global fallback, no
+ * confidence ranking, no arity check. Used by `Registry.lookup` Step 2 (type-
+ * binding propagation) and by any caller that wants the single best type-
+ * target for an annotation without paying for the full evidence pipeline.
+ *
+ * **Algorithm (strict).** Walk the scope chain from `ref.declaredAtScope`:
+ *
+ *   1. At each scope, inspect `bindings.get(ref.rawName)`:
+ *      - If one of the bindings is a **type-kind** def with a **strict origin**
+ *        (`'local' | 'import' | 'namespace' | 'reexport'`), return it.
+ *      - If any binding for this name exists at this scope but none qualifies
+ *        (e.g., a local variable named `User` shadows an outer import of class
+ *        `User`), return `null`. The nearer binding shadows; we do NOT fall
+ *        through to the global qualified-name index.
+ *      - Otherwise continue to the parent scope.
+ *   2. If the raw name is a dotted path (e.g., `'models.User'`) and the scope
+ *      walk produced no match, consult `QualifiedNameIndex.byQualifiedName`.
+ *      Only accept **exactly one** type-kind hit — anything ambiguous returns
+ *      `null` rather than a guess.
+ *   3. Return `null`.
+ *
+ * **What `'strict' origins' means.** `'wildcard'` is intentionally excluded.
+ * A wildcard-expanded name (`from x import *`) is too loose to use as an
+ * anchor for type resolution — it gives no signal about whether the name was
+ * actually imported. `Registry.lookup` may accept wildcard bindings at its
+ * own discretion (with lower evidence weight); `resolveTypeRef` does not.
+ *
+ * **What 'type-kind' means.** The subset of `NodeLabel` that a type annotation
+ * may legitimately reference: class-like, interface-like, enum-like, and
+ * alias-like kinds. See `TYPE_KINDS` below.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { ScopeLookup, TypeRef } from './types.js';
+import type { DefIndex } from './def-index.js';
+import type { QualifiedNameIndex } from './qualified-name-index.js';
+/**
+ * All inputs `resolveTypeRef` needs from the semantic model. Bundled into a
+ * context object so the call site stays short and the interface is stable as
+ * additional indexes get threaded through in later rings.
+ */
+export interface ResolveTypeRefContext {
+    readonly scopes: ScopeLookup;
+    readonly defIndex: DefIndex;
+    readonly qualifiedNameIndex: QualifiedNameIndex;
+}
+export declare function resolveTypeRef(ref: TypeRef, ctx: ResolveTypeRefContext): SymbolDefinition | null;
+//# sourceMappingURL=resolve-type-ref.d.ts.map

package/dist/_shared/scope-resolution/resolve-type-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-type-ref.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/resolve-type-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAuB,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIpE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;CACjD;AA4CD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,IAAI,CAgDhG"}

package/dist/_shared/scope-resolution/resolve-type-ref.js

@@ -0,0 +1,126 @@
+/**
+ * `resolveTypeRef` — strict single-return resolver for `TypeRef`s
+ * (RFC §4.6; Ring 2 SHARED #916).
+ *
+ * Narrower contract than `Registry.lookup`: no name-only global fallback, no
+ * confidence ranking, no arity check. Used by `Registry.lookup` Step 2 (type-
+ * binding propagation) and by any caller that wants the single best type-
+ * target for an annotation without paying for the full evidence pipeline.
+ *
+ * **Algorithm (strict).** Walk the scope chain from `ref.declaredAtScope`:
+ *
+ *   1. At each scope, inspect `bindings.get(ref.rawName)`:
+ *      - If one of the bindings is a **type-kind** def with a **strict origin**
+ *        (`'local' | 'import' | 'namespace' | 'reexport'`), return it.
+ *      - If any binding for this name exists at this scope but none qualifies
+ *        (e.g., a local variable named `User` shadows an outer import of class
+ *        `User`), return `null`. The nearer binding shadows; we do NOT fall
+ *        through to the global qualified-name index.
+ *      - Otherwise continue to the parent scope.
+ *   2. If the raw name is a dotted path (e.g., `'models.User'`) and the scope
+ *      walk produced no match, consult `QualifiedNameIndex.byQualifiedName`.
+ *      Only accept **exactly one** type-kind hit — anything ambiguous returns
+ *      `null` rather than a guess.
+ *   3. Return `null`.
+ *
+ * **What `'strict' origins' means.** `'wildcard'` is intentionally excluded.
+ * A wildcard-expanded name (`from x import *`) is too loose to use as an
+ * anchor for type resolution — it gives no signal about whether the name was
+ * actually imported. `Registry.lookup` may accept wildcard bindings at its
+ * own discretion (with lower evidence weight); `resolveTypeRef` does not.
+ *
+ * **What 'type-kind' means.** The subset of `NodeLabel` that a type annotation
+ * may legitimately reference: class-like, interface-like, enum-like, and
+ * alias-like kinds. See `TYPE_KINDS` below.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+// ─── Strict policy constants ────────────────────────────────────────────────
+/** `'wildcard'` is deliberately absent. See file header. */
+const STRICT_ORIGINS = new Set([
+    'local',
+    'import',
+    'namespace',
+    'reexport',
+]);
+/**
+ * `NodeLabel` values that may appear on the RHS of a type annotation.
+ *
+ * Includes the usual class-like and interface-like kinds plus the alias-like
+ * ones (`TypeAlias`, `Typedef`). `Namespace` is excluded — it is a scope
+ * container, not a value type. `Function` / `Method` / `Variable` are
+ * excluded by design: a `rawName` bound to them at a strict origin is a
+ * *shadowing* binding, which the algorithm short-circuits to `null`.
+ *
+ * `'Type'` (the generic `NodeLabel` value) is also excluded — verified
+ * against `@codragraph/cli/src/core/ingestion/` at the time of writing, no
+ * production extractor emits `type: 'Type'` for annotation-relevant
+ * symbols. Should a future extractor start emitting it, add `'Type'`
+ * here and add a test asserting the new path.
+ */
+const TYPE_KINDS = new Set([
+    'Class',
+    'Interface',
+    'Enum',
+    'Struct',
+    'Union',
+    'Trait',
+    'TypeAlias',
+    'Typedef',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Template',
+]);
+// ─── Main entry point ──────────────────────────────────────────────────────
+export function resolveTypeRef(ref, ctx) {
+    // Phase 1: scope-chain walk anchored at the declaration site.
+    let currentId = ref.declaredAtScope;
+    const visited = new Set();
+    while (currentId !== null) {
+        // Cycle guard — a well-formed scope tree never loops, but a bug in the
+        // construction path should fail fast here rather than hanging.
+        if (visited.has(currentId))
+            return null;
+        visited.add(currentId);
+        const scope = ctx.scopes.getScope(currentId);
+        if (scope === undefined)
+            return null; // broken chain = unresolvable
+        const bindings = scope.bindings.get(ref.rawName);
+        if (bindings !== undefined && bindings.length > 0) {
+            // At least one binding exists at this scope → it is the shadowing site.
+            // Either one of them qualifies, or the name is shadowed by a non-type.
+            for (const binding of bindings) {
+                if (!STRICT_ORIGINS.has(binding.origin))
+                    continue;
+                if (TYPE_KINDS.has(binding.def.type)) {
+                    return binding.def;
+                }
+            }
+            // Shadowed by a non-type / non-strict-origin binding. Fail fast — no
+            // global fallback, no walk to the parent.
+            return null;
+        }
+        currentId = scope.parent;
+    }
+    // Phase 2: dotted fallback via `QualifiedNameIndex`. Only accept a unique
+    // type-kind hit; anything ambiguous returns null (strict: no guesses).
+    if (ref.rawName.includes('.')) {
+        const candidates = ctx.qualifiedNameIndex.get(ref.rawName);
+        let onlyTypeDef = null;
+        for (const defId of candidates) {
+            const def = ctx.defIndex.get(defId);
+            if (def === undefined)
+                continue;
+            if (!TYPE_KINDS.has(def.type))
+                continue;
+            if (onlyTypeDef !== null)
+                return null; // ambiguous
+            onlyTypeDef = def;
+        }
+        if (onlyTypeDef !== null)
+            return onlyTypeDef;
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-type-ref.js.map

package/dist/_shared/scope-resolution/resolve-type-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-type-ref.js","sourceRoot":"","sources":["../../src/scope-resolution/resolve-type-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAqBH,+EAA+E;AAE/E,4DAA4D;AAC5D,MAAM,cAAc,GAAsC,IAAI,GAAG,CAAuB;IACtF,OAAO;IACP,QAAQ;IACR,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,GAA2B,IAAI,GAAG,CAAY;IAC5D,OAAO;IACP,WAAW;IACX,MAAM;IACN,QAAQ;IACR,OAAO;IACP,OAAO;IACP,WAAW;IACX,SAAS;IACT,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,UAAU;CACX,CAAC,CAAC;AAEH,8EAA8E;AAE9E,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,GAA0B;IACrE,8DAA8D;IAC9D,IAAI,SAAS,GAAmB,GAAG,CAAC,eAAe,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAW,CAAC;IAEnC,OAAO,SAAS,KAAK,IAAI,EAAE,CAAC;QAC1B,uEAAuE;QACvE,+DAA+D;QAC/D,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEvB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,CAAC,8BAA8B;QAEpE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,wEAAwE;YACxE,uEAAuE;YACvE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,SAAS;gBAClD,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrC,OAAO,OAAO,CAAC,GAAG,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,qEAAqE;YACrE,0CAA0C;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,WAAW,GAA4B,IAAI,CAAC;QAChD,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS;YAChC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxC,IAAI,WAAW,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC,CAAC,YAAY;YACnD,WAAW,GAAG,GAAG,CAAC;QACpB,CAAC;QACD,IAAI,WAAW,KAAK,IAAI;YAAE,OAAO,WAAW,CAAC;IAC/C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/_shared/scope-resolution/scope-id.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+import type { Range } from './types.js';
+import type { ScopeId, ScopeKind } from './types.js';
+/** Inputs required to construct a canonical `ScopeId`. */
+export interface ScopeIdInput {
+    readonly filePath: string;
+    readonly range: Range;
+    readonly kind: ScopeKind;
+}
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export declare function makeScopeId(input: ScopeIdInput): ScopeId;
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export declare function clearScopeIdInternPool(): void;
+//# sourceMappingURL=scope-id.d.ts.map

package/dist/_shared/scope-resolution/scope-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/_shared/scope-resolution/scope-id.js

@@ -0,0 +1,46 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export function makeScopeId(input) {
+    const raw = `scope:${input.filePath}#${input.range.startLine}:${input.range.startCol}-${input.range.endLine}:${input.range.endCol}:${input.kind}`;
+    const existing = INTERN_POOL.get(raw);
+    if (existing !== undefined)
+        return existing;
+    INTERN_POOL.set(raw, raw);
+    return raw;
+}
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export function clearScopeIdInternPool() {
+    INTERN_POOL.clear();
+}
+/** Internal: shared intern pool (process-local). */
+const INTERN_POOL = new Map();
+//# sourceMappingURL=scope-id.js.map

package/dist/_shared/scope-resolution/scope-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.js","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,MAAM,GAAG,GAAG,SAAS,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;IAClJ,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,oDAAoD;AACpD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC"}

package/dist/_shared/scope-resolution/scope-tree.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
+ * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
+ *
+ * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
+ * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
+ * derived from each `Scope.parent` pointer, and validates the structural
+ * invariants a well-formed scope tree must satisfy.
+ *
+ * Invariants enforced at build time (throw on violation):
+ *
+ *   - Every non-`Module` scope has a non-null parent.
+ *   - Every parent pointer references a scope that was also supplied to
+ *     `buildScopeTree`.
+ *   - Parent range **strictly contains** child range.
+ *   - Sibling ranges under the same parent do not overlap.
+ *   - Parent and child live in the same `filePath`. (Cross-file parent
+ *     pointers would be a category error — a `File` scope is not the
+ *     parent of another file's scopes; imports do that job.)
+ *
+ * Satisfies the `ScopeLookup` contract (defined in `./types.js`), so
+ * `resolveTypeRef` (#916) and the scope-aware registries (#917) can take a
+ * `ScopeTree` directly without adapters.
+ *
+ * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
+ * `Object.freeze`d; miss lookups return a shared frozen empty array.
+ */
+import type { Scope, ScopeId, ScopeLookup } from './types.js';
+export interface ScopeTree extends ScopeLookup {
+    readonly size: number;
+    readonly byId: ReadonlyMap<ScopeId, Scope>;
+    getScope(id: ScopeId): Scope | undefined;
+    getParent(id: ScopeId): Scope | undefined;
+    /** Child `ScopeId`s of `id`, in input order. Frozen empty array on miss. */
+    getChildren(id: ScopeId): readonly ScopeId[];
+    /**
+     * Ancestor chain from the immediate parent up to (and including) the
+     * root module scope. Excludes the starting scope itself. Frozen empty
+     * array on miss / for a root scope.
+     */
+    getAncestors(id: ScopeId): readonly ScopeId[];
+    has(id: ScopeId): boolean;
+}
+/**
+ * Thrown by `buildScopeTree` when the input violates a structural
+ * invariant. Carries the offending ids + the invariant name so failed
+ * extraction pipelines can report actionable diagnostics.
+ */
+export declare class ScopeTreeInvariantError extends Error {
+    readonly invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id';
+    constructor(invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id', message: string);
+}
+/**
+ * Build an immutable `ScopeTree` from a flat list of `Scope` records.
+ *
+ * Throws `ScopeTreeInvariantError` on the first invariant violation; a
+ * malformed tree is a bug in the extraction pipeline, not a data case for
+ * consumers to handle, so fail-fast is the correct posture.
+ */
+export declare function buildScopeTree(scopes: readonly Scope[]): ScopeTree;
+//# sourceMappingURL=scope-tree.d.ts.map

package/dist/_shared/scope-resolution/scope-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAS,MAAM,YAAY,CAAC;AAIrE,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAE3C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC9C,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAID;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB;gBANf,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB,EACxB,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAiFlE"}