gitnexus 1.6.3-rc.2 → 1.6.3-rc.4

package/dist/_shared/index.d.ts

@@ -6,10 +6,14 @@ export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './langua
 export type { MroStrategy } from './mro-strategy.js';
 export type { PipelinePhase, PipelineProgress } from './pipeline.js';
 export type { SymbolDefinition } from './scope-resolution/symbol-definition.js';
-export type { ScopeId, DefId, ScopeKind, Range, Capture, BindingRef, ImportEdge, TypeRef, Scope, ResolutionEvidence, Resolution, Reference, ReferenceIndex, LookupParams, RegistryContributor, } from './scope-resolution/types.js';
+export type { ScopeId, DefId, ScopeKind, Range, Capture, CaptureMatch, BindingRef, ImportEdge, TypeRef, Scope, ResolutionEvidence, Resolution, Reference, ReferenceIndex, LookupParams, RegistryContributor, ParsedImport, ParsedTypeBinding, WorkspaceIndex, ScopeTree, Callsite, } from './scope-resolution/types.js';
 export { EvidenceWeights, typeBindingWeightAtDepth } from './scope-resolution/evidence-weights.js';
 export { ORIGIN_PRIORITY } from './scope-resolution/origin-priority.js';
 export type { OriginForTieBreak } from './scope-resolution/origin-priority.js';
 export { LanguageClassifications, isProductionLanguage, } from './scope-resolution/language-classification.js';
 export type { LanguageClassification } from './scope-resolution/language-classification.js';
+export { diffResolutions } from './scope-resolution/shadow/diff.js';
+export type { ShadowAgreement, ShadowCallsite, ShadowDiff, } from './scope-resolution/shadow/diff.js';
+export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';
+export type { LanguageParityRow, ShadowParityReport } from './scope-resolution/shadow/aggregate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/_shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EACV,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,UAAU,EACV,UAAU,EACV,OAAO,EACP,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EACV,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,QAAQ,GACT,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAG5F,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EACV,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/index.js

@@ -8,4 +8,7 @@ export { EvidenceWeights, typeBindingWeightAtDepth } from './scope-resolution/ev
 export { ORIGIN_PRIORITY } from './scope-resolution/origin-priority.js';
 // Language classification (RFC §6.1 Ring 3/4 governance)
 export { LanguageClassifications, isProductionLanguage, } from './scope-resolution/language-classification.js';
+// Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
+export { diffResolutions } from './scope-resolution/shadow/diff.js';
+export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';
 //# sourceMappingURL=index.js.map

package/dist/_shared/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AA2BjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/scope-resolution/shadow/aggregate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shadow-mode aggregation — per-language parity %, per-evidence-kind
+ * breakdown of divergences. Consumed by the parity dashboard (RING2-PKG-5).
+ *
+ * Pure functions; no I/O. The harness persists per-run JSON; the dashboard
+ * reads `.gitnexus/shadow-parity/latest.json` and renders.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #918.
+ */
+import type { SupportedLanguages } from '../../languages.js';
+import type { ResolutionEvidence } from '../types.js';
+import type { ShadowAgreement, ShadowDiff } from './diff.js';
+export interface LanguageParityRow {
+    readonly language: SupportedLanguages;
+    readonly totalCalls: number;
+    readonly bothAgree: number;
+    readonly onlyLegacy: number;
+    readonly onlyNew: number;
+    readonly bothDisagree: number;
+    readonly bothEmpty: number;
+    /**
+     * Fraction in [0, 1]. Numerator = `bothAgree`; denominator = "calls where
+     * at least one side resolved" = `totalCalls - bothEmpty`.
+     *
+     * When the denominator is 0 (all calls for this language were
+     * `both-empty`), returns 0. Callers rendering the dashboard should treat
+     * a 0 parity alongside `totalCalls === bothEmpty` as "no signal" rather
+     * than "total disagreement".
+     */
+    readonly parity: number;
+    /**
+     * Divergence signals broken down by `ResolutionEvidence.kind`. Sourced
+     * from `ShadowDiff.evidenceDelta` on non-agreeing rows only — `both-agree`
+     * and `both-empty` do not contribute.
+     */
+    readonly evidenceBreakdown: ReadonlyMap<ResolutionEvidence['kind'], number>;
+}
+export interface ShadowParityReport {
+    readonly generatedAt: string;
+    readonly perLanguage: readonly LanguageParityRow[];
+    readonly overall: Omit<LanguageParityRow, 'language' | 'evidenceBreakdown'>;
+}
+/**
+ * Aggregate a stream of `ShadowDiff` records into a `ShadowParityReport`,
+ * bucketed by language. Pure function.
+ *
+ * - `perLanguage` rows are sorted alphabetically by `SupportedLanguages`
+ *   value for stable JSON output (the dashboard reads
+ *   `.gitnexus/shadow-parity/latest.json` and diffing snapshots is useful).
+ * - `overall` is the column-wise sum across languages.
+ * - `generatedAt` is injected via the `now` parameter so tests stay
+ *   deterministic; production callers let it default to `new Date()`.
+ */
+export declare function aggregateDiffs(diffs: readonly {
+    readonly language: SupportedLanguages;
+    readonly diff: ShadowDiff;
+}[], now?: Date): ShadowParityReport;
+export type { ShadowAgreement, ShadowDiff };
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/_shared/scope-resolution/shadow/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/shadow/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAI7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,mBAAmB,CAAC,CAAC;CAC7E;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,EACtF,GAAG,GAAE,IAAiB,GACrB,kBAAkB,CAuBpB;AAiGD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC"}

package/dist/_shared/scope-resolution/shadow/aggregate.js

@@ -0,0 +1,117 @@
+/**
+ * Shadow-mode aggregation — per-language parity %, per-evidence-kind
+ * breakdown of divergences. Consumed by the parity dashboard (RING2-PKG-5).
+ *
+ * Pure functions; no I/O. The harness persists per-run JSON; the dashboard
+ * reads `.gitnexus/shadow-parity/latest.json` and renders.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #918.
+ */
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Aggregate a stream of `ShadowDiff` records into a `ShadowParityReport`,
+ * bucketed by language. Pure function.
+ *
+ * - `perLanguage` rows are sorted alphabetically by `SupportedLanguages`
+ *   value for stable JSON output (the dashboard reads
+ *   `.gitnexus/shadow-parity/latest.json` and diffing snapshots is useful).
+ * - `overall` is the column-wise sum across languages.
+ * - `generatedAt` is injected via the `now` parameter so tests stay
+ *   deterministic; production callers let it default to `new Date()`.
+ */
+export function aggregateDiffs(diffs, now = new Date()) {
+    const perLanguageMap = new Map();
+    for (const { language, diff } of diffs) {
+        let counts = perLanguageMap.get(language);
+        if (!counts) {
+            counts = makeEmptyCounts();
+            perLanguageMap.set(language, counts);
+        }
+        tallyDiff(counts, diff);
+    }
+    const perLanguage = Array.from(perLanguageMap.entries())
+        .map(([language, counts]) => buildRow(language, counts))
+        .sort((a, b) => a.language.localeCompare(b.language));
+    const overall = buildOverallRow(perLanguage);
+    return {
+        generatedAt: now.toISOString(),
+        perLanguage,
+        overall,
+    };
+}
+function makeEmptyCounts() {
+    return {
+        totalCalls: 0,
+        bothAgree: 0,
+        onlyLegacy: 0,
+        onlyNew: 0,
+        bothDisagree: 0,
+        bothEmpty: 0,
+        evidenceBreakdown: new Map(),
+    };
+}
+function tallyDiff(counts, diff) {
+    counts.totalCalls += 1;
+    incrementAgreement(counts, diff.agreement);
+    if (diff.agreement === 'both-agree' || diff.agreement === 'both-empty')
+        return;
+    for (const ev of diff.evidenceDelta) {
+        counts.evidenceBreakdown.set(ev.kind, (counts.evidenceBreakdown.get(ev.kind) ?? 0) + 1);
+    }
+}
+function incrementAgreement(counts, agreement) {
+    switch (agreement) {
+        case 'both-agree':
+            counts.bothAgree += 1;
+            return;
+        case 'only-legacy':
+            counts.onlyLegacy += 1;
+            return;
+        case 'only-new':
+            counts.onlyNew += 1;
+            return;
+        case 'both-disagree':
+            counts.bothDisagree += 1;
+            return;
+        case 'both-empty':
+            counts.bothEmpty += 1;
+            return;
+    }
+}
+function buildRow(language, counts) {
+    const resolved = counts.totalCalls - counts.bothEmpty;
+    const parity = resolved > 0 ? counts.bothAgree / resolved : 0;
+    return {
+        language,
+        totalCalls: counts.totalCalls,
+        bothAgree: counts.bothAgree,
+        onlyLegacy: counts.onlyLegacy,
+        onlyNew: counts.onlyNew,
+        bothDisagree: counts.bothDisagree,
+        bothEmpty: counts.bothEmpty,
+        parity,
+        // Freeze via `new Map` on a sorted-kind copy so downstream consumers
+        // can't mutate the aggregator's internal state.
+        evidenceBreakdown: new Map(Array.from(counts.evidenceBreakdown.entries()).sort(([a], [b]) => a.localeCompare(b))),
+    };
+}
+function buildOverallRow(perLanguage) {
+    let totalCalls = 0;
+    let bothAgree = 0;
+    let onlyLegacy = 0;
+    let onlyNew = 0;
+    let bothDisagree = 0;
+    let bothEmpty = 0;
+    for (const row of perLanguage) {
+        totalCalls += row.totalCalls;
+        bothAgree += row.bothAgree;
+        onlyLegacy += row.onlyLegacy;
+        onlyNew += row.onlyNew;
+        bothDisagree += row.bothDisagree;
+        bothEmpty += row.bothEmpty;
+    }
+    const resolved = totalCalls - bothEmpty;
+    const parity = resolved > 0 ? bothAgree / resolved : 0;
+    return { totalCalls, bothAgree, onlyLegacy, onlyNew, bothDisagree, bothEmpty, parity };
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/_shared/scope-resolution/shadow/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../../../src/scope-resolution/shadow/aggregate.ts"],"names":[],"mappings":"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"}

package/dist/_shared/scope-resolution/shadow/diff.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shadow-mode diff logic — RFC §6.3.
+ *
+ * Pure comparison logic for shadow mode. Takes two `Resolution[]` (legacy
+ * DAG result + new scope-based registry result) and produces a structured
+ * diff record for the parity dashboard.
+ *
+ * Consumed by the Ring 2 PKG shadow harness (#923), which dual-runs each
+ * call through legacy + new paths, diffs results, and persists per-run JSON
+ * for the parity dashboard.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #918.
+ */
+import type { Resolution, ResolutionEvidence } from '../types.js';
+export type ShadowAgreement = 'both-agree' | 'only-legacy' | 'only-new' | 'both-disagree' | 'both-empty';
+export interface ShadowDiff {
+    readonly callsite: ShadowCallsite;
+    readonly legacy: Resolution | null;
+    readonly newResult: Resolution | null;
+    readonly agreement: ShadowAgreement;
+    /**
+     * Symmetric difference of the two top resolutions' `evidence` arrays,
+     * keyed on `ResolutionEvidence.kind`.
+     *
+     * - For `'both-agree'` and `'both-empty'` agreements, always empty.
+     * - For `'both-disagree'`, contains evidence kinds present on exactly one
+     *   side (not in both).
+     * - For `'only-legacy'`, contains all of legacy's top evidence.
+     * - For `'only-new'`, contains all of new's top evidence.
+     */
+    readonly evidenceDelta: readonly ResolutionEvidence[];
+}
+export interface ShadowCallsite {
+    readonly filePath: string;
+    readonly line: number;
+    readonly col: number;
+    readonly calledName: string;
+}
+/**
+ * Compare two `Resolution[]` arrays (top matches at `[0]`) and produce a
+ * `ShadowDiff`. Pure function.
+ *
+ * Agreement rules:
+ * - both arrays empty → `'both-empty'`, `evidenceDelta: []`
+ * - legacy empty, new non-empty → `'only-new'`, `evidenceDelta` = new's top evidence
+ * - legacy non-empty, new empty → `'only-legacy'`, `evidenceDelta` = legacy's top evidence
+ * - both non-empty, same top `def.nodeId` → `'both-agree'`, `evidenceDelta: []`
+ * - both non-empty, different top `def.nodeId` → `'both-disagree'`,
+ *   `evidenceDelta` = symmetric difference by `ResolutionEvidence.kind`
+ *   (first occurrence of a kind-only-on-legacy then kind-only-on-new; order
+ *   preserved from input arrays)
+ *
+ * Evidence-delta rationale: callers aggregating divergences want to know
+ * which signal kinds explain a disagreement. Keying on `kind` (not full
+ * equality over `weight`/`note`) avoids spurious deltas when the same
+ * signal fires with slightly different calibration weights on each side.
+ */
+export declare function diffResolutions(callsite: ShadowCallsite, legacy: readonly Resolution[], newResult: readonly Resolution[]): ShadowDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/_shared/scope-resolution/shadow/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/scope-resolution/shadow/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIlE,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,aAAa,GACb,UAAU,GACV,eAAe,GACf,YAAY,CAAC;AAEjB,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,SAAS,EAAE,SAAS,UAAU,EAAE,GAC/B,UAAU,CAoBZ"}

package/dist/_shared/scope-resolution/shadow/diff.js

@@ -0,0 +1,79 @@
+/**
+ * Shadow-mode diff logic — RFC §6.3.
+ *
+ * Pure comparison logic for shadow mode. Takes two `Resolution[]` (legacy
+ * DAG result + new scope-based registry result) and produces a structured
+ * diff record for the parity dashboard.
+ *
+ * Consumed by the Ring 2 PKG shadow harness (#923), which dual-runs each
+ * call through legacy + new paths, diffs results, and persists per-run JSON
+ * for the parity dashboard.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #918.
+ */
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Compare two `Resolution[]` arrays (top matches at `[0]`) and produce a
+ * `ShadowDiff`. Pure function.
+ *
+ * Agreement rules:
+ * - both arrays empty → `'both-empty'`, `evidenceDelta: []`
+ * - legacy empty, new non-empty → `'only-new'`, `evidenceDelta` = new's top evidence
+ * - legacy non-empty, new empty → `'only-legacy'`, `evidenceDelta` = legacy's top evidence
+ * - both non-empty, same top `def.nodeId` → `'both-agree'`, `evidenceDelta: []`
+ * - both non-empty, different top `def.nodeId` → `'both-disagree'`,
+ *   `evidenceDelta` = symmetric difference by `ResolutionEvidence.kind`
+ *   (first occurrence of a kind-only-on-legacy then kind-only-on-new; order
+ *   preserved from input arrays)
+ *
+ * Evidence-delta rationale: callers aggregating divergences want to know
+ * which signal kinds explain a disagreement. Keying on `kind` (not full
+ * equality over `weight`/`note`) avoids spurious deltas when the same
+ * signal fires with slightly different calibration weights on each side.
+ */
+export function diffResolutions(callsite, legacy, newResult) {
+    const legacyTop = legacy.length > 0 ? legacy[0] : null;
+    const newTop = newResult.length > 0 ? newResult[0] : null;
+    const agreement = (() => {
+        if (legacyTop === null && newTop === null)
+            return 'both-empty';
+        if (legacyTop === null)
+            return 'only-new';
+        if (newTop === null)
+            return 'only-legacy';
+        return legacyTop.def.nodeId === newTop.def.nodeId ? 'both-agree' : 'both-disagree';
+    })();
+    const evidenceDelta = computeEvidenceDelta(legacyTop, newTop, agreement);
+    return {
+        callsite,
+        legacy: legacyTop,
+        newResult: newTop,
+        agreement,
+        evidenceDelta,
+    };
+}
+// ─── Internal helpers ───────────────────────────────────────────────────────
+/**
+ * Symmetric difference of two evidence arrays, keyed on
+ * `ResolutionEvidence.kind`. Preserves input order: legacy-only signals
+ * first (in legacy's original order), then new-only signals (in new's order).
+ *
+ * For `'both-agree'` / `'both-empty'` the delta is empty by contract. For
+ * `'only-legacy'` / `'only-new'` one side's evidence is the delta (nothing to
+ * subtract against).
+ */
+function computeEvidenceDelta(legacy, newResult, agreement) {
+    if (agreement === 'both-agree' || agreement === 'both-empty')
+        return [];
+    if (agreement === 'only-legacy')
+        return legacy.evidence;
+    if (agreement === 'only-new')
+        return newResult.evidence;
+    // both-disagree: symmetric difference keyed on `kind`
+    const legacyKinds = new Set(legacy.evidence.map((e) => e.kind));
+    const newKinds = new Set(newResult.evidence.map((e) => e.kind));
+    const onlyInLegacy = legacy.evidence.filter((e) => !newKinds.has(e.kind));
+    const onlyInNew = newResult.evidence.filter((e) => !legacyKinds.has(e.kind));
+    return [...onlyInLegacy, ...onlyInNew];
+}
+//# sourceMappingURL=diff.js.map

package/dist/_shared/scope-resolution/shadow/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/scope-resolution/shadow/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsCH,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAwB,EACxB,MAA6B,EAC7B,SAAgC;IAEhC,MAAM,SAAS,GAAsB,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,MAAM,MAAM,GAAsB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7E,MAAM,SAAS,GAAoB,CAAC,GAAG,EAAE;QACvC,IAAI,SAAS,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QAC/D,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,UAAU,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,aAAa,CAAC;QAC1C,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC;IACrF,CAAC,CAAC,EAAE,CAAC;IAEL,MAAM,aAAa,GAAG,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAEzE,OAAO;QACL,QAAQ;QACR,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,MAAM;QACjB,SAAS;QACT,aAAa;KACd,CAAC;AACJ,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAC3B,MAAyB,EACzB,SAA4B,EAC5B,SAA0B;IAE1B,IAAI,SAAS,KAAK,YAAY,IAAI,SAAS,KAAK,YAAY;QAAE,OAAO,EAAE,CAAC;IACxE,IAAI,SAAS,KAAK,aAAa;QAAE,OAAO,MAAO,CAAC,QAAQ,CAAC;IACzD,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,SAAU,CAAC,QAAQ,CAAC;IAEzD,sDAAsD;IACtD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEjE,MAAM,YAAY,GAAG,MAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,MAAM,SAAS,GAAG,SAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE9E,OAAO,CAAC,GAAG,YAAY,EAAE,GAAG,SAAS,CAAC,CAAC;AACzC,CAAC"}

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

@@ -42,6 +42,142 @@ export interface Capture {
     /** The captured source text. */
     readonly text: string;
 }
+/**
+ * A grouping of `Capture`s that came from a single query match (e.g., one
+ * `@import.statement` match carries `@import.source`, `@import.name`,
+ * `@import.alias?` as child captures). Keyed by capture name for O(1)
+ * child access.
+ */
+export type CaptureMatch = Readonly<Record<string, Capture>>;
+/**
+ * Provider-interpreted raw import, consumed by finalize (Phase 2) to produce
+ * linked `ImportEdge[]`. The provider's `interpretImport` hook turns a
+ * `CaptureMatch` for an `@import.statement` into one of these; the central
+ * finalize algorithm resolves `targetRaw` to a concrete file via
+ * `resolveImportTarget` and materializes the final `ImportEdge`.
+ *
+ * Discriminated union — each variant carries only the fields that make sense
+ * for its kind. Invalid shapes (e.g., a `namespace` import with an alias-like
+ * `importedName` mismatch) are compile errors, not latent bugs. `'wildcard-
+ * expanded'` is deliberately NOT a variant: that kind is finalize output only,
+ * produced when `expandsWildcardTo` materializes a wildcard against target
+ * exports — a provider must never emit it at parse time.
+ */
+export type ParsedImport = 
+/**
+ * Per-name import without rename.
+ *
+ * Examples:
+ *   - Python `from foo import X`   → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: 'foo' }`
+ *   - TS `import { X } from './foo'` → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: './foo' }`
+ *   - Java `import foo.bar.X`       → `{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: 'foo.bar' }`
+ */
+{
+    readonly kind: 'named';
+    readonly localName: string;
+    readonly importedName: string;
+    readonly targetRaw: string;
+}
+/**
+ * Per-name import with rename.
+ *
+ * Examples:
+ *   - Python `from foo import X as Y`   → `{ kind: 'alias', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: 'foo' }`
+ *   - TS `import { X as Y } from './foo'` → `{ kind: 'alias', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: './foo' }`
+ */
+ | {
+    readonly kind: 'alias';
+    readonly localName: string;
+    readonly importedName: string;
+    readonly alias: string;
+    readonly targetRaw: string;
+}
+/**
+ * Qualified module handle, with or without rename. `importedName` is the
+ * module being aliased; `localName` is the scope-visible handle (often the
+ * same unless renamed).
+ *
+ * Examples:
+ *   - Python `import numpy`            → `{ kind: 'namespace', localName: 'numpy', importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - Python `import numpy as np`      → `{ kind: 'namespace', localName: 'np',    importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - TS `import * as np from 'numpy'` → `{ kind: 'namespace', localName: 'np',    importedName: 'numpy', targetRaw: 'numpy' }`
+ *   - Go `import foo "pkg/bar"`        → `{ kind: 'namespace', localName: 'foo',   importedName: 'bar',   targetRaw: 'pkg/bar' }`
+ */
+ | {
+    readonly kind: 'namespace';
+    /** Scope-visible handle (e.g. `np` in `import numpy as np`; `numpy` when unaliased). */
+    readonly localName: string;
+    /** Module being aliased (e.g. `numpy` in `import numpy as np`). */
+    readonly importedName: string;
+    readonly targetRaw: string;
+}
+/**
+ * Syntactically-detectable parse-time re-export. Finalize may still produce
+ * `ImportEdge { kind: 'reexport', transitiveVia }` when flattening chains;
+ * this variant preserves the *parse-time* signal so finalize doesn't have
+ * to re-derive it from scratch.
+ *
+ * Examples:
+ *   - TS `export { X } from './y'`       → `{ kind: 'reexport', localName: 'X', importedName: 'X', targetRaw: './y' }`
+ *   - TS `export { X as Y } from './y'`  → `{ kind: 'reexport', localName: 'Y', importedName: 'X', alias: 'Y', targetRaw: './y' }`
+ *   - Rust `pub use foo::bar`            → `{ kind: 'reexport', localName: 'bar', importedName: 'bar', targetRaw: 'foo' }`
+ */
+ | {
+    readonly kind: 'reexport';
+    /** Name as re-exported in the current module. */
+    readonly localName: string;
+    /** Name in the source module. */
+    readonly importedName: string;
+    readonly targetRaw: string;
+    /** Set when the re-export renames the symbol (e.g. `export { X as Y } from './y'`). */
+    readonly alias?: string;
+}
+/**
+ * Runtime-computed target — the import path is not a static literal at
+ * parse time. Providers SHOULD emit the unresolvable expression's source
+ * text as `targetRaw` to aid diagnostics; `null` only when no string form
+ * exists.
+ *
+ * Examples:
+ *   - JS `await import(expr)`                          → `{ kind: 'dynamic-unresolved', localName: '', targetRaw: 'expr' }`
+ *   - Python `importlib.import_module(f'pkg.{name}')`  → `{ kind: 'dynamic-unresolved', localName: '', targetRaw: "f'pkg.{name}'" }`
+ */
+ | {
+    readonly kind: 'dynamic-unresolved';
+    readonly localName: string;
+    /** Source text of the unresolved expression when available; `null` otherwise. */
+    readonly targetRaw: string | null;
+};
+/**
+ * Provider-interpreted type binding. The provider's `interpretTypeBinding`
+ * hook turns a `CaptureMatch` (e.g., `@type-binding.parameter`) into one of
+ * these; the central extractor attaches the resulting `TypeRef` to the
+ * appropriate scope's `typeBindings` map.
+ */
+export interface ParsedTypeBinding {
+    /** The name being bound (parameter name, `self`, assignment LHS, …). */
+    readonly boundName: string;
+    /** The raw type name as written in source (`'User'`, `'models.User'`, …). */
+    readonly rawTypeName: string;
+    readonly source: TypeRef['source'];
+}
+/**
+ * Cross-file workspace index consumed by finalize-phase hooks
+ * (`resolveImportTarget`, `expandsWildcardTo`). Opaque placeholder in Ring 1;
+ * concretely typed in Ring 2 SHARED (#915).
+ */
+export type WorkspaceIndex = unknown;
+/**
+ * Scope tree handle consumed by parse-phase hooks (`bindingScopeFor`,
+ * `importOwningScope`) to navigate the in-progress scope tree. Opaque
+ * placeholder in Ring 1; concretely typed in Ring 2 SHARED (#912).
+ */
+export type ScopeTree = unknown;
+/** Call-site description passed to `arityCompatibility`. */
+export interface Callsite {
+    /** Number of arguments at the call site. */
+    readonly arity: number;
+}
 /**
  * A cross-file import edge attached to a module/namespace scope.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}

package/dist/core/ingestion/language-provider.d.ts

@@ -8,7 +8,7 @@
  * The providers table in `languages/index.ts` uses `satisfies Record<SupportedLanguages, LanguageProvider>`
  * so adding a language to the enum without creating a provider is a compiler error.
  */
-import type { SupportedLanguages, MroStrategy } from '../../_shared/index.js';
+import type { SupportedLanguages, MroStrategy, Capture, CaptureMatch, BindingRef, TypeRef, Scope, ScopeId, ScopeKind, ScopeTree, ParsedImport, ParsedTypeBinding, SymbolDefinition, Callsite, WorkspaceIndex } from '../../_shared/index.js';
 import type { LanguageTypeConfig } from './type-extractors/types.js';
 import type { CallRouter } from './call-routing.js';
 import type { CallExtractor, DispatchDecision, ImplicitReceiverOverride, ReceiverEnriched } from './call-types.js';
@@ -222,6 +222,177 @@ interface LanguageProviderConfig {
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;
+    /**
+     * Emit scope captures from raw source. Tree-sitter-based providers run a
+     * `scopes.scm` query; standalone providers (COBOL) emit captures from a
+     * regex tagger. The return shape is parser-agnostic: the central
+     * `ScopeExtractor` consumes `Capture[]` without knowing which parser
+     * produced them.
+     *
+     * Required for any provider participating in scope-based resolution.
+     * Providers that have not yet migrated continue to run through the legacy
+     * DAG path (feature-flagged per `REGISTRY_PRIMARY_<LANG>`).
+     *
+     * Default: undefined (language continues to use legacy DAG).
+     */
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => Promise<readonly Capture[]>;
+    /**
+     * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
+     * The central finalize algorithm resolves `ParsedImport.targetRaw` to a
+     * concrete file via `resolveImportTarget` and materializes the final
+     * `ImportEdge` with `targetModuleScope` / `targetDefId` filled in.
+     *
+     * Required when `emitScopeCaptures` is implemented.
+     */
+    readonly interpretImport?: (captures: CaptureMatch) => ParsedImport | null;
+    /**
+     * What is the implicit receiver on a Function scope? For instance methods
+     * this is `self`/`this`; for standalone functions it is `null`. Consulted
+     * by `Registry.lookup` Step 2 via the `resolveTypeRef` helper.
+     *
+     * Required for any language with method dispatch (OO semantics).
+     *
+     * Default: undefined (treated as `null` — no implicit receiver).
+     */
+    readonly receiverBinding?: (functionScope: Scope) => TypeRef | null;
+    /**
+     * Interpret a raw type-binding capture (parameter annotation, `self`,
+     * assignment with constructor RHS, …) into a `ParsedTypeBinding`. The
+     * central extractor attaches the resulting `TypeRef` to the appropriate
+     * scope's `typeBindings` map.
+     *
+     * Default: undefined (falls back to `{ boundName: captures.name, rawTypeName: captures.type, source: 'annotation' }`).
+     */
+    readonly interpretTypeBinding?: (captures: CaptureMatch) => ParsedTypeBinding | null;
+    /**
+     * Override the `ScopeKind` assigned to a scope capture. Use when the
+     * capture name alone can't resolve the kind (e.g., tree-sitter captures
+     * a `block` that is semantically an `Expression` in this language).
+     *
+     * Default: undefined (the central extractor uses the capture name's
+     * suffix — `@scope.function` → `'Function'`, etc.).
+     */
+    readonly resolveScopeKind?: (captures: CaptureMatch) => ScopeKind | null;
+    /**
+     * Should this scope capture materialize as a real `Scope` node? Return
+     * `false` to skip scope creation while still emitting declarations that
+     * would have gone inside (they attach to the enclosing real scope).
+     *
+     * Example: Python `if`/`for`/`while` bodies capture as `@scope.block` but
+     * Python has no block scope — hook returns `false` and child declarations
+     * lift to the enclosing function/module.
+     *
+     * Default: undefined (treated as `true` — always create).
+     */
+    readonly shouldCreateScope?: (captures: CaptureMatch) => boolean;
+    /**
+     * Override where a declaration's name becomes visible. By default the name
+     * is bound in the innermost enclosing scope; return a different `ScopeId`
+     * to hoist it (JS `var` → enclosing function scope; Ruby `def` inside
+     * `begin` → enclosing class scope).
+     *
+     * Return `null` to delegate to the central default (innermost enclosing
+     * scope). This matches the `X | null` convention used by the other optional
+     * hooks and supports partial overrides — e.g., a JS provider can return a
+     * hoisted scope for `var` declarations and `null` for `let`/`const`, without
+     * re-implementing the default lookup.
+     *
+     * **Purity:** must be a pure function of its inputs — same parameters must
+     * yield the same `ScopeId` (or `null`) across invocations. No closure over
+     * mutable state. Required so scope-tree construction stays deterministic
+     * across re-parses.
+     *
+     * Default: undefined (the central extractor uses `innermostScope.id`).
+     */
+    readonly bindingScopeFor?: (declCapture: CaptureMatch, innermostScope: Scope, scopeTree: ScopeTree) => ScopeId | null;
+    /**
+     * Resolve a `ParsedImport.targetRaw` expression to a concrete file path in
+     * the workspace. Language-specific resolution: Python relative imports,
+     * JS package.json + node_modules, Go module paths, Java classpath,
+     * COBOL COPY paths. Ports today's per-language import resolver.
+     *
+     * Required when `emitScopeCaptures` is implemented. Ring 2 PKG #922
+     * provides the adapter that bridges today's resolver shape to this hook.
+     */
+    readonly resolveImportTarget?: (parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex) => string | null;
+    /**
+     * Enumerate the exported names of a file — used by the finalize algorithm
+     * to expand `import * from M` into individual `BindingRef`s with
+     * `origin: 'wildcard'`.
+     *
+     * Default: undefined (central finalize walks the target file's
+     * `ExportMap.keys()`).
+     */
+    readonly expandsWildcardTo?: (targetFile: string, workspaceIndex: WorkspaceIndex) => readonly string[];
+    /**
+     * Decide the scope to which a `ParsedImport` attaches. Most languages
+     * attach imports to the nearest enclosing `Module`/`Namespace` scope
+     * (the default); some languages allow local imports (Python function-local
+     * `from x import Y`, Rust fn-local `use`, TS dynamic `import()`) — return
+     * a `Function`/`Block` scope id instead.
+     *
+     * Return `null` to delegate to the central default (nearest enclosing
+     * `Module`/`Namespace`). This matches the `X | null` convention used by
+     * the other optional hooks and supports partial overrides — a provider
+     * that handles only specific import forms non-standardly can `return null`
+     * for the common cases and let the central walk handle them.
+     *
+     * **Purity:** must be a pure function of its inputs — same parameters must
+     * yield the same `ScopeId` (or `null`) across invocations. No closure over
+     * mutable state. Required so scope-tree construction stays deterministic
+     * across re-parses.
+     *
+     * Default: undefined (central finalize walks to the nearest enclosing
+     * `Module` or `Namespace` scope).
+     */
+    readonly importOwningScope?: (parsedImport: ParsedImport, innermostScope: Scope, scopeTree: ScopeTree) => ScopeId | null;
+    /**
+     * Merge local declarations and imported bindings for a single (scope, name)
+     * during finalize materialization of a scope's binding table. Language-
+     * specific precedence: Python local hides import; TypeScript namespace
+     * merging keeps both; Ruby constant resolution has its own rules.
+     *
+     * Default: undefined (central finalize uses local-first-then-imports,
+     * deduping by `DefId`).
+     */
+    readonly mergeBindings?: (scope: Scope, bindings: readonly BindingRef[]) => readonly BindingRef[];
+    /**
+     * Classify a `@reference.call` capture as free / member / constructor /
+     * index. Preferred path is declarative via capture sub-tags
+     * (`@reference.call.free`, etc.); this hook handles the languages where
+     * call form can't be decided statically (Ruby bare `foo(x)` is free-or-
+     * member until resolved).
+     *
+     * Default: undefined (central extractor reads capture sub-tag if present;
+     * else treats as `'free'`).
+     */
+    readonly classifyCallForm?: (captures: CaptureMatch, enclosingScope: Scope) => 'free' | 'member' | 'constructor' | 'index';
+    /**
+     * Does a binding at this scope shadow bindings of the same name in outer
+     * scopes? Default: any binding shadows (standard lexical scoping). Return
+     * `false` for transparent-scope edge cases (Python `from x import *`
+     * contexts, JS `var` hoisting quirks, COBOL PARAGRAPH transparency).
+     *
+     * Consulted by `Registry.lookup` Step 1 and by `resolveTypeRef` for
+     * shadowing decisions during the lexical chain walk.
+     *
+     * Default: undefined (treated as `true` — any binding shadows).
+     */
+    readonly shouldShadow?: (scope: Scope, bindings: readonly BindingRef[]) => boolean;
+    /**
+     * Is this callable definition compatible with the given call-site arity?
+     * Language-specific rules: Python `*args`/`**kwargs`/defaults, JS default
+     * params + rest, Kotlin vararg + defaults, Ruby optional/splat/block, Go
+     * straight counts, Rust no-variadic-no-defaults.
+     *
+     * `'incompatible'` is a soft penalty (−0.15 per EvidenceWeights) and is
+     * filtered only when at least one `'compatible'` candidate exists;
+     * otherwise the incompatible candidate is kept with the penalty so the
+     * call-site still links to a best-guess target.
+     *
+     * Default: undefined (treated as `'unknown'` — no signal either way).
+     */
+    readonly arityCompatibility?: (def: SymbolDefinition, callsite: Callsite) => 'compatible' | 'unknown' | 'incompatible';
 }
 /** Runtime type — same as LanguageProviderConfig but with defaults guaranteed present. */
 export interface LanguageProvider extends Omit<LanguageProviderConfig, 'importSemantics' | 'heritageDefaultEdge' | 'mroStrategy'> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.2",
+  "version": "1.6.3-rc.4",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",